The Battle for Wesnoth Wiki - User contributions [en]

AbilitiesWML

2026-02-07T19:47:16Z

Jarom: Added a note about ability keys inside weapon specials used as abilities

{{WML Tags}}
== Abilities and their effects ==

There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials.

Each ability or special defines an effect based on one to three units. Most abilities apply to a single unit, and '''[filter_self]''' can be used to determine when the ability is active. Weapon specials apply to two units, which can be filtered either as "attacker" and "defender" (with the obvious meaning) or as "self" and "other" – the unit that possesses the special, and that unit's opponent. When filtering on the "other" unit, you use '''[filter_opponent]'''.

Leadership-style abilities are a more complex case, as they involve three units. Like a weapon special, there is an attacker and defender, but there is also a third unit that could be referred to as the "teacher". The "teacher" is the unit that possesses the ability, so it is referred to as "self" in the ability. A leadership ability works by temporarily granting a weapon special to either the attacker or the defender. The unit that benefits from this is referred to as the "student", while the unit that does not benefit is simply the "other" unit. When filtering on the "other" unit, you use '''[filter_opponent]''', while the student can be filtered with '''[filter_student]'''.

== The ''[abilities]'' tag ==

The following tags are used to describe an ability in WML:

* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn
* '''[resistance]''': modifies the resistance of a unit to damage
* '''[leadership]''': modifies the damage of a unit
* '''[skirmisher]''': negates enemy zones of control
* '''[illuminates]''': modifies the time of day adjacent to the affected units
* '''[teleport]''': allows the unit to teleport
* '''[hides]''': renders the unit invisible to enemies
* {{DevFeature1.15|0}} All [[#The_.5Bspecials.5D_tag|weapon specials]] except for '''[plague]''', '''[heal_on_hit]''', and '''[swarm]''' can be placed in the '''[abilities]''' tag. These [[#Extra_tags_and_keys_used_by_weapon_specials_as_abilities|"weapon specials as abilities"]] will give the weapon special to all attacks the unit has.
* '''[defense]''' {{DevFeature1.19|16}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' .
* Any other tag is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. '''Note:''' a dummy ability must have an id for the name and description to display.
* {{DevFeature1.15|3}} All the engine [[#The_.5Bspecials.5D_tag|weapon specials]] can be placed in the [abilities] tag now.

=== Available formula variables in Abilities and Weapon Specials ===

{{DevFeature1.15|?}} When using formulas in abilities and weapon specials, the following formula variables are available:
* '''self''': (unit) the unit that has the ability
* '''student''': (unit) for leadership-like abilities this is the unit that is adjacent to the unit that has the ability; if affect_self=yes, this is also unit who has ability.
* '''attacker''': (unit) for attack-related abilities and weapon specials, this is the attacking unit during the attack.
* '''defender''': (unit) for attack-related abilities and weapon specials, this is the defending unit during the attack.
* '''other''': (unit) the unit whose stats get modified from the ability. For abilities without 'apply_to=opponent' this is always the same as 'student'.

=== Common keys and tags for every ability ===

{{DevFeature1.13|?}} All keys inside any ability that expects a numeric value will also accept formulas using
[[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses. However, do '''not''' precede those parentheses with a dollar sign like <code>$(...)</code>, since that will erase the <tt>self</tt> variable.

* '''name''': the (translatable) name of the ability. If omitted, the ability will be a hidden ability.
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified. You should thus set ''female_name'' as well!
* '''description''': the (translatable) description of the ability.
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''affect_self''': if equal to 'yes' (default), the ability will affect the unit that has it.
* '''affect_allies''': if equal to 'yes', the ability will affect units from the same and allied sides in the specified adjacent hexes. If set to 'no' it will not affect own or allied sides. If not set (default) it will affect units on the same side but not from allied sides.
* '''affect_enemies''': if equal to 'yes' (default is 'no'), the ability will affect enemies in the specified adjacent hexes.
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this ability, used for the registry under [[UnitsWML#.5Babilities.5D|[units][abilities]]]. If not defined, falls back to '''id'''. Used to add this ability via '''abilities_list''' key in '''[unit_type]''' or '''[effect]apply_to=new_ability'''.
* '''halo_image''': {{DevFeature1.17|22}} if used, the halo specified showed on unit affected by ability.
* '''overlay_image''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit affected by ability.
* '''halo_image_self''': {{DevFeature1.17|22}} if used, the halo specified showed on unit who has ability when active.
* '''overlay_image_self''': {{DevFeature1.17|22}} if used, the overlay specified showed on unit who has ability when active.
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.
* {{anchor|affect_adjacent|'''[affect_adjacent]'''}}: an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. The side requirement of matching units is defined by the '''affect_allies''' and '''affect_enemies''' keys. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.
** '''radius''': {{DevFeature1.19|13}} set to 1 by default, it determines the range within which units can be affected beyond immediately adjacent units, if the value is equal to 'full-map', the area is the entire map.
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{anchor|filter_base_value|'''[filter_base_value]'''}}: filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this ability appears in. Note that such events get included when a unit with this ability first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].

=== Common keys and tags for abilities with a value ===

The '''[leadership]''', '''[heals]''', '''[regenerate]''',and '''[illuminates]''' abilities take values that specify how those abilities modify their respective base values.

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority ability to use as its base the value returned by a lower-priority ability of the same type; for example a negative priority will cause the value to be calculated before checking whether the mainline marksman ability should override it. The value is arbitrary, but generally -10 is chosen to allow for another (not yet known) ability to be placed in between the known ones. Default: 0.
* '''cumulative''': if set to 'yes', the [leadership] value will be added to another [leadership] value= same if have same id=, for other abilities, the highest value between value= or base_value will be chosen.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[heals]'' and ''[regenerate]'' abilities ===
* '''value''': the amount healed.
* '''poison''': When the healed unit is poisoned, then unit takes usual poison damage instead. Interaction with poison can be changed with these values:
** ''cured'' - stops poison damage and heals the poison instead of healing
** ''slowed'' - stops poison damage instead of healing

* Use common keys and tags for abilities with a value.

=== Extra keys and tags used by the ''[resistance]'' ability ===

* '''value''': set resistance to this value.
* '''max_value''': maximum resistance value. Default: 0%. {{DevFeature1.17|24}} Default: no limit.
* '''min_value''': {{DevFeature1.19|0}} minimum resistance value. Default: no limit.
* Use common keys and tags for abilities with a value
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the resistance ability only takes effect when the opponent uses a matching weapon.

=== Extra keys and tags used by the ''[defense]'' ability ===
* '''value''': set defense to this value. Warning, the chance to be hit decrease when value of ability increase.
* Use common keys and tags for abilities with a value

=== Extra keys used by the ''[leadership]'' ability ===

* '''value''': the percentage bonus to damage.
* Use common keys and tags for abilities with a value
''Note:'' cumulative leadership with '''cumulative=yes''' and '''value=''' doesn't work in 1.16 (but fixed in 1.17.12 and later). To work around use '''add=''' or '''sub=''' key (it doesn't require cumulative) (https://github.com/wesnoth/wesnoth/issues/6466 ). If you want each instance of a ''[leadership]'' with the same id to be added you will be able to reuse '''cumulative=yes''' in 1.17.12 and later, otherwise, if you want to add the value of another ''[leadership]'' only once even with the same id in several copies, use '''add'''.
* '''[filter_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the owner of the ability uses a matching weapon.
* '''[filter_second_weapon]''': {{DevFeature1.15|0}} If present, the leadership ability only takes effect when the opponent uses a matching weapon.

=== Extra keys used by the ''[illuminates]'' ability ===

Because this ability changes the terrain instead of units on it, affect_self, affect_allies, affect_enemies and [filter_adjacent] have no effect. If you use [affect_adjacent] the terrain under and adjacent to adjacent unit will be changed.
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* Use Common keys and tags for abilities with a value
* '''max_value''': the maximum percentage bonus given. Cannot be less than 0. Defaults to 0 if not present.
* '''min_value''': the minimum percentage bonus given. Cannot be greater than 0. Defaults to 0 if not present.
* '''radius''': {{DevFeature1.19|15}} defines the radius of the ability, by default only the terrain the user is on and adjacent hexes are affected, but this can now be extended to a radius defined by '''radius''' ; if '''radius'''=all_map then the whole map will be affected.

=== Extra keys used by the ''[hides]'' ability ===

* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".

=== Extra tags used by the ''[teleport]'' ability ===

* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the [tunnel][source] and [tunnel][target] tag for filtering purposes.

=== Extra tags and keys used by weapon specials as abilities ===

* {{anchor|filter_student|'''[filter_student]'''}}: {{DevFeature1.15|0}} If present, only the unit matching this filter, either the possessor of the ability if affect_self=yes, or an adjacent unit matching '''[filter_adjacent]''' will be affected.
* '''[filter_adjacent_student]''': {{DevFeature1.19|10}} if an adjacent unit to student does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_student]. The variables $this_unit and $other_unit both work as you'd expect. Multiple [filter_adjacent_student] can be provided, all of which must pass for the ability to activate.
** '''radius''': {{DevFeature1.19|13}} determines the distance of units that can be filtered and not just adjacent units, '''radius''' is set to 1 by default. {{DevFeature1.19|18}} '''[filter_adjacent_student]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''[filter_adjacent_student_location]''': {{DevFeature1.19|10}} like [filter_adjacent_student], but filters on locations instead of units. This is a shorthand for [filter_student][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''[filter_adjacent_student_location]''' is removed because having multiple shorthands requires giving them specific names for abilities used as weapons, and it's even simpler to use the [[StandardUnitFilter]].
* '''overwrite_specials''': {{DevFeature1.15|13}} If present, allows a special abilities weapon with a numerical value to impose its value and ignore values of abilities or specials of the same type. If '''overwrite_specials=one_side''', the specials and abilities used by the opponent of the unit affected by the ability with this key and applied to it will not be affected. If '''overwrite_specials=both_sides''', all non-key-carrying abilities and all specials of the same type affecting the recipient unit will be affected, even if used by the opponent (used in the macro FORCE_CHANCE_TO_HIT).
* {{anchor|overwrite|'''[overwrite]'''}}: {{DevFeature1.17|22}} Part of '''overwrite_specials'''. Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** {{anchor|filter_specials|'''[experimental_filter_specials]'''}}: [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability].
** '''description_affected''': {{DevFeature1.17|13}} becomes the '''description''' of the weapon special, without changing the '''description''' of the ability
** '''name_affected''': {{DevFeature1.17|13}} becomes the '''name''' of the weapon special, without changing the '''name''' of the ability
* Other keys and tags appropriate to the specific weapon special.

=== Macros for common abilities ===

[https://www.wesnoth.org/macro-reference.html#file:abilities.cfg macro reference]
* ABILITY_AMBUSH
* ABILITY_CURES
* ABILITY_HEALS
* ABILITY_ILLUMINATES
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)
* ABILITY_NIGHTSTALK
* ABILITY_REGENERATES
* ABILITY_SKIRMISHER
* ABILITY_STEADFAST
* ABILITY_SUBMERGE
* ABILITY_TELEPORT

== The ''[specials]'' tag ==

The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:

* '''[attacks]''': modifies the number of attacks of a weapon, in using '''value''', '''add''', '''sub''', '''multiply''' or '''divide''' attributes
* '''[berserk]''': pushes the attack for more than one combat round, using '''value''' attribute, '''value''' is 1 by default
* '''[chance_to_hit]''': modifies the chance to hit of a weapon, using same standard numerical attributes as '''[attacks]'''
* '''[damage]''': modifies the damage of a weapon, using same attributes as '''[attacks]''' and '''[chance_to_hit]'''
* '''[damage_type]''' {{DevFeature1.17|23}}: changes the damage type of a weapon
* '''[defense]''' {{DevFeature1.19|15}}: modifies the chances of being hit by the opponent's weapon, this value can be modified by the parry attribute, the accuracy attribute of the opponent's weapon, or by their special weapon '''[chance_to_hit]'''. Be careful, the more you increase the value, the less chance the opponent has of hitting you. Using same standard numerical attributes as '''[attacks]''' {{DevFeature1.19|16}} [defense] is no longer a weapon special but an ability.
* '''[disable]''': disables the weapon
* '''[drains]''': heals the attacker '''value''' percentage of the damage dealt, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 50 by default
* '''[firststrike]''': forces the weapon to always strike first
* '''[heal_on_hit]''': heals the attacker when an attack connects, using same attributes as '''[attacks]''' and '''[chance_to_hit]''', '''value''' is 0 by default
* '''[petrifies]''': turns the target to stone
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place
* '''[poison]''': poisons the target
* '''[slow]''': slows the target
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints
Any other tag is valid, but will result in a special that does nothing but report it is there.

=== Common keys and tags for every weapon special ===

{{DevFeature1.13|?}} All keys inside any weapon special that expects a numeric value will also accept formulas using [[Wesnoth Formula Language]]. In order to use a formula in these keys, you must enclose it in parentheses.

* '''name''': the (translatable) name of the special. If omitted, the special will be hidden from the player.
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).
* '''description''': the (translatable) description of the special.
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.
* '''special_note''' {{DevFeature1.15|14}} Translatable string, which will be displayed in the unit’s help. See also [[UnitTypeWML#Special_Notes]].
* '''id''': this ability will not be cumulative with other specials using this id.
* '''unique_id''': {{DevFeature1.19|18}} A unique identifier for this weapon special, used for the registry under [[UnitsWML#.5Bweapon_specials.5D|[units][weapon_specials]]]. If not defined, falls back to '''id'''. Used to add this weapon special via '''[unit_type][attack]specials_list''', or via [[EffectWML]].
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its effects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate. {{DevFeature1.19|18}} '''filter_adjacent''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]] and ''count'' is no longer required.
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location]. {{DevFeature1.19|18}} '''filter_adjacent_location''' is deprecated and will likely be removed in version 1.21, since a version already exists in the [[StandardUnitFilter]].
* {{anchor|filter_self|'''[filter_self]'''}}: the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.
* {{anchor|filter_opponent|'''[filter_opponent]'''}}: the special will only be active if the opponent matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.
* {{anchor|filter_attacker|'''[filter_attacker]'''}}: the special will only be active if the attacker matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.
* {{anchor|filter_defender|'''[filter_defender]'''}} the special will only be active if the defender matches this SUF.
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.
* '''overwrite_specials''': if equal to 'one_side', then only this unit's specials are evaluated. If equal to 'both_sides', then both this unit's specials and any of the opponent's weapon specials that affect this unit are evaluated. If a special with this attribute is active, it will take precedence over any other specials of the same type that do not have this attribute. Don't applied to boolean weapon special like [poison] ,[slow], [firststrike] or [petrifies].
* '''[overwrite]''': {{DevFeature1.17|22}} Allows more flexibility in determining which specials should take priority over other specials of the same type.
** '''priority''': A numeric value to use when determining which special should be used if multiple specials of the same type have the '''overwrite_specials''' attribute. Default is 0.
** '''[experimental_filter_specials]''': [[StandardAbilityFilter]] Further attributes to filter specials by to determine if it should take priority over other specials. Accepts the same attributes as [experimental_filter_ability], {{DevFeature1.19|5}} [experimental_filter_specials] deprecated, use [filter_specials] instead.
* '''[event]''': [[EventWML]]. {{DevFeature1.19|4}} An [event] to be included into any scenario where a unit with this weapon special appears in. Note that such events get included when a unit with this weapon special first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[WML_Abilities|WML Abilities]]. Shortcut of [unit_type][event].
* {{DevFeature1.15|3}} When used inside '''[abilities]''' tag, relevant ability keys can also be used (see above).

=== Common keys and tags for specials with a value ===

The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).

* '''value''': the value to be used. Available inside translatable strings as '''$value'''.
* '''add''': the number to add to the base value. Note the interaction with '''sub''' in [[#Common_calculations]]. Available inside translatable strings as '''$add'''.
* '''sub''': the number to subtract from the base value. Available inside translatable strings as '''$sub'''.
* '''multiply''': this multiplies the base value. Available inside translatable strings as '''$multiply'''.
* '''divide''': this divides the base value. Available inside translatable strings as '''$divide'''.
* '''max_value''': {{DevFeature1.19|2}} maximum special value. Default: no limit. Available inside translatable strings as '''$max_value'''.
* '''min_value''': {{DevFeature1.19|2}} minimum special value. Default: no limit. Available inside translatable strings as '''$min_value'''.
* '''priority''': {{DevFeature1.19|19}} This attribute allows a higher-priority special to use as its base the value returned by a lower-priority special of the same type. Default: 0.
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', '''less_than''', '''greater_than''', '''less_than_equal_to''', '''greater_than_equal_to'''.

==== Common calculations ====

Several abilities and weapon specials take the keys '''add''', '''sub''', '''multiply''' and '''divide'''.

{{DevFeature1.19|4}} '''add''' and '''sub''' work independently.

Prior to 1.19.4:

* If '''add''' and '''sub''' are used in the same ability, the '''add''' is ignored
* If '''add''' and '''sub''' are used in separate abilities with the same id, or with the default id that's used when no id is specified, then the order in which the abilities are encountered controls the calculation, which may change depending on units' positions on the map.

=== Extra keys used by the ''[damage_type]'' special ===

{{DevFeature1.17|23}}

* '''replacement_type''': replaces the attack type with the specified type when [damage_type] is active.
* '''alternative_type''': add a second type of attack to the existing type, it is always the one of the two which will do the most damage to the opponent which will be used.

'''Note:''' In 1.18, alternative_type may be stronger than expected, as the damage calculations sometimes ignore [resistance] abilities. This is a known bug, which occurs deterministically and will be left unfixed in 1.18.x to prevent Out Of Sync errors.

'''Note:''' If a [damage_type] special includes a [filter_weapon]type=, that filter is tested against the base type of the weapon, ignoring all [damage_type] specials.

=== Extra keys used by the ''[berserk]'' special ===

* '''value''': the maximum number of combat rounds (default 1).
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).

=== Extra keys used by the ''[plague]'' special ===

* '''type''': the unit type to be spawned on kill. When not specified, the default is the unit type of the unit doing the plaguing. This value can be used via the PO variable '''$type''' inside translatable string keys, such as '''description'''.

=== Extra keys used by the ''[swarm]'' special ===

* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.

Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].

=== Macros for common weapon specials ===

[https://www.wesnoth.org/macro-reference.html#file:weapon_specials.cfg macro reference]
* WEAPON_SPECIAL_BACKSTAB
* WEAPON_SPECIAL_BERSERK
* WEAPON_SPECIAL_CHARGE
* WEAPON_SPECIAL_DRAIN
* WEAPON_SPECIAL_FIRSTSTRIKE
* WEAPON_SPECIAL_MAGICAL
* WEAPON_SPECIAL_MARKSMAN
* WEAPON_SPECIAL_PLAGUE
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE
* WEAPON_SPECIAL_POISON
* WEAPON_SPECIAL_SLOW
* WEAPON_SPECIAL_STONE
* WEAPON_SPECIAL_SWARM

== See Also ==

* [[UnitTypeWML]]
* [[SingleUnitWML]]
* [[ReferenceWML]]

[[Category:WML Reference]]

OptionWML

2024-09-04T19:29:24Z

Jarom: choice as primary tag name

{{WML Tags}}
== The [options] tag ==

This tag might be a child of an [[EraWML|[era]]], [[ScenarioWML#The_.5Bmultiplayer.5D_tag|[multiplayer]]] or [[ModificationWML|[modification]]] tag. {{DevFeature1.13|1}} [options] are now also recognised in a [[CampaignWML|[campaign]]] tag. Its subtags describe a set of configuration options which are displayed to the user as widgets on the game creation screen, and the entered values are translated into WML variables in the game. The created variables' name is identical to the option's id they're attached to, so option IDs must be valid variable names and unique across all kinds of options. A good idea might be to prefix the addon ID.

The following subtags are recognized for '''[options]''':

* {{anchor|checkbox|'''[checkbox]'''}}: registers a checkbox.
** '''id''': the id for this option. Must be unique.
** '''default''': boolean value, determines if the box should be checked initially. Default no.
** '''name''': a string to be displayed next to the widget.
** '''description''': the tooltip text to be displayed when the user hovers the mouse over the widget.
* {{anchor|choice|'''[choice]'''}}: registers a combo box. This tag used to be named '''[combo]''' before 1.13.6.
** '''id''': the id for this option. Must be unique.
** '''default''': the default value of the widget.
** '''name''': a string to be displayed next to the widget.
** '''description''': the tooltip text to be displayed when the user hovers the mouse over the widget.
** '''[item]''': adds an item to the combo box.
*** '''name''': the displayed name of this item.
*** '''value''': the value the widget will take when this item is selected.
* {{anchor|entry|'''[entry]'''}}: registers a text entry.
** '''id''': the id for this option. Must be unique.
** '''default''': the string initially displayed by the widget.
** '''name''': a string to be displayed next to the widget.
** '''description''': the tooltip text to be displayed when the user hovers the mouse over the widget.
* {{anchor|slider|'''[slider]'''}}: registers an integer slider.
** '''id''': the id for this option. Must be unique.
** '''default''': an integer value. The slider will be positioned at this value by default.
** '''min''': the minimal value the slider can take.
** '''max''': the maximal value the slider can take.
** '''step''': the difference between adjacent values the slider can take. Default 1.
** '''name''': a string to be displayed next to the widget.
** '''description''': the tooltip text to be displayed when the user hovers the mouse over the widget.

in 1.12 those variables are inserted as preload event that set these variables.
{{DevFeature1.13|0}} These variables are now inserted directly in the scenario without events, this means you can also use those variables in scenariolevel [lua] tags and prestart events.

For [campaign] use in 1.12, options need to be inserted in the first [scenario]. Options for campaigns no longer work inside the first [scenario] and must now be placed directly inside [campaign].

SavefileWML

2024-09-04T19:05:57Z

Jarom: fix typo

{{WML Tags}}
== The format for Wesnoth savegames ==

A Wesnoth savegame is a file stored in '''~saves/''' (See "user data directory", [[PreprocessorRef]]).
In order to view or modify these files, the option Compressed Saves (Advanced Preferences) must be set to "No". Also, since they are not config(.cfg) files the normal coloring will not be generated. To generate coloring, simply save the file as .cfg, then open it again.

There are 3 types of savegames: start-of-scenario, replay and in-game (including autosave and out-of-sync save). The information included in a save depends on its type.

{|
|-
| || Start-of-scenario || Replay || In-game
|-
| General info and statistics || Yes || Yes || Yes
|-
| [snapshot] || No || No || Yes
|-
| [replay] || No || Yes || Yes
|-
| [replay_start] || No || Yes || Yes
|-
| [carryover_sides] || No || Yes || Yes
|-
| [carryover_sides_start] || Yes || Yes || Yes
|}

{{DevFeature1.13|0}} There are 4 types of savegames: start-of-scenario, expanded start-of-scenario, replay and in-game (including autosave and out-of-sync save). The information included in a save depends on its type.

{|
|-
| || Start-of-scenario || Expanded Start-of-scenario || Replay || In-game
|-
| General info and statistics || Yes || Yes || Yes || Yes
|-
| [snapshot] || No || No || No || Yes
|-
| [replay] || No || No || Yes || Yes
|-
| [replay_start] || No || No || Yes || Yes
|-
| [carryover_sides] || No || No || Yes || Yes
|-
| [carryover_sides_start] || Yes || Yes || No || No
|-
| [scenario] || No || Yes || No || No
|}

{{DevFeature1.13|0}} There are also 2 types of Server generated replays
{|
|-
| || Fresh game || Start-of-scenario || Reloaded game
|-
| General info and statistics || Yes || Yes || Yes
|-
| [snapshot] || No || No || Yes
|-
| [replay] || Yes || Yes || Yes
|-
| [replay_start] || No || No || Yes
|-
| [carryover_sides] || No || No || Yes
|-
| [carryover_sides_start] || Yes || Yes || No
|-
| [scenario] || Yes || Yes || No
|}

'''General info and statistics'''

Contains general information about the scenario, campaign and version of Battle for Wesnoth the savegame is from. This information is included in all savegames.
Not all tags of this section are explained here.

* '''version''': The version of Wesnoth this game was saved by. If the savegame is from a different version of Wesnoth than the one currently running, the message "This save is from a different version of the game. Do you want to try to load it?" is displayed
* '''campaign_type''': Whether the scenario is a scenario or multiplayer.
* '''campaign_define''': When this replay is loaded, the symbol campaign_define will be stored. See also "#ifdef", [[PreprocessorRef]]
* '''difficulty''': The difficulty level of the savegame. Normal values are "EASY", "NORMAL", and "HARD".
* '''label''': heading of the save
* '''next_scenario''': Name of the next scenario in a campaign
* '''scenario''': Name of the current scenario
* '''[multiplayer]''': If the game is a multiplayer game, multiplayer information is included here
* '''[statistics]''': Describes previous scenarios
** '''mid_scenario''': If "false", the scenario will be reloaded and any modifications will be played with.
** '''[scenario]''': Describes basic statistics of a previous scenario. See [[StatisticalScenarioWML]] for a description of [scenario]

'''[snapshot]'''

The [snapshot] describes the current state of the game in an in-game save. It has the same format as the rest of the savefile and holds the map of the scenario. The snapshot is loaded when “Show replay” is not selected.

* '''playing_team''': the number of the team whose turn it is, starting with 0
* '''turn_at''': The number of the current turn
* '''map_data''': The data for the map. The mini-map generated by this data is displayed to the right

'''[replay_start]'''

[replay_start] is a full snapshot of the start of the first turn of a scenario. It describes the position the player was in when the game started and is used as starting point for replays.

'''[replay]'''

The [replay] contains everything that happened in the scenario since it started.

* '''[command]''': Describes one action. Syntax for [command] is described in [[ReplayWML]]

'''[carryover_sides_start]'''

[carryover_sides_start] contains the carryover data from the previous scenario, like retained gold and units. It is also used to store in-game data required in the next level, such as variables, the random seed and menu items. [carryover_sides_start] retains the data throughout the scenario.

* '''random_calls''' and '''random_seed''': Used to determine and synchronize random events in the game
* '''[side]''': Player information, retained gold, recruits and recalls for all sides in the game
* '''[end_level_data]''': Contains the information how the carryover data should be used.
* '''[variables]''': a list of the current values of all variables. The attribute variable_name=value means that the variable ''variable_name'' has the content ''value''. The tag [array_name] describes an array stored in the array ''array_name'' (which could describe a unit see [[SingleUnitWML]]). See also [[VariablesWML]]
* '''[menu_item]''': Custom WML menu items

'''[carryover_sides]'''

[carryover_sides] is a copy of the data in [carryover_sides_start]. Anything to be used in the new scenario is removed from [carryover_sides]. At the end of the scenario the carryover for the next scenario is added to what is left in [carryover_sides].

'''[scenario]'''

{{DevFeature1.13|0}} Expanded Start-of-scenario saves are almost the same as normal start-of-scenario saves, except that they also contain the start [scenario] so it doesn't need to be read from the game config.
In most cases, this type of savegame is used internally, for example, at the beginning of a fresh networked mp game, where this host sends this type of savefile to the other clients, which is then loaded by them.

But in theory the game can also read an expanded start-of-scenario save from disk.

== See Also ==
* [[ReferenceWML]]

[[Category: WML Reference]]

DirectActionsWML

2024-09-04T18:47:40Z

Jarom: Add information about $teleport_unit in [tunnel]

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].

The following tags are actions:

=== [endlevel] ===
Ends the scenario.
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu.

When the result is "victory" the following keys can be used:
* '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.
* '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
* '''carryover_add''': if yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''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. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':
** '''result'''
** '''bonus'''
** '''carryover_percentage'''
** '''carryover_add'''

And there is also
** '''side''' The number of the side for which these results should apply.

=== [unit] ===
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}

This tag can also recall an existing unit, which happens when:
* the '''id=''' attribute is used
* a unit with that '''id=''' already exists
* (might be unnecessary) the existing unit is on the side's recall list
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.

Campaign authors: a usual way to recall plot-necessary heroes is to use a macro with the data for creating that hero. This helps during debugging, because you can skip to scenarios and the recall-or-create functionality means that any units which are normally met in a previous scenario are automatically created (otherwise some scenarios may be an instant loss). This can only be used for units that must survive the previous scenarios, as it would recreate units if they died in a previous scenario.
For example,
[https://github.com/wesnoth/wesnoth/blob/1.14.7/data/campaigns/Heir_To_The_Throne/utils/httt_utils.cfg#L685 HttT's NEED_DELFADOR macro].

=== [recall] ===
Recalls a unit taking into account any [[SingleUnitWML|filter_recall]] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.

If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.

* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).
* '''x,y''': the unit is placed here instead of next to the leader.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.

=== [teleport] ===
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to teleport to. Used instead of '''x,y'''.
* '''clear_shroud''': should shroud be cleared on arrival
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.

(Note: There is also a ability named teleport, see [[AbilitiesWML]].)

=== [terrain_mask] ===
Changes the terrain on the map. See [[TerrainMaskWML]].

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.
* '''location_id''': This key sets a string as a way to mark the hex or hexes for later reference. It is very similar to the leader starting position, and can also be set that way in the map editor.

If you want to remove the overlays from a terrain and leave only the base, use:
layer=overlay
terrain="^"

<b>Note:</b> When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages is that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [gold] ===
Gives sides gold.
* '''amount''': the amount of gold to give.
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field or recall list. This must be a specific variable describing a unit, and may not be an array (if it is, only the first unit will be unstored).

This may be useful in different contexts:
* To update a unit on the map after having edited its WML. This usage is common, but discouraged - if possible, you should use [[#.5Bmodify_unit.5B|[modify_unit]]] or [[#.5Bobject.5B|[object]]] instead.
* To place a previously-defined unit into the scenario, if it was directly defined in a WML variable, using [unit] with the key '''to_variable'''. This usage is rather uncommon.
* To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.

The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[VariablesWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].

The tag takes the following keys:
* '''variable''': This is required to indicate the name of the variable to read the unit from.
* '''Placement keys''':
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.
** '''find_vacant''' (yes|no, default no): Whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no' (default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''check_passability''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.
* '''Side-effect keys''' (these directly modify the behaviour of the action):
** '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP, make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors, especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.

Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit—and killed—in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

=== [allow_recruit] ===
Allows a side to recruit units it couldn't previously recruit. Any leader on this side will now be able to recruit the new units.
* '''type''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [allow_extra_recruit] ===
Allows a leader to recruit units it couldn't previously recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[allow_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [disallow_recruit] ===
Prevents a side from recruiting units it could previously recruit. No leader on this side will be able to recruit the specified units anymore, unless that leader has the same unit in their personal '''extra_recruit''' list.
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit. This won't prevent the leader from recruiting that unit if the unit is in the '''[side]recruit=''' list – you must use '''[disallow_recruit]''' in that case.
* '''extra_recruit''': the types of units that the leader can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [set_recruit] ===
Sets the units a side can recruit. Any leader on this side will now be able to recruit these units.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [set_extra_recruit] ===
Sets the units a leader can recruit.
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[set_recruit]'''.
* '''extra_recruit''': the types of units that the leader can now recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

=== [modify_side] ===
Modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'''
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* '''income''': the income given at the begining of each turn.
* '''recruit''': a list of unit types, replacing the side's current recruitment list.
* '''team_name''': the team in which the side plays the scenario.
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.
* '''gold''': the amount of gold the side owns.
* '''village_gold''': the income setting per village for the side.
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
* '''shroud''': a boolean string describing the status of Shroud for the side.
* '''hidden''': a boolean string specifying whether side is shown in status table.
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|[modify_ai]]]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally
* '''share_vision''': change both the above at the same time
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.

=== [modify_turns] ===
Modifies the turn limit in the middle of a scenario.
* '''value''': the new turn limit.
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).

=== [allow_end_turn] ===
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't require arguments.
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.

=== [capture_village] ===
Changes the ownership of a village.
* [[StandardLocationFilter]]: all village locations matching the filter are affected.
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.

=== [kill] ===
Removes all units (including units in a recall list) that match the filter from the game.
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.
* '''animate''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.
* '''fire_event''' (default 'no'): if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes ({{DevFeature1.13|8}} or if it has a victory animation and animate=yes). The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).
* '''[primary_attack]''' {{DevFeature1.13|8}} The attacker's weapon to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by. If a secondary unit is specified, this is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the unit. However, if there is no secondary unit specified, it is instead treated as an [[UnitTypeWML#Attacks|weapon definition]], and the animation will be run as if an imaginary unit possessing that weapon was the attacker.
* '''[secondary_attack]''' {{DevFeature1.13|8}} Similar to the above, but for the defender's weapon. This is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the dying unit.

=== [move_unit] ===
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.
* '''fire_event''' (boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.

=== [modify_ai] ===
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.

* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.
* '''path''' (string): Describes which AI object is to be modified.
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.

=== [modify_unit] ===
works similar to the MODIFY_UNIT macro.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter. ([object] is described further [[#.5Bobject.5D|below]])
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements, and will potentially overwrite existing modifications.
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit. See [[EffectWML]].
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the unit (saved inside the unit's [variables] tag); uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify. Note that keys will be processed in arbitrary order, which may cause problems if you use formulas that depend on other formulas. To work around this you may need to use the tag twice with the same filter.
example usage (see also the test scenario):
<syntaxhighlight lang='wml'>
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]
</syntaxhighlight>

The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).

Modifying a unit ''may'' trigger an advancement event if the experience is set higher than the max_experience. However, this behaviour should not be relied upon to happen under all circumstances; if it's desired, the event should be triggered separately, for example with '''[transform_unit]'''.

'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:
* '''side'''
* '''gender'''
* '''name'''
* '''canrecruit'''
* '''unrenamable'''
* '''extra_recruit'''
* '''[variables]'''
* '''facing'''
* '''x, y'''
* '''goto_x, goto_y'''
* '''hitpoints'''
* '''experience'''
* '''moves'''
* '''[status]'''
* '''attacks_left'''
* '''role'''

=== [transform_unit] ===
Transforms every unit on the map matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points. Regardless of anything else, the unit will be rebuilt. Thus, transforming a unit to its current type is a way to force a rebuild, for example after manually removing a modification.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.

=== [unpetrify] ===
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.

=== [object] ===
Gives some unit an object which modifies their stats in some way. This tag can also be used in places that don't support ActionWML, such as [[#.5Bmodify_unit.5D|[modify_unit]]] or [[SingleUnitWML|[unit][modifications]]]. The following is supported in all these places:
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the scenario.
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* Other keys, such as '''id''', may be used to remove the object later, but are not used by the engine. An '''[object]''' tag can contain any arbitrary data that may be helpful to identify the object to remove later using a [[FilterWML#Filtering_on_WML_data|WML filter]].

The following is supported only when using '''[object]''' as ActionWML:
* '''id''': (Optional) By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores. The ID is also commonly used to manually remove the object later, for example with [[#.5Bremove_object.5D|[remove_object]]].
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it tries to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.
* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_object] ===
{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching objects removed. Use no [filter] tag.
* '''object_id''': The id of the object to be removed.

Note that some unit properties are not restored ideally, e.g. current unit's health reversion might not work as expected (max_hitpoints will though). {{DevFeature1.15|0}} This was fixed.

Note that [remove_object] works the following way:

# Remove the object from the unit
# Rebuild the unit to make the changes effective.

Step 2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [[#.5Bmodify_unit.5D|[modify_unit]]] to get a list of properties that can safely be changed via [modify_unit].

=== [remove_trait] ===
{{DevFeature1.15|2}}

* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
* '''trait_id''': The id of the trait to be removed. See [[UnitsWML#.5Btrait.5D|[trait]]].

=== [remove_shroud] ===
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed

=== [place_shroud] ===
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.
* '''[filter_side]''' with a [[StandardSideFilter]] as argument
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed

=== [lift_fog] ===
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_vision=all).

=== [reset_fog] ===
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).

=== [allow_undo] ===
Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though — specifically when handling a menu item, where there is no current action — and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.

The types of actions that can be undone are movement, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.
* Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the action the first time.
* Although recalling can be undone, recruitment can not be undone; this seems to apply even when the recruit's traits are not randomly-generated (tested on 1.12.6 and 1.14.4+dev).

If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.

Due to a bug in 1.12 ([http://web.archive.org/web/20170330000414/http://gna.org/bugs/?23323 https://gna.org/bugs/?23323]) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS:
* [message] with [option]s
* [get_global_variable]
* wesnoth.synchronize_choice

While in 1.13 using '''[allow_undo]''' together with those things won't give you a guaranteed OOS, there are some non-obvious situations where it will, for example assume the following event:

[event]
name="moveto"
[message]
message = "message"
[option]
label = "option 1"
[command]
[/command]
[/option]
[option]
label = "option 2"
[command]
[/command]
[/option]
[/message]
[allow_undo]
[/allow_undo]
[/event]

It will cause OOS when the message is undone: since the event is already executed (erased) on one client only , the clients will disagree about how many choices happen during the next moveto action.

=== [on_undo] ===
{{DevFeature1.13|2}}
Contains commands to execute when the player undoes the action which triggered the parent event.
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)

Note:
It is not clear where whether the actionwml in [on_undo] in executed before or after the action is undone. Also, specially for enter/leave_hex events the units position when executing the [on_undo] code is usually different than when executing the original event. The recommended way to work around these issues is to refer to the unit by id instead of position and store all other needed information variables as 'upvalues'. You can also move the actual undo code to an external event. For example
[event]
name="undo_blah"
first_time_only=no
[store_unit]
id="$moved_unit_id"
[/store_unit]
... do undo stuff stuff
[/event]

...
... in some other event
[on_undo]
# store ''upvalues
{VARIABLE moved_unit_id $unit.id}
# call actual undo handler
[fire_event]
name = "undo_blah"
[/fire_event]
[on_undo]

=== [on_redo] ===
{{DevFeature1.13|2}}
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.

{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.

Note that [on_redo] is not guaranteed to be called when redoing an action, the engine might also decide to just fire the original events again.

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of '''enter_hex'''/'''exit_hex''' [event] in that version.

{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).

{{DevFeature1.13|11}}
In an '''enter_hex'''/'''exit_hex''' [event], interrupt the movement, leaving the unit where it is. This is intended to be used with an event that gives the player new information, to let the player choose whether to change their plans. For example, if the player has commanded a unit to move from (1,1) to (3,3) and attack a unit on (4,4); then a [cancel_action] inside an '''enter_hex''' [event] on (2,2) would make the unit stop on (2,2). A [cancel_action] inside an enter_hex [event] on (3,3) would let the player choose whether to attack.

{{DevFeature1.15|0}}
In a '''capture'''/'''moveto''' [event], interrupt the attack.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed. When the variable is not needed, use {CLEAR_VARIABLE heal_amount} after this tag.

{{DevFeature1.17|0}} The '''$heal_amount''' variable is no longer set. Use the '''variable''' key instead.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to yes) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. This can't be used to set the unit's hitpoints below 1 or above the unit's maximum hitpoints. If "full", it fully heals the unit.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable.
* '''variable''': {{DevFeature1.17|0}} creates an array with the given name; each item of the array has two fields, ''id='' (the ID of the unit being healed) and ''heal_amount='' (the amount of HPs the unit has been healed by).

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount. When harming multiple units, the special variable '''$this_unit''' can be used to access the current unit being harmed. This obviously does not work inside the filters though, as they give '''$this_unit''' a different meaning.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': (default yes) If there is a harmer, experience will be attributed similar to regular combat. Can take list of values. When any value is provided, all unspecified experience types default to not giving experience. Supported values: {{DevFeature1.17|25}} until that version only experience=yes and experience=no are supported
** no - none of involved units get any experience (this value only works if it is the only value in list)
** kill - the harming unit receives experience based on level of harmed unit in attack which kills harmed unit
** attack - the harming unit receives experience based on level of harmed unit in attack which does not kill harmed unit, or in attack which kills harmed unit while kill experience is disabled
** defend - the unit being harmed receives experience based on level of harming unit in attack which does not kill harmed unit
** fight - short form of experience=attack,defend
** yes - short form of experience=kill,attack,defend
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

=== [time_area] ===
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later or reference it from a location filter elsewhere. Can be a comma-separated list when removing time_areas, see below.
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.

''Example:'' (caves in parts of a map)
<syntaxhighlight lang=wml>
[time_area]
id = cave_area
x = 1-2,4-5
y = 1-2,1-2
{UNDERGROUND}
[/time_area]
</syntaxhighlight>

Specifying an id allows the area to be referenced from location filters. Example:
<syntaxhighlight lang=wml>
[time_area]
id = glyphs
x = 9,14
y = 11,3
[/time_area]
[event]
name = moveto
first_time_only=no
[filter]
side = 1
[filter_location]
area = glyphs
[/filter_location]
[/filter]
# Do something, for example healing the unit
[/event]
</syntaxhighlight>

=== [remove_time_area] ===

{{DevFeature1.13|2}}

This is a syntactic shortcut for [time_area] remove=.
* '''id''': Comma-separated list of time area ids to remove.

=== [end_turn] ===
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).

=== [replace_map] ===

Replaces the entire map.
* '''map_data''': Content of a wesnoth map file. (This key used to be just '''map='''.) Example:
map_data="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:
map_file=01_The_Elves_Besieged.map
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement. ('''NB''': due to https://github.com/wesnoth/wesnoth/issues/5757 this attribute is ignored in versions 1.16.*. The fix was delivered in 1.17.* but wasn't backported due to backward-compatibility requirements)

=== [tunnel] ===

Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain).

'''Behavior Change as of Wesnoth 1.13.6:''' Vision is now possible (and enabled by default) through tunnels and allied units on the exit hex do not block a tunnel by default any more. This is done in order for moves through tunnels to be consistent with other moves. The previous behavior can still be accomplished by using the new optional keys listed below.

* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es). Use $teleport_unit to filter on unit being teleported.
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es). Use $teleport_unit to filter on unit being teleported.
* '''id''': (optional) identifier for the tunnel, to allow removing.
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction.
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.
* '''delayed_variable_substitution''' (boolean, default: yes): If yes, the WML block contained in this [tunnel] is not variable-substituted at execution time of the event where this [tunnel] is within. Instead, variables are substituted when the tunnel is used by a unit. See [[EventWML#Nested_Events]]

(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).

=== [do_command] ===

{{DevFeature1.13|0}}

Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted

* [attack]
* [move]
* [recruit]
* [recall]
* [disband]
* [fire_event]
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it. That means for example that only moves that player would be allowed to do are possible, and movement is interrupted when sighting enemy unit.

One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.

This command should be replay safe if it is either invoked in a synced context, ''or'' invoked in code that is never synced, like AI code, a select event, or a menu item with `synced = false`. However, if you use desynchronized logic ''during'' an event that is otherwise synced, invoking [do_command] based on that desynchronized logic will result in out-of-sync errors during the replay; in this case, you must explicitly synchronize which command to do using something like the lua function wesnoth.sync.evaluate_single.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

Puts a unit to the recall list of its side.
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.

=== [set_achievement] ===

{{DevFeature1.17|13}}

Sets the specified achievement as completed and shows a popup stating it's been completed. The popup is not shown if the achievement has already been achieved.

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.

=== [set_sub_achievement] ===

{{DevFeature1.17|17}}

Sets the specified sub-achievement as completed.

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''sub_id''': The id of the sub-achievement.

=== [progress_achievement] ===

{{DevFeature1.17|13}}

Progress an achievement by the specified amount, with an optional limit for how far the achievement can be progressed.

* '''content_for''': The [[AchievementsWML#.5Bachievement_group.5D|[achievement_group]]] that this achievement is part of.
* '''id''': The id of the achievement.
* '''amount''': The amount to increment the achievement.
* '''limit''': (optional) Using this attribute will prevent achievements from progressing past this value.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [https://www.wesnoth.org/macro-reference.html here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

MakingCampaignInWML

2022-01-18T09:53:45Z

Jarom: Added to category

'''Step-by-step tutorial - making a campaign using WML.'''

'''Part 1: Making a basic campaign'''

You can access the next part by following the link at the bottom, but here's a list for convenience:
*[[MakingCampaignInWML2|Part 2: Expanding the campaign definition]]
*[[MakingCampaignInWML3|Part 3: Improving the first scenario]]
*[[MakingCampaignInWML4|Part 4: Custom macros and events]]

----

This tutorial's goal is to provide a step-by-step explanation on how to build a campaign using [[ReferenceWML|WML]]. It's not as comprehensive as other existing tutorials, because it's designed to minimize information in order to lower the entry barrier, so after doing it you won't gain all the necessary information, but you will be able to make a basic campaign. It's recommended to download WML Guide, The Final Exam or a simple add-on like Story of the Wose (from 1.14 add-ons server) or An Orcish Incursion (from 1.16 add-ons server).

== Getting started ==

First, locate your add-ons folder. Following screenshot is for 1.16.0 version:

https://i.imgur.com/0L2dLo2.png

Then, create a folder for your add-on. It's customary that it starts with a capital letter and advisable that it has no spaces – use _ (underscores) or [https://en.wikipedia.org/wiki/Camel_case PascalCase] instead. In this tutorial we'll create a folder named WML_Tutorial. Pick a folder name that refers to your add-ons's name, it's often the same as in id below. Replace spaces with underscores.

'''Important note: after making any changes in your add-on, save all modified files first, then reload Wesnoth either by closing and running it again or by clicking f5 in the main menu.'''

== The main file ==
Now inside create a file '''_main.cfg''' (the filename has to be exactly like that), then open it with your preferred code editor. Windows notepad is theoretically sufficient, but the author strongly recommends [https://code.visualstudio.com/ Visual Studio Code] with [https://marketplace.visualstudio.com/items?itemName=Bitron.wml WML add-in], alternatively [https://notepad-plus-plus.org/downloads/ Notepad++], preferably with imported [https://forums.wesnoth.org/viewtopic.php?t=44392 WML language definition]. If using VS Code, it's advisable to open the whole add-on folder and use it as a workspace.

Then, we create the basic structure. Refer to the code below:

<syntaxhighlight lang=wml>
[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
[/campaign]
</syntaxhighlight>

It's just four lines that tell the campaign that there exists a campaign named WML Tutorial. You can now run the game and see the following entry in campaigns menu:

https://i.imgur.com/vcUqfEj.png

However, it will show an error "Failed to load the scenario" if we try to start. Let's analyse the code step by step.

[[CampaignWML|'''[campaign]''']] tag is an opening tag. In the last line there's also a closing tag, '''[/campaign]'''. All tags must have both opening tag and closing tag, and the closing tag is always the same as opening tag but with / (slash) before the name. In this case the tag name is campaign and it means that everything inside describes a single campaign.
----
Important syntax information – omit at your own risk unless you read [[SyntaxWML]] or the [[WML_for_Complete_Beginners:_Chapter_1|other tutorial]].
* (Almost) all valid tags (tag names) are listed in alphabetical order in the right panel on all WML Reference pages, but keep in mind that most of them are only valid within a certain context. There are also "tag amendments" with [+name] (e.g. [+campaign]) syntax, but we'll talk about them later.
* Everything between opening tag (e.g. [campaign]) and matching closing tag (e.g. [/campaign]) is this tag's content. It consists of subtags (aka children) with the same syntax (check tag's reference for possible subtags), and keys, in this example second and third lines are keys. Order of tags usually matters.
* Keys follow the ''name=value'' syntax, which is somewhat flexible – ''name = value'' as in the example above works as well. Wesnoth core uses ''name=value'' to save disc space but this tutorial will use ''name = value'' for clarity. Contrary to tags, order of keys is not important, unless there are duplicate keys, but those should be avoided. Therefore feel free to sort them however you want. However in some cases there are implicit conventions, usually established by extensive use in mainline - this tutorial often breaks them on purpose. One that is recommended to be followed is to put id-like and type-like keys first, if there are any, and group name with id.
* It's strongly recommended that each opening tag causes the following lines of code to have one more tab stop (or four spaces) at the beginning – it's called indentation. Wesnoth core typically uses tabs – this example we will use spaces because they are easier to use with webpages.
* Note for XML/SGML programmers – there are no void tags, self-closing tags, or keys within the opening tag – keys are only within content, so WML does not conform to both conventions. Not to mention the use of [] square brackets in place of <> angled brackets.
----
'''id = WML_Tutorial''' - this key tells the game that the campaign we describe has an identifier "WML_tutorial. Pick an id that doesn't conflict with any other campaign, preferably including all add-ons, and forget about it forever.
:You can enclose WML_tutorial (or your own id) in double quotes, it won't change anything. IDs are recommended to have no spaces but it's not mandatory. Typically campaign's id is its name but with underscores in place of spaces.
'''name = _"WML Tutorial"''' - tells the game to show a text (string) WML Tutorial to the user every time it needs this campaign's name. Note the _ (underscore) – it means that this text is translatable. Every text that's visible to the user should always be translatable.
:Wesnoth core's usual syntax for translatable keys is ''name= _ "visible"'' but we'll do things our own way as always, and this time for a good reason that will be explained in the second part. Unlike ids, names don't have to be unique, but it's advisable in this case.

So we did tell the game that there exists a campaign named WML Tutorial, but it has currently no content. Wesnoth should always know that our campaign exists, but should only load its content when necessary. Therefore, we'll use [[PreprocessorRef|WML Preprocessor]] to load the content when the campaign is started. All you need to know for now is that we add '''define=''' key to the ''[campaign]'' tag, and then after the tag we'll put the '''#ifdef''' directive along with closing '''#endif''' directive.

<syntaxhighlight lang=wml>
[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
define = WML_TUTORIAL
[/campaign]
#ifdef WML_TUTORIAL
#endif
</syntaxhighlight>

The text after ''#ifdef'' (WML_TUTORIAL in this case) must match the value of ''define='' key. It's recommended to use [https://en.wikipedia.org/wiki/Snake_case SCREAMING_SNAKE_CASE] for it. It's customary that it matches the campaign's id somehow. Now everything between ''#ifdef'' and matching ''#endif'' will be loaded when the campaign starts. Though there's nothing there for now – let's make it load scenarios.
:It's possible to delegate your campaign's content loading to a different file, especially if you're planning to have dependencies based on it – which rarely happens actually. If you need an example you can check the add-on Era of Magic's ''campaign.cfg'' file.

First, make a folder scenarios within your add-on folder (WML_Tutorial). You can use a different name but you shouldn't. Then add a magic line '''{~add-ons/WML_Tutorial/scenarios}''' between ''#ifdef'' and ''#endif'' in your ''_main.cfg'' file. If you used a different folder name for your add-on, change the line accordingly.

Now when your campaign is loaded, all files with .cfg extension inside scenarios folder (we'll add one soon) will be loaded, as well as all ''_main.cfg'' files in its subfolders (this feature is almost never used so forget it, there are better ways if you need nested folder structure).

== Basic scenario ==
Before we move to create the first scenario, we're going to need a map. Create a folder named maps – unlike scenarios, the folder's name is important. Now make a simple map with two starting positions marked and save it in your newly created maps folder. Refer to [[BuildingMaps|this tutorial on making maps]]. You can also copy one from other campaigns for training purposes, e.g. ''01_At_the_East_Gate.map'' from The Hammer of Thursagan – [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/The_Hammer_of_Thursagan/maps/01_At_the_East_Gate.map link to Wesnoth's github].
:You might need to navigate a bit, assuming you're in the editor's maps folder, go two steps higher to reach the userdata folder, then go to data/add-ons/WML_Tutorial. You can add your add-on's maps folder to the quick access panel on the left for future ease of use.

Having created the map, let's create a scenario. For demonstration purposes, we'll name it Initial Scenario. First let's create a .cfg file in the scenarios folder. In our case it'll be ''01_Initial_Scenario.cfg''. Numbering isn't necessary, but it helps keep track of order, so it's recommended. Now consider the following code that you should copy to your scenario file:

<syntaxhighlight lang=wml>
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
[/side]
[/scenario]
</syntaxhighlight>

[[ScenarioWML|'''[scenario]''']] tag tells the game that everything inside describes a single scenario.

''id='' and ''name='' are pretty much the same as in ''[campaign]'', except this time id is important for you because you'll be using it in other places.
:You need to note that your scenario's id mustn't clash with other scenarios loaded at the same time, that is, other scenarios in your campaign. It's advised to match scenario's id with its name and filename. Prefixing scenario ids with numbers helps in debugging and keeping track of order, and it's customary not to use spaces.

''map_file='' key refers to the filename of map file within maps folder. You could also use ''map_data='' like in other tutorials and many add-ons, but it's somewhat obsolete, more difficult and error-prone.
:It's advisable that your map file has exactly the same filename as your scenario file, except that it's in a different folder and has .map instead of .cfg extension.

[[SideWML|'''[side]''']] tag describes a single side. In this example it has a ''side='' key, which describes the turn order (usually side 1 is player's but not necessarily). It also has a mandatory ''controller='' key. It's ''"human"'' value tells the game that the player is the one playing this side.

== Adjustments to main file ==
Now add a ''first_scenario = 01_Initial_Scenario'' key to your ''[campaign]'' tag in ''_main.cfg'' file. If you gave your scenario a different id, adjust the code accordingly.
Now you can try to actually run your campaign, but it's going to throw an error because it can't find the map. To make it work, add the following code to ''#ifdef'' in ''_main.cfg'':

<syntaxhighlight lang=wml>
[binary_path]
path = data/add-ons/WML_Tutorial
[/binary_path]
</syntaxhighlight>

This [[BinaryPathWML|'''[binary_path]''']] will tell the game to look for resources (images/maps/sounds/music files) in their respective folders. Like always, if your add-on uses a different folder name, adjust the code accordingly.

Now you can actually run your campaign. It should load, but you'll instantly lose.

== Troubleshooting ==
In case your scenario doesn't load, troubleshoot it before proceeding to next steps. Otherwise, you can skip it.

If the game doesn't show your campaign on the list at all:
:Either you made a mistake in the naming ''_main.cfg'' file, or your add-on's directory is in the wrong place – start again from the beginning. There's also a possibility that you used wrong syntax in your ''[campaign]'' tag, in this case copy the code from here again and check for conflicting ids.
If your scenario doesn't load:
:Check if your include directive ''{~add-ons/WML_Tutorial/scenarios}'' points to the valid scenarios folder and your scenario file is there (filename doesn't matter as long as it has the correct .cfg extension). Check if your ''#ifdef'' and ''define='' are matching. Check if your ''[scenario]'' tag has correct syntax (unlikely to be the problem).
If your scenario throws an error about the map:
:Check if your map file is in the correct folder (maps). Check if your ''[binary_path]'''s ''path='' key points correctly to your add-on's folder (WML_Tutorial in this case). Check if ''map_file='' key in ''[scenario]'' matches the filename of your map (including extension).
Code up to this point:
:Your ''_main.cfg'' file should look more or less like that:

<syntaxhighlight lang=wml>
[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
first_scenario = 01_Initial_Scenario
define = WML_TUTORIAL
[/campaign]

#ifdef WML_TUTORIAL
[binary_path]
path = data/add-ons/WML_Tutorial
[/binary_path]
{~add-ons/WML_Tutorial/scenarios}
#endif
</syntaxhighlight>

:While your ''01_Initial_Scenario.cfg'' (or however it's named) in scenarios folder should look like that:

<syntaxhighlight lang=wml>
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
[/side]
[/scenario]
</syntaxhighlight>

:And there should be a correct map file in the maps folder, named ''01_Initial_Scenario.map'' (or whatever is written in ''map_file='' key).

== Adding playability ==
Now, as it was said before, if you run the scenario you'll instantly lose. Solution is trivial: add a ''type='' key to your '''[side]''' tag with valid unit id as value. Here we'll use ''type = Longbowman''. This key tells the game that your leader is a unit of type Longbowman, so it can create this unit on the starting point defined in the map editor.

Now if you run the game, you'll instantly win. Reason – there's no enemy. If it's intended, you can add a ''victory_when_enemies_defeated = no'' key to your '''[scenario]''' tag, but it's an advanced feature – we're going to add an enemy instead. Consider the following code:

<syntaxhighlight lang=wml>
[side]
side = 2
controller = ai
type = Dark Sorcerer
[/side]
</syntaxhighlight>

Insert it in your ''[scenario]'' tag. It adds a second (''side=2'') side, controlled by ai, whose leader is a Dark Sorcerer. It's pretty similar to the previous ''[side]'' tag, so the further explanation will be omitted.
Now you can run your scenario and it'll actually work, except that you can only move your leader – there's nothing to recruit.

Add a ''recruit='' key to both ''[side]'' tags. In this example, it'll be ''recruit = Bowman, Spearman'' for ''side = 1'' and ''recruit = Skeleton Archer, Skeleton'' for ''side = 2''. This tells the game which units the side can recruit, of course, and the value should be a comma-separated list of valid unit ids.

Run the game. You should have a simple one-scenario campaign in which your human army of bowmans and spearmans fight a disgusting horde of skeletons led by a dark sorcerer. All values like gold, income etc are their respective default values. This concludes a [https://en.wikipedia.org/wiki/Minimal_working_example Minimal Working Example].

== Troubleshooting part 2: ==
If your or enemy leader don't appear
:Check if their unit ids in ''type='' are valid. Check if starting positions for side 1 and 2 are properly defined in the map file. There exists a way for placing leaders without a defined starting position but it's an advanced feature.
If you can't recruit, or enemy doesn't recruit
:The respective ''recruit='' key has invalid syntax or contains an invalid unit id. Try the example first.
scenario code at this point:

<syntaxhighlight lang=wml>
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
type = Longbowman
recruit = Bowman, Spearman
[/side]
[side]
side = 2
controller = ai
type = Dark Sorcerer
recruit = Skeleton Archer, Skeleton
[/side]
[/scenario]
</syntaxhighlight>

----

[[MakingCampaignInWML2|Part 2: Expanding the campaign definition]]
[[Category:WML_Tutorials]]

MakingCampaignInWML

2021-12-22T18:48:39Z

Jarom: bold for first _main.cfg filename to avoid confusion

MakingCampaignInWML

2021-11-25T17:15:09Z

Jarom: Added screenshots and references to other parts

'''Step-by-step tutorial - making a campaign using WML.'''

'''Part 1: Making a basic campaign'''

You can access the next part by following the link at the bottom, but here's a list for convenience:
*[[MakingCampaignInWML2|Part 2: Expanding the campaign definition]]
*[[MakingCampaignInWML3|Part 3: Improving the first scenario]]
*[[MakingCampaignInWML4|Part 4: Custom macros and events]]

----

This tutorial's goal is to provide a step-by-step explanation on how to build a campaign using WML. It's not as comprehensive as other existing tutorials, because it's designed to minimize information in order to lower the entry barrier, so after doing it you won't gain all the necessary information, but you will be able to make a basic campaign. It's recommended to download WML Guide, The Final Exam or a simple add-on like Story of the Wose (from 1.14 add-ons server) or An Orcish Incursion (from 1.16 add-ons server).

== Getting started ==

First, locate your add-ons folder. Following screenshot is for 1.16.0 version:

https://i.imgur.com/0L2dLo2.png

Then, create a folder for your add-on. It's customary that it starts with a capital letter and advisable that it has no spaces – use _ (underscores) or [https://en.wikipedia.org/wiki/Camel_case PascalCase] instead. In this tutorial we'll create a folder named WML_Tutorial. Pick a folder name that refers to your add-ons's name, it's often the same as in id below. Replace spaces with underscores.

'''Important note: after making any changes in your add-on, save all modified files first, then reload Wesnoth either by closing and running it again or by clicking f5 in the main menu.'''

== The main file ==
Now inside create a file _main.cfg (the filename has to be exactly like that), then open it with your preferred code editor. Windows notepad is theoretically sufficient, but the author strongly recommends [https://code.visualstudio.com/ Visual Studio Code] with [https://marketplace.visualstudio.com/items?itemName=Bitron.wml WML add-in], alternatively [https://notepad-plus-plus.org/downloads/ Notepad++], preferably with imported [https://forums.wesnoth.org/viewtopic.php?t=44392 WML language definition]. If using VS Code, it's advisable to open the whole add-on folder and use it as a workspace.

Then, we create the basic structure. Refer to the code below:

<syntaxhighlight lang=wml>
[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
[/campaign]
</syntaxhighlight>

It's just four lines that tell the campaign that there exists a campaign named WML Tutorial. You can now run the game and see the following entry in campaigns menu:

https://i.imgur.com/vcUqfEj.png

However, it will show an error "Failed to load the scenario" if we try to start. Let's analyse the code step by step.

[[CampaignWML|'''[campaign]''']] tag is an opening tag. In the last line there's also a closing tag, '''[/campaign]'''. All tags must have both opening tag and closing tag, and the closing tag is always the same as opening tag but with / (slash) before the name. In this case the tag name is campaign and it means that everything inside describes a single campaign.
----
Important syntax information – omit at your own risk unless you read [[SyntaxWML]] or the [[WML_for_Complete_Beginners:_Chapter_1|other tutorial]].
* (Almost) all valid tags (tag names) are listed in alphabetical order in the right panel on all WML Reference pages, but keep in mind that most of them are only valid within a certain context. There are also "tag amendments" with [+name] (e.g. [+campaign]) syntax, but we'll talk about them later.
* Everything between opening tag (e.g. [campaign]) and matching closing tag (e.g. [/campaign]) is this tag's content. It consists of subtags (aka children) with the same syntax (check tag's reference for possible subtags), and keys, in this example second and third lines are keys. Order of tags usually matters.
* Keys follow the ''name=value'' syntax, which is somewhat flexible – ''name = value'' as in the example above works as well. Wesnoth core uses ''name=value'' to save disc space but this tutorial will use ''name = value'' for clarity. Contrary to tags, order of keys is not important, unless there are duplicate keys, but those should be avoided. Therefore feel free to sort them however you want. However in some cases there are implicit conventions, usually established by extensive use in mainline - this tutorial often breaks them on purpose. One that is recommended to be followed is to put id-like and type-like keys first, if there are any, and group name with id.
* It's strongly recommended that each opening tag causes the following lines of code to have one more tab stop (or four spaces) at the beginning – it's called indentation. Wesnoth core typically uses tabs – this example we will use spaces because they are easier to use with webpages.
* Note for XML/SGML programmers – there are no void tags, self-closing tags, or keys within the opening tag – keys are only within content, so WML does not conform to both conventions. Not to mention the use of [] square brackets in place of <> angled brackets.
----
'''id = WML_Tutorial''' - this key tells the game that the campaign we describe has an identifier "WML_tutorial. Pick an id that doesn't conflict with any other campaign, preferably including all add-ons, and forget about it forever.
:You can enclose WML_tutorial (or your own id) in double quotes, it won't change anything. IDs are recommended to have no spaces but it's not mandatory. Typically campaign's id is its name but with underscores in place of spaces.
'''name = _"WML Tutorial"''' - tells the game to show a text (string) WML Tutorial to the user every time it needs this campaign's name. Note the _ (underscore) – it means that this text is translatable. Every text that's visible to the user should always be translatable.
:Wesnoth core's usual syntax for translatable keys is ''name= _ "visible"'' but we'll do things our own way as always, and this time for a good reason that will be explained in the second part. Unlike ids, names don't have to be unique, but it's advisable in this case.

So we did tell the game that there exists a campaign named WML Tutorial, but it has currently no content. Wesnoth should always know that our campaign exists, but should only load its content when necessary. Therefore, we'll use [[PreprocessorRef|WML Preprocessor]] to load the content when the campaign is started. All you need to know for now is that we add '''define=''' key to the ''[campaign]'' tag, and then after the tag we'll put the '''#ifdef''' directive along with closing '''#endif''' directive.

<syntaxhighlight lang=wml>
[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
define = WML_TUTORIAL
[/campaign]
#ifdef WML_TUTORIAL
#endif
</syntaxhighlight>

The text after ''#ifdef'' (WML_TUTORIAL in this case) must match the value of ''define='' key. It's recommended to use [https://en.wikipedia.org/wiki/Snake_case SCREAMING_SNAKE_CASE] for it. It's customary that it matches the campaign's id somehow. Now everything between ''#ifdef'' and matching ''#endif'' will be loaded when the campaign starts. Though there's nothing there for now – let's make it load scenarios.
:It's possible to delegate your campaign's content loading to a different file, especially if you're planning to have dependencies based on it – which rarely happens actually. If you need an example you can check the add-on Era of Magic's ''campaign.cfg'' file.

First, make a folder scenarios within your add-on folder (WML_Tutorial). You can use a different name but you shouldn't. Then add a magic line '''{~add-ons/WML_Tutorial/scenarios}''' between ''#ifdef'' and ''#endif'' in your ''_main.cfg'' file. If you used a different folder name for your add-on, change the line accordingly.

Now when your campaign is loaded, all files with .cfg extension inside scenarios folder (we'll add one soon) will be loaded, as well as all ''_main.cfg'' files in its subfolders (this feature is almost never used so forget it, there are better ways if you need nested folder structure).

== Basic scenario ==
Before we move to create the first scenario, we're going to need a map. Create a folder named maps – unlike scenarios, the folder's name is important. Now make a simple map with two starting positions marked and save it in your newly created maps folder. Refer to [[BuildingMaps|this tutorial on making maps]]. You can also copy one from other campaigns for training purposes, e.g. ''01_At_the_East_Gate.map'' from The Hammer of Thursagan – [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/The_Hammer_of_Thursagan/maps/01_At_the_East_Gate.map link to Wesnoth's github].
:You might need to navigate a bit, assuming you're in the editor's maps folder, go two steps higher to reach the userdata folder, then go to data/add-ons/WML_Tutorial. You can add your add-on's maps folder to the quick access panel on the left for future ease of use.

Having created the map, let's create a scenario. For demonstration purposes, we'll name it Initial Scenario. First let's create a .cfg file in the scenarios folder. In our case it'll be ''01_Initial_Scenario.cfg''. Numbering isn't necessary, but it helps keep track of order, so it's recommended. Now consider the following code that you should copy to your scenario file:

<syntaxhighlight lang=wml>
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
[/side]
[/scenario]
</syntaxhighlight>

[[ScenarioWML|'''[scenario]''']] tag tells the game that everything inside describes a single scenario.

''id='' and ''name='' are pretty much the same as in ''[campaign]'', except this time id is important for you because you'll be using it in other places.
:You need to note that your scenario's id mustn't clash with other scenarios loaded at the same time, that is, other scenarios in your campaign. It's advised to match scenario's id with its name and filename. Prefixing scenario ids with numbers helps in debugging and keeping track of order, and it's customary not to use spaces.

''map_file='' key refers to the filename of map file within maps folder. You could also use ''map_data='' like in other tutorials and many add-ons, but it's somewhat obsolete, more difficult and error-prone.
:It's advisable that your map file has exactly the same filename as your scenario file, except that it's in a different folder and has .map instead of .cfg extension.

[[SideWML|'''[side]''']] tag describes a single side. In this example it has a ''side='' key, which describes the turn order (usually side 1 is player's but not necessarily). It also has a mandatory ''controller='' key. It's ''"human"'' value tells the game that the player is the one playing this side.

== Adjustments to main file ==
Now add a ''first_scenario = 01_Initial_Scenario'' key to your ''[campaign]'' tag in ''_main.cfg'' file. If you gave your scenario a different id, adjust the code accordingly.
Now you can try to actually run your campaign, but it's going to throw an error because it can't find the map. To make it work, add the following code to ''#ifdef'' in ''_main.cfg'':

<syntaxhighlight lang=wml>
[binary_path]
path = data/add-ons/WML_Tutorial
[/binary_path]
</syntaxhighlight>

This [[BinaryPathWML|'''[binary_path]''']] will tell the game to look for resources (images/maps/sounds/music files) in their respective folders. Like always, if your add-on uses a different folder name, adjust the code accordingly.

Now you can actually run your campaign. It should load, but you'll instantly lose.

== Troubleshooting ==
In case your scenario doesn't load, troubleshoot it before proceeding to next steps. Otherwise, you can skip it.

If the game doesn't show your campaign on the list at all:
:Either you made a mistake in the naming ''_main.cfg'' file, or your add-on's directory is in the wrong place – start again from the beginning. There's also a possibility that you used wrong syntax in your ''[campaign]'' tag, in this case copy the code from here again and check for conflicting ids.
If your scenario doesn't load:
:Check if your include directive ''{~add-ons/WML_Tutorial/scenarios}'' points to the valid scenarios folder and your scenario file is there (filename doesn't matter as long as it has the correct .cfg extension). Check if your ''#ifdef'' and ''define='' are matching. Check if your ''[scenario]'' tag has correct syntax (unlikely to be the problem).
If your scenario throws an error about the map:
:Check if your map file is in the correct folder (maps). Check if your ''[binary_path]'''s ''path='' key points correctly to your add-on's folder (WML_Tutorial in this case). Check if ''map_file='' key in ''[scenario]'' matches the filename of your map (including extension).
Code up to this point:
:Your ''_main.cfg'' file should look more or less like that:

<syntaxhighlight lang=wml>
[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
first_scenario = 01_Initial_Scenario
define = WML_TUTORIAL
[/campaign]

#ifdef WML_TUTORIAL
[binary_path]
path = data/add-ons/WML_Tutorial
[/binary_path]
{~add-ons/WML_Tutorial/scenarios}
#endif
</syntaxhighlight>

:While your ''01_Initial_Scenario.cfg'' (or however it's named) in scenarios folder should look like that:

<syntaxhighlight lang=wml>
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
[/side]
[/scenario]
</syntaxhighlight>

:And there should be a correct map file in the maps folder, named ''01_Initial_Scenario.map'' (or whatever is written in ''map_file='' key).

== Adding playability ==
Now, as it was said before, if you run the scenario you'll instantly lose. Solution is trivial: add a ''type='' key to your '''[side]''' tag with valid unit id as value. Here we'll use ''type = Longbowman''. This key tells the game that your leader is a unit of type Longbowman, so it can create this unit on the starting point defined in the map editor.

Now if you run the game, you'll instantly win. Reason – there's no enemy. If it's intended, you can add a ''victory_when_enemies_defeated = no'' key to your '''[scenario]''' tag, but it's an advanced feature – we're going to add an enemy instead. Consider the following code:

<syntaxhighlight lang=wml>
[side]
side = 2
controller = ai
type = Dark Sorcerer
[/side]
</syntaxhighlight>

Insert it in your ''[scenario]'' tag. It adds a second (''side=2'') side, controlled by ai, whose leader is a Dark Sorcerer. It's pretty similar to the previous ''[side]'' tag, so the further explanation will be omitted.
Now you can run your scenario and it'll actually work, except that you can only move your leader – there's nothing to recruit.

Add a ''recruit='' key to both ''[side]'' tags. In this example, it'll be ''recruit = Bowman, Spearman'' for ''side = 1'' and ''recruit = Skeleton Archer, Skeleton'' for ''side = 2''. This tells the game which units the side can recruit, of course, and the value should be a comma-separated list of valid unit ids.

Run the game. You should have a simple one-scenario campaign in which your human army of bowmans and spearmans fight a disgusting horde of skeletons led by a dark sorcerer. All values like gold, income etc are their respective default values. This concludes a [https://en.wikipedia.org/wiki/Minimal_working_example Minimal Working Example].

== Troubleshooting part 2: ==
If your or enemy leader don't appear
:Check if their unit ids in ''type='' are valid. Check if starting positions for side 1 and 2 are properly defined in the map file. There exists a way for placing leaders without a defined starting position but it's an advanced feature.
If you can't recruit, or enemy doesn't recruit
:The respective ''recruit='' key has invalid syntax or contains an invalid unit id. Try the example first.
scenario code at this point:

<syntaxhighlight lang=wml>
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
type = Longbowman
recruit = Bowman, Spearman
[/side]
[side]
side = 2
controller = ai
type = Dark Sorcerer
recruit = Skeleton Archer, Skeleton
[/side]
[/scenario]
</syntaxhighlight>

----

[[MakingCampaignInWML2|Part 2: Expanding the campaign definition]]

MakingCampaignInWML4

2021-11-25T16:53:41Z

Jarom: Created page with "'''Custom macros and events''' After going through part 1, part 2 and part 3 we know the basics of m..."

'''Custom macros and events'''

After going through [[MakingCampaignInWML|part 1]], [[MakingCampaignInWML2|part 2]] and [[MakingCampaignInWML3|part 3]] we know the basics of making a campaign - you could almost make one with the information you have now, but let's be honest, that would be kinda boring. We're going to improve the storytelling and gameplay using events, but before that we're going to learn how to make our own macros because that's extremely useful for making various things.

== Creating custom macros ==

Up until now we've been using macros defined by the game and if you checked game data out of curiosity, you might know how they are made. It's good to know [https://github.com/wesnoth/wesnoth/tree/master/data/core/macros how to find them], but that's not necessary for now. We can place our macros anywhere, but for those that are used in various scenarios we typically place them in ''utils'' or ''macros'' folders - practice varies, as both names are not recognized by ''[binary_path]''. Therefore, we're going to first add the folder to our campaign. To do that, in ''_main.cfg'', in ''#ifdef'' section, we're going to place the following line:

<syntaxhighlight lang=wml>
{~add-ons/WML_Tutorial/utils}
</syntaxhighlight>

It tells the game to load all .cfg files inside the ''utils'' folder of our add-on, just like we did with scenarios.

Macros must be defined before they are used, so place this before all other similar lines, notably the one loading scenarios, but not necessarily before ''[binary_path]'' because it's typically not using it.

Obviously you have to adjust the content of the line to match your add-on's folder name, and if you're using ''macros'' instead of ''utils'' as folder name, change that too, but hopefully that's something you know at this point.

Now that we have included the folder, we have to create a file with .cfg extension inside. If it's a generic file, we typically name it ''utils.cfg'' or ''macros.cfg'', if it's something more specific we can name it ''scenario-macros.cfg'', ''bigmap.cfg'', ''abilities.cfg'' etc. For the purpose of this tutorial we're going to create one named ''heroes.cfg'', and the other one named ''bigmap.cfg''.

Making ("defining") a custom macro is typically like that:

<syntaxhighlight lang=wml>
#define MACRO_NAME ARGUMENT1 ARGUMENT2
[tag]
key = value
other_key = its_value
[/tag]
#enddef
</syntaxhighlight>

What's important is the '''#define MACRO_NAME''', the argument list in the same line and the '''#enddef''' at the end, but it's best to look at examples if in doubt.

=== Creating reusable hero macros ===

We have just one scenario for now, but typical campaigns have more. We have two characters from the beginning, but it's common that some will join us later on. When testing the campaign using '':debug'' and '':cl''/'':n'' commands it's common that we don't get all of them, which might break our recall logic.

For that reason Wesnoth offers a special create/recall syntax: if we try to create a new unit with the same id as one of units on the recall list, the unit from the recall list will be recalled in the specified place instead, and if not, the create action will proceed as normal.

Now we don't want to copy our heroes' code in every place they might appear, because if we're going to change anything, we'd have to change it everywhere. So we're going to move just the contents of their [leader]/[unit] tag into separate argumentless macros. Why only contents? Because it will make it easier to add some situation-specific keys to the tag this way, and use either [leader] or [unit] tags depending on circumstances.

'''TL;DR:''' We're moving some of the code to a macro shared between scenarios because it might be helpful later.

Let's start with Lezarek. Add a code like that to ''heroes.cfg'':

<syntaxhighlight lang=wml>
#define HERO_LEZAREK
id = Lezarek
name = _"Lezarek"
unrenamable = yes
type = Longbowman
#enddef
</syntaxhighlight>

And in the scenario we leave:

<syntaxhighlight lang=wml>
[leader]
{HERO_LEZAREK}
[/leader]
</syntaxhighlight>

It's customary to prefix macros with something meaningful (HERO_ in this case), it makes it easier for autocomplete tools to help us and whoever is going to read this code later (typically you) will have it easier to guess what it does. It also helps in preventing collisions in macro names.

Now with Verbott we're not going to move everything. To ''heroes.cfg'' we'll append:

<syntaxhighlight lang=wml>
#define HERO_VERBOTT
id = Verbott
name = _"Verbott"
unrenamable = yes
type = White Mage
gender = female
[modifications]
{TRAIT_LOYAL_HERO}
{TRAIT_INTELLIGENT}
[/modifications]
#enddef
</syntaxhighlight>

And in the scenario we leave:

<syntaxhighlight lang=wml>
[unit]
{HERO_VERBOTT}
placement = leader
[/unit]
</syntaxhighlight>

Because placement is something that might change between scenarios.

And that's it. You should be able to reuse your heroes in future scenarios now.

=== Creating and tracking a map ===

It was mentioned in the previous part that you can add your map to the intro, and now we're going to learn how. First, in the ''bigmap.cfg'' file we created before, add a macro like that:

<syntaxhighlight lang=wml>
#define TUTORIAL_MAP STAGE
[story]
[part]
[background_layer]
image = maps/background.jpg
scale_horizontally = no
[/background_layer]
[background_layer]
image = maps/wesnoth.png
scale_horizontally = no
base_layer = yes
[/background_layer]
show_title = yes
{STAGE}
[/part]
[/story]
#enddef
</syntaxhighlight>

Now this is a big piece of magic code and you're not going to modify most of it, to the point that you might question why it's not a default wesnoth macro. You can change the name of the macro of course. If you have your own map, replace just the ''image = maps/wesnoth.png'' line, but it's unlikely that you're making your own background, so you probably won't replace the other layer.

Further explanations are for the curious ones:

:Most of the keys in '''[background_layer]''', that is, '''scale_vertically=''', '''scale_horizontally=''' and '''keep_aspect_ratio=''' are there to make the graphics scale properly and fill the screen of any device without looking weird. However, default values of ''scale_vertically'' (yes) and ''keep_aspect_ratio'' (yes) are good for us, so we don't have to set those manually.
:Meanwhile, '''base_layer = yes''' makes this picture the one, to which all coordinates of subsequent '''[image]''' tags (usually hidden in macros) are aligned to, and make them scale properly along with the map picture. All of those are well-thought means to keep the map looking nice on any screen size, and have to be modified only if you wish to achieve some clever non-standard effects, but that's unlikely.

You might notice that we need an argument for this macro. This argument is typically another macro, whose contents are macros describing images… yeah, that's a lot of macros in macros. Let's make those for scenario 1:

<syntaxhighlight lang=wml>
#define JOURNEY_01_NEW
{NEW_BATTLE 191 570}
#enddef
</syntaxhighlight>

This will place a single battle marker somewhere northeast of Blackwater port when given as argument to the macro before. Now all we need to do is place the following macro call in scenario, preferably just after ''[story]'' to keep it logically together:

<syntaxhighlight lang=wml>
{TUTORIAL_MAP {JOURNEY_01_NEW}}
</syntaxhighlight>

But that's for the first scenario. To make one for the second scenario we typically do something like that:

<syntaxhighlight lang=wml>
#define JOURNEY_01_OLD
{OLD_BATTLE 191 570}
#enddef

#define JOURNEY_02_NEW
{JOURNEY_01_OLD}
{NEW_JOURNEY 204 564}
{NEW_JOURNEY 211 557}
{NEW_JOURNEY 219 550}
{NEW_BATTLE 230 537}
#enddef
</syntaxhighlight>

Note that we first created a macro old journey. You could ask why, when all it does is to provide one value for the next journey - well, there are two reasons, first, it helps maintain some logic, as the OLD macro is practically the same as the NEW macro, and second, if we wanted to add third scenario, we'd start with making something like that:

<syntaxhighlight lang=wml>
#define JOURNEY_02_OLD
{JOURNEY_01_OLD}
{OLD_JOURNEY 204 564}
{OLD_JOURNEY 211 557}
{OLD_JOURNEY 219 550}
{OLD_BATTLE 230 537}
#enddef
</syntaxhighlight>

This time it's much more than just one value, and it reuses the previously created OLD macro. We can chain OLD macros as much as we want and making changes in journey in one stage will automatically propagate to all subsequent journeys without having to copy the change manually.

For selecting a proper positioning for journey markers, you mostly have to experiment yourself. Things you might want to know if you plan to do that:

*Markers are centered on the point you select
*You can use NEW_REST/OLD_REST instead of NEW_BATTLE/OLD_BATTLE for dialogue and cutscene scenarios, it looks like a flag instead of crossed swords - see HttT
*Battle and rest icons are bigger than journey dots, so you typically want to give them slightly more space around
*It's best to first make the NEW journey, often starting with placing the rest/battle marker and then making a believable route to them, then experiment with it a lot to make it smooth and good looking, and only after that copy the content exactly to OLD, and run the search/replace function from NEW to OLD on this part - you'll save some editing time that way

=== Creating a macros only used in one file and inline macros ===

Sometimes you're going to frequently reuse a part of a code in one scenario but not in other places. There's no point in placing it inside ''utils''/''macros'' then, as it's often meaningless without context. So you should define it somewhere in that file, and then you can use '''#undef''' directive to get rid of it afterwards. Don't use ''#undef'' with macros in ''utils'', even if they are not used anymore after some scenarios - this might cause weird errors.
A not very rare usage of macros is placing some text in the middle of a line and it's important that the macro itself doesn't cause a line break. If you're attempting something like that, place ''#enddef'' in the same line as the content. We're going to use both to optimize our ''_main.cfg'' file for possible future changes. First, add the following lines, preferably after ''#textdomain'' but definitely before ''[textdomain]'':

<syntaxhighlight lang=wml>
#define WML_TUTORIAL_PATH
data/add-ons/WML_Tutorial#enddef
</syntaxhighlight>

Of course, you should replace WML_Tutorial with your folder name if it's different, and the macro name as well.

As you can see, we placed here a part of text that's typically used at least twice in your ''_main.cfg'' file (more if you use custom images). Now we can replace our path line inside ''[textdomain]'', that originally looks like:

<syntaxhighlight lang=wml>
path = data/add-ons/WML_Tutorial/translations
</syntaxhighlight>

with

<syntaxhighlight lang=wml>
path = {WML_TUTORIAL_PATH}/translations
</syntaxhighlight>

And similarly the path in [binary_path]:

<syntaxhighlight lang=wml>
path = {WML_TUTORIAL_PATH}
</syntaxhighlight>

If you used custom images in ''[campaign]'', you should change their lines as well.

Finally, at the last line you can put the following:

<syntaxhighlight lang=wml>
#undef WML_TUTORIAL_PATH
</syntaxhighlight>

to get rid of the macro after it's not needed anymore (we'll typically be using either ''~add-ons/'' path or ones relative to ''[binary_path]'' in other files). This helps with keeping the macro list clean and potentially avoid conflicts.

You can say that character count-wise that's not a good difference, but note that your macro name can be shorter, and if you change your folder name for some reason you only have to change it once. Well, for just two usages you might not really need it, but it serves as a good example. Make sure your campaign works after those changes, as mistakes in this part can easily break it.

== Events, actions and objectives ==

Probably the most common thing in Wesnoth are events. You'll surely encounter them during campaign/scenario development, and sometimes during units/multiplayer development as well. In their simplest form they can be expressed as: When a certain thing happens, do some actions.

We won't be covering all details of event development here, but we'll go through some common use cases and you should be able to figure the rest by yourself to a certain extent. You can check the list of in-game events you can use in [[EventWML]] and all the WML action tags that can be used in response in [[ActionWML]].

Let's start with a very common filterless events: prestart and start. The former is typically used for advanced scenario setup - advanced versions of [unit], [item] and [label], setting up variables etc. The latter is usually used for initial dialogues and objectives.

We already wrote a prestart event for our scenario without much explanation and we're going to leave it unchanged for now, keep in mind that you can have more than one prestart event and they will all run one after another before the game screen is shown to the player.

=== Writing a starting dialogue ===

We're going to write a start event now. Without any actions it'll simply look like that:

<syntaxhighlight lang=wml>
[event]
name = start
[/event]
</syntaxhighlight>

But the essence of events are actions. In this case we're going to use the '''[message]''' tag, a part of [[InterfaceActionsWML]]. It's very flexible, but most of the time you're going to use its basic form with only '''speaker=''' and '''message=''' keys, and ''speaker='' is the id of the unit that should speak the content of the ''message='' key.

We'll put the following inside ''[event]'':

<syntaxhighlight lang=wml>
[message]
speaker = Lezarek
message = _"A necromancer! To arms, my friends!"
[/message]
[message]
speaker = MalShack
message = _"Rejoice, puny villagers! Tonight you'll join the ranks of eternals!"
[/message]
</syntaxhighlight>

Yeah, typical SotA style necromancer attack. By the way, out of 16 mainline campaigns as of 1.16.0, 6 start with orc/goblin attack, 3 with undead attack and 2 with bandit attack. Judge for yourself whether it's good or not to increase that number, but it's seemingly nothing shameful to use that cliche.

The dialogue writing is up to you, but it's strongly preferred to have an English version in the code for various important reasons, and use translations to make your own language's version, but it's not an absolute necessity.

Note that we usually place events after ''[side]'' tags to keep some logical order in our file, but it's not a strict rule.

=== Writing objectives: basics ===

Let's also add some custom objectives at the end of our start event. You probably noticed while testing that there's a default objective - defeat enemy leaders. Writing any custom ones will replace it, and new objectives replace old objectives.

Writing objectives is important and somewhat complex. We'll start with the basics, that is, a custom win condition. Keep in mind that it's just a description, it doesn't do anything by itself, but the example will make use of the default win condition which is: all enemies defeated (we only have one enemy).

<syntaxhighlight lang=wml>
[objectives]
[objective]
description = _"Defeat the necromancer Mal-Shack"
condition = win
[/objective]
[/objectives]
</syntaxhighlight>

The '''[objectives]''' tag groups particular objectives into one screen, and a new ''[objectives]'' tag will replace the old one. If you don't want to change anything, use '''[show_objectives]''' instead. Inside ''[objectives]'' you should use '''[objective]''' tag. The ones with '''condition = win''' are the player's goals, and will be shown before those with '''condition = lose''' that describe the player's defeat possibilities, so you should also sort them like that in the code to avoid confusion.

We should also add a defeat condition. The easiest one is the turn limit. All you need to do is to place the macro '''{TURNS_RUN_OUT}''' inside ''[objectives]'' and you'll get a standardized (and usually translated) one. Opposite macro is '''{HAS_NO_TURN_LIMIT}''' but it's often obvious and omitted. There are some other macros with standard texts in [https://www.wesnoth.org/macro-reference.html#file:objective-utils.cfg ''objective-utils.cfg''] macro file.

=== A hero's death ===

We'll obviously lose if our leader dies, but we won't if a hero dies, and both are not written in objectives yet. It's a well-known trick to move both death events and objectives to a separate file in utils or macros folder - typically heroes file or deaths file. In this case we're going to use the ''heroes.cfg'' file.

First, let's write an objective for each. You can also refer to the [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Secrets_of_the_Ancients/utils/sota-utils.cfg sota-utils] file, because there are good solutions there.

<syntaxhighlight lang=wml>
#define OBJECTIVE_DEATH_LEZAREK
[objective]
description = _"Death of Lezarek"
condition = lose
[/objective]
#enddef

#define OBJECTIVE_DEATH_VERBOTT
[objective]
description = _"Death of Verbott"
condition = lose
[/objective]
#enddef
</syntaxhighlight>

Now if you're going to have them together for the rest of the campaign, consider creating just one macro for both, e.g. OBJECTIVES_DEATHS, but if they are typically together but not always, you can make one macro combining the previous macros:

<syntaxhighlight lang=wml>
#define BASIC_DEATH_OBJECTIVES
{OBJECTIVE_DEATH_LEZAREK}
{OBJECTIVE_DEATH_VERBOTT}
#enddef
</syntaxhighlight>

And we're going to put ''{BASIC_DEATH_OBJECTIVES}'' into our scenario's ''[objectives]'' tag.

Now we actually should handle their deaths:

<syntaxhighlight lang=wml>
#define HERO_DEATH_EVENTS
[event]
name = last breath
[filter]
id = Verbott
[/filter]
[message]
speaker = Verbott
message = _"No! How could the great me meet my end in this nowhere!"
[/message]
[endlevel]
result = defeat
[/endlevel]
[/event]
[event]
name = die
[filter]
id = Lezarek
[/filter]
[message]
speaker = Verbott
message = _"Lezarek! How dare you die on me! I can't lead troops by myself!"
[/message]
[endlevel]
result = defeat
[/endlevel]
[/event]
#enddef
</syntaxhighlight>

Note the '''[filter]''' tag. Both last breath and die events must have a filter tag that will narrow down units whose deaths will trigger those events - we don't bother with deaths of simple cannon fodders. This tag is very widespread in various events and actions, so there's no running from it. It usually takes a '''[[StandardUnitFilter]]''' as content, but there are also other filters for different tags, see [[FilterWML]]. Obviously there's no filter for ''start and ''prestart'' events.

The '''[endlevel]''' tag from [[DirectActionsWML]] will cause the scenario to end, either as victory or defeat depending on the value of '''result=''' key.

The second event is actually not strictly necessary in most cases, because we'd lose anyway with no leader, but it's customary to at least say some last words, or if there are more important characters, to say farewell to your dead ally. You can notice that we used different events for both of them - '''last breath''' is when the unit is about to die, but it's still there with 0HP or less, while '''die''' is after it falls into the abyss of nothingness so it can't speak anymore. Sometimes you want to split your death events into two - ''last breath'' with the unit's last words, and ''die'' with ''[endlevel]'' after visual effects of dying.

Don't forget to put our ''{HERO_DEATH_EVENTS}'' macro call somewhere in the ''[scenario]'' (often in the end).

=== Alternative win condition: move to... ===

You might notice that in some scenarios your goal is to move your leader to a specific place rather than killing enemies. We'll go through the basics of this approach. First, an ''[objective]'':

<syntaxhighlight lang=wml>
[objective]
{ALTERNATIVE_OBJECTIVE_CAPTION}
description = _"Move Lezarek to signpost in the north"
condition = win
[/objective]
</syntaxhighlight>

It goes to our ''[objectives]'' of course. You should only use ''{ALTERNATIVE_OBJECTIVE_CAPTION}'' when completing either objective results in win. Sometimes you need to complete both objectives, or one of them is a side/bonus objective.

Now let's write the event that will handle this objective:

<syntaxhighlight lang=wml>
[event]
name = moveto
[filter]
id = Lezarek
x,y = 3,1
[/filter]
[message]
speaker = Lezarek
message = _"We abandon the village! Follow me!"
[/message]
[endlevel]
result = victory
[/endlevel]
[/event]
</syntaxhighlight>

'''Moveto''' events are typically used to handle a situation where a certain unit moved to a specific place. You can define the location in the '''[filter_location]''' subtag of ''[filter]'', but often you just need x and y coordinates that can be given directly in ''[filter]'' and you should treat it as: there exists an unit matching the filter that just finished moving.

Note the ''x,y = 3,1'' line - it's a shorthand for two lines, ''x = 3'' and ''y = 1''. You can use it with most arbitrary keys that only have one value, but in cases other than ''x,y'' it usually impacts readability.

=== Alternative win condition: survive ===

Another common win condition is to survive a certain number of turns. Currently we lose if turns run out, but we can change that. First, let's remove the ''{TURNS_RUN_OUT}'' objective and replace it with:

<syntaxhighlight lang=wml>
[objective]
{ALTERNATIVE_OBJECTIVE_CAPTION}
description = _ "Survive until turns end"
condition = win
show_turn_counter = yes
[/objective]
</syntaxhighlight>

And now handling it:

<syntaxhighlight lang=wml>
[event]
name = time over
[message]
speaker = Lezarek
message = _"The reinforcements are about to come! Surrender, you evil necromancer!"
[/message]
[message]
speaker = MalShack
message = _"Kuh! Persistent ones... I'll be back!"
[/message]
[endlevel]
result = victory
[/endlevel]
[/event]
</syntaxhighlight>

And that's it - our victory ''[endlevel]'' will be called before automatic defeat from time limit. Note the lack of ''[filter]''.

Keep in mind that typically scenarios have only one win condition, occasionally complex one.

== Variables and conditionals ==

You can save some things, usually game state, for later use. If you have some experience with programming, you know why it's important, and if you don't, well, it might come in handy.

Let's assume the following scenario - the keep of our enemy's side has something important for some reason that should be better explained in dialogues, and we should get a bonus in gold when we win if we manage to snatch it.

First, let's declare a variable in our ''prestart'' event. You can do that using '''[set_variable]''' from [[InternalActionsWML]], but typically you're going to use '''{VARIABLE}''' macro like this:

<syntaxhighlight lang=wml>
{VARIABLE enemy_keep_visited no}
</syntaxhighlight>

The first argument is the name of the variable to set and the second argument is the desired value.
Now we should add a separate moveto event that will handle visiting the enemy keep:

<syntaxhighlight lang=wml>
[event]
name = moveto
[filter]
side = 1
[filter_location]
location_id = 2
[/filter_location]
[/filter]
[message]
speaker = unit
message = _"I've recovered the item!"
[/message]
{VARIABLE enemy_keep_visited yes}
[/event]
</syntaxhighlight>

It's slightly different from the ''moveto'' event we know. First, we don't point to a specific id - any unit of side 1 (in this case player's) will trigger it. Second, we don't specify x and y, but '''location_id''' instead - we did the same when placing a label in prestart event, even in the same location - regardless of wherever this location actually is on the map. Convenient.

Second, we used '''speaker = unit''' - obviously there isn't any unit with id like that, it's a special value that points to the unit that acted in the event (if there is any), in this case the unit that moved to the enemy keep. It's actually a variable as well, and in some events there's an analogical '''second_unit''', for example in ''last breath'' and ''die'' events it's the unit who killed the unit in the ''[filter]''.

The ''{VARIABLE}'' macro is the same as last time, just with a different value. It will overwrite the previous value.

Now we need to handle that gold giving stuff. We'll do that using a victory event to make sure we'll get it regardless of how we won.

<syntaxhighlight lang=wml>
[event]
name = victory
[if]
[variable]
name = enemy_keep_visited
boolean_equals = yes
[/variable]
[then]
[gold]
side = 1
amount = 100
[/gold]
[/then]
[else]
[message]
speaker = Verbott
message = _"It's unfortunate that we didn't manage to obtain that item."
[/message]
[/else]
[/if]
{CLEAR_VARIABLE enemy_keep_visited}
[/event]
</syntaxhighlight>

The '''[if]-[then]/[else]''' is a typical conditional structure that can be used in many different places. This, along with '''[variable]''' and other condition tags can be found in [[ConditionalActionsWML]], so make sure to read it someday - I'm not going to elaborate on those.

The '''[gold]''' tag from [[DirectActionsWML]] gives the specified amount of gold to the given side. That's it.

The '''{CLEAR_VARIABLE}''' macro is a shorthand for '''[clear_variable]''' tag, which is used to get rid of a variable completely after it's no longer useful - otherwise it will persist between scenarios and clutter the savegames. It'll silently do nothing if the variable was already cleared before or never existed.

It's also possible to pass a variable's value to any key or even a string, using the so-called variable substitution like that:

<syntaxhighlight lang=wml>
[message]
speaker = $unit.id
message = _"I'm $unit.name!"
[/message]
</syntaxhighlight>

It takes advantage of the previously mentioned unit variable specific to some events with filters, like ''moveto'' or ''die''.

See [[VariablesWML/How to use variables]] for a more in-depth tutorial on variables.

== Next scenario ==

When you create the second scenario just like you created the first one, you probably want to be able to move from scenario 1 to scenario 2. There are 2 ways to do that - first, you can add a next_scenario = id_of_second_scenario key to your ''[scenario]'' tag. This will provide a default for most cases, including the '':n'' debug command. Second, you can add exactly the same key to a specific ''[endlevel]'' tag - this way allows you to branch your scenario progression as you wish, just like with, for example, Muff-Malal Peninsula/Isle of the Damned in HttT. You can even pass a value of a variable containing the next scenario's id into the '''next_scenario=''' key if you have really complicated progression logic. But usually you're just going to put it directly in ''[scenario]'' and be done with it.

== Other features ==

In this tutorial we barely scratched the surface of deep possibilities of WML, especially [[ActionWML]], but we covered most of the common usages for campaigns and you can always read the [[ReferenceWML|actual documentation]] to find what you need.

MakingCampaignInWML3

2021-11-25T16:05:52Z

Jarom: Created page with "'''Part 3: Improving the first scenario''' In the first part of this tutorial we've made the very basic scenario to be able to run the campaign. In th..."

'''Part 3: Improving the first scenario'''

In the [[MakingCampaignInWML|first part]] of this tutorial we've made the very basic scenario to be able to run the campaign. In the [[MakingCampaignInWML2|second part]] we added a little difficulty-based change in enemy leader and put a ''#textdomain'' directive at the beginning - both didn't really change much, and our first scenario is still very barebones, so it's high time we do something with it.

There's no TL;DR this time, but you can skip the parts you're not interested in - they are all technically optional and independent.

== Time schedule ==

Our scenario currently has no ongoing day/night schedule and the corresponding part of the game window is black. You can add '''[time]''' tags to the ''[scenario]'', but almost always you're going to use predefined macros instead, so we're not going to cover that - see [[TimeWML]] if you want. All time macros are in one file, but most important ones are listed [https://www.wesnoth.org/macro-reference.html#file:schedules.cfg here]. That being said, you're probably going to use '''{DEFAULT_SCHEDULE}''' for normal scenarios and '''{UNDERGROUND}''' for those in caves, rarely '''{INDOORS}''' for those in buildings. Put one of those inside ''[scenario]'' and you're done.

Sometimes we want our scenario to start at a specific time of day. You could make your own schedule, switching the order, but it's counterproductive - use '''current_time=''' instead. It takes a number corresponding to the order of schedules. For example, when using '{DEFAULT_SCHEDULE}'', ''current_time=1'' is dawn, which is default, but ''current_time=4'' will make us start at dusk instead. In the example we're going to use ''current_time=5'', that is, our scenario will start at first watch.

<syntaxhighlight lang=wml>
{DEFAULT_SCHEDULE}
current_time = 5
</syntaxhighlight>

Rarely a part of our map is underground while the rest is above the ground. In this case determine which is dominant and put that in the ''[scenario]'' directly. For the rest, use '''[time_area]'''. In addition to ''[time]'' and ''current_time='' like in ''[scenario]'', it also takes a '''list of x and y''' coordinates affected. Usually you're going to prepare this in scenario editor mode of map editor, not manually, even though it's possible, and then paste it into your scenario.

As a side note, you can point your ''map_file='' key to an editor-generated scenario file instead of just a map, and it'll automatically import everything, including ''[time_area]'' and ''[side]'' tags. However, it's easy to make a mistake and import too much, so be careful if you try that.

In this scenario we're not going to use any ''[time_area]'' tags, but here's an example how it might look like:

<syntaxhighlight lang=wml>
[time_area]
x = 1-10
y = 1-5
{UNDERGROUND}
[/time_area]
</syntaxhighlight>

It'll make a 10x5 area in the right corner to always have underground time, instead of usual. You can also add and remove those during the scenario, and make it automatically affect only cave tiles, but those are advanced features.

== Time limit and experience modifier ==

Currently, unlike most campaign scenarios, ours has no time limit. Let's add it:

<syntaxhighlight lang=wml>
turns = 25
</syntaxhighlight>

That being said, usually the turn limit is progressive with difficulty. We could write it like that:

<syntaxhighlight lang=wml>
#ifdef EASY
turns = 25
#endif
#ifdef NORMAL
turns = 23
#endif
#ifdef HARD
turns = 20
#endif
</syntaxhighlight>

But there's no point. There's a macro for that:

<syntaxhighlight lang=wml>
{TURNS 25 23 20}
</syntaxhighlight>

And that's it. Just put the macro in your ''[scenario]'' tag and maybe adjust the values for each difficulty. Just in case, remember that it's going to make the player lose when turns run out, so it's usually lower as the difficulty progresses.

If you have four difficulties using normal defines, use '''{TURNS4}''' instead, e.g. ''{TURNS4 25 23 20 18}''

The other thing you might want to set is '''experience_modifier=''' key. It'll cause your unit to advance faster or slower, and might be a part of balance or difficulty. Most campaigns have it at default 100%. If you want to make it, let's say, 200%, add:

<syntaxhighlight lang=wml>
experience_modifier = 200
</syntaxhighlight>

If you want to make it difficulty-dependent, you can use '''{QUANTITY}''' macro (or '''{QUANTITY4}''' to cover ''NIGHTMARE'' difficulty):

<syntaxhighlight lang=wml>
{QUANTITY experience_modifier 60 100 140}
</syntaxhighlight>

However, if for some reason the experience modifier changes mid-campaign, either due to scenario change or difficulty change, weird things might happen, so refrain from both. Keep in mind that players can change difficulty at the beginning of a new scenario, unless set otherwise in ''[campaign]'' tag (see previous tutorial).

== Intro ==

While playing wesnoth campaigns you probably noticed, that usually before a scenario there are story panels, which introduce the story or narrate the events happening off-screen. Making those is relatively easy. First, put a [[IntroWML|'''[story]''']] tag inside your ''[scenario]''. Everything related to the intro will go into ''[story]''. You can have several ''[story]'' tags and they will play one by one in order of appearance, but there's usually no point in doing that.

The ''[story]'' itself has few configuration options, but you're unlikely to use them normally. What you will add though, are '''[part]''' tags. In its simplest form they look like that:

<syntaxhighlight lang=wml>
[part]
story = _"The Example village lived in peace, protected by its mighty garrison of volunteers. Until one night the ugly necromancer came with its fearsome minions..."
[/part]
</syntaxhighlight>

It'll display the text on the bottom of a black screen. Not cool. Let's add the '''background'''. Default backgrounds are in the story folder inside images, but of course you can add your own and they will be localized using the content of your ''[binary_path]''. It's pretty much the same as the ''background='' key in ''[campaign]''.

<syntaxhighlight lang=wml>
background = "story/landscape-hills-01.jpg"
</syntaxhighlight>

Among other frequently used keys are '''music=''' which will change the music in background after this part is reached, and '''show_title=''', which when set to yes will display the scenario name on the top of the screen. We'll only use the latter in the example, as it's commonly used with last ''[part]'' in your ''[story]''.

Of course, every ''[story]'' can have multiple ''[part]''s inside, but note several things:
*Many scenarios don't have any [story] at all. The progression is made by dialogues instead
*You don't have to force yourself to put many ''[part]''s when one is enough.
*You don't have to tell players every single detail of your story setting, and even if you do, they might just skip it anyway.
Knowing that, have fun in adding as many ''[part]''s as you deem necessary. The example intro we're using looks like that:

<syntaxhighlight lang=wml>
[story]
[part]
story = _"The Example village lived in peace, protected by its mighty garrison of volunteers. Until one night the ugly necromancer came with its fearsome minions..."
background = "story/landscape-hills-01.jpg"
show_title = yes
[/part]
[/story]
</syntaxhighlight>

It's also possible to add a map showing our path and battle locations, but we'll do that later.

== Flavours ==

=== Music ===

There is a defined music playlist that will play by default, but you can override it with your own for added immersion. For that, there's a '''[music]''' tag, but you're almost never going to use it directly. Instead, use several macros:

One of '''{SCENARIO_MUSIC}''' or '''{INTRO_AND_SCENARIO_MUSIC}'''

there could be an optional '''{LET_INTRO_MUSIC_FINISH}''' here but it currently (1.16.0) doesn't work as expected

and subsequently any number of '''{EXTRA_SCENARIO_MUSIC}'''

You can also replace the music mid-scenario but it's rarely used and we're not going to cover that. All related macros are in [https://github.com/wesnoth/wesnoth/blob/master/data/core/macros/sound-utils.cfg ''sound-utils.cfg''] file, and most are documented [https://www.wesnoth.org/macro-reference.html#file:sound-utils.cfg here].

The difference between ''{SCENARIO_MUSIC}'' and ''{INTRO_AND_SCENARIO_MUSIC}'' is that the latter takes an additional first parameter, a music that will play instead of the default one (Revelation by Joseph G. Toscano) during the intro. Note that you can also use the ''[part]'''s own ''music='' key, and when you're not using any of those the music will just continue from the main menu without any interruptions or changes.

You can, for example, give your scenario a serene feeling by adding something like that inside your ''[scenario]'' tag:

<syntaxhighlight lang=wml>
{SCENARIO_MUSIC "elvish-theme.ogg"}
{EXTRA_SCENARIO_MUSIC "travelling_minstrels.ogg"}
</syntaxhighlight>

However, we're going to have more impactful music in our scenario, to accentuate the sudden night attack.

<syntaxhighlight lang=wml>
{INTRO_AND_SCENARIO_MUSIC "transience.ogg" "the_city_falls.ogg"}
{EXTRA_SCENARIO_MUSIC "siege_of_laurelmor.ogg"}
{EXTRA_SCENARIO_MUSIC "frantic.ogg"}
{EXTRA_SCENARIO_MUSIC "vengeful.ogg"}
{EXTRA_SCENARIO_MUSIC "frantic-old.ogg"}
</syntaxhighlight>

What music to pick when is a delicate topic we're not touching here. You can also put your own music, and the game will try to look for it in the music/ folder in your add-on folder (if you set the ''[binary_path]'' properly).

=== Labels ===

You can put text describing a certain tile (sometimes a certain area around it as well) using [https://wiki.wesnoth.org/InterfaceActionsWML#.5Blabel.5D '''[label]'''] tag. It will show below the unit standing there.

<syntaxhighlight lang=wml>
[label]
x = 3
y = 1
text = _"To the far lands"
[/label]
</syntaxhighlight>

This will show the text ''To the far lands'' below the hex 3,1.

You can do the same using macro:

<syntaxhighlight lang=wml>
{SET_LABEL 3 1 _"To the far lands"}
</syntaxhighlight>

You can also do that dynamically later in the game, using the same syntax. There's one more thing, slightly ahead of our current progress:

<syntaxhighlight lang=wml>
[event]
name = prestart
[label]
location_id = 2
text = _"The ugly necromancer's camp"
[/label]
[/event]
</syntaxhighlight>

This code will add the text at map-defined side 2 starting position, without having to specify the coordinates. You can also use this with other named map locations defined in the map editor. However, this will not work if ''[label]'' is directly in ''[scenario]'' and there's no predefined macro for it.

=== Map decorations ===

In addition to terrain placed in the map editor you can put some additional graphics on your map using [https://wiki.wesnoth.org/InterfaceActionsWML#.5Bitem.5D '''[item]'''] tag. It's syntax is similar to the one in ''[label]'', except that you replace ''text='' with '''image=''' key that should point to an image in your add-on's or game's images folder. In base game images for that are either in scenery or items subfolders. Note, however, that many of those indicate something that player can interact with, and therefore shouldn't be used without reason.

<syntaxhighlight lang=wml>
[item]
x = 3
y = 1
image = "scenery/signpost.png"
[/item]
</syntaxhighlight>

And of course there's a macro for that. Note that arguments are in different order than with labels.

<syntaxhighlight lang=wml>
{PLACE_IMAGE "scenery/signpost.png" 3 1}
</syntaxhighlight>

Keep in mind that despite being named ''[item]'', they don't do anything by themselves. For giving items to units, you have to use ''[object]'' inside ''[event]'', but that's for later.

== Configuring player side ==

In the first part we've set up two [[SideWML|''[side]'']] tags with bare minimum needed for them to work. Now we're going to expand both of those to match the standards.

First, we're going to move our leader to a separate subtag. This is a new feature that greatly improves readability of the ''[side]'' tag. Replace our ''type='' key with:

<syntaxhighlight lang=wml>
[leader]
type = Longbowman
[/leader]
</syntaxhighlight>

Next, we're going to configure the side itself. Our current starting gold is 100 and it's independent from difficulty. To set starting gold we use:

<syntaxhighlight lang=wml>
gold = 200
</syntaxhighlight>

However, since gold is one of main balance factors, it's better to make it difficulty-dependent. Like with turn limit, there's a macro for that:

<syntaxhighlight lang=wml>
{GOLD 250 200 150}
</syntaxhighlight>

And of course there's a '''{GOLD4}''' version that includes ''NIGHTMARE''. If you skipped the part about time limit, you can go back for details [[#Time limit and experience modifier|there]].

Analogical situation is with income - you have 2 by default and you can set a different value using '''income=''' key. However, there are things you need to remember: first, your actual income will be 2 more than what you write. That is, if you write ''income=2'', you'll have 4 actual income per turn. Second, there are macros for income.

<syntaxhighlight lang=wml>
{INCOME 6 4 3}
</syntaxhighlight>

This will make your base income to be 8 on easy and 5 on hard. Of course there exists an '''{INCOME4}''' version. If you want to truly have no base income, use this instead:

<syntaxhighlight lang=wml>
{NO_INCOME}
</syntaxhighlight>

Keep in mind that it doesn't affect villages. You can set those using '''village_gold=''' and '''village_support=''' keys, and they work normally, without adding any arbitrary values.

Now we're going to focus on another two keys: '''fog=''' and '''shroud='''. You should have learnt about those over the course of several campaigns. Those can be turned on or off separately for all sides, and if they are on, there are several additional keys that can be used describing fog and shroud behaviour with allied sides. They are further documented in [[SideWML]]. All you need to know for now is that we're going to turn on fog for our side and leave shroud as its default, which is off:

<syntaxhighlight lang=wml>
fog = yes
</syntaxhighlight>

Now we're going to set teams. Obviously with only two sides no real alliances are going to happen, but there exists a status table which makes use of this:

<syntaxhighlight lang=wml>
team_name = Humans
user_team_name = _"Humans"
</syntaxhighlight>

First one describes actual alliances, and is a list. So if we want to have a side allied with ours, it would need to have Humans in its team name as well. If someone should be allied with both Humans and Undead, we would write:

<syntaxhighlight lang=wml>
team_name = Humans, Undead
</syntaxhighlight>

The second one is translatable and shows in the status table. It doesn't need to match the team name, though it often does if it only contains one value (no commas). Try to keep it short.

And that's it for now. There are many other keys you can use, but in fact they are rarely used. See the [[SideWML|docs]] if you want to check them for some reason.

== Player's side units ==

We're done with configuring the side itself, but we still haven't really configured the leader. We moved him to the separate subtag, but it didn't change anything - it'll still have a randomly generated changeable '''name''', auto-generated '''id''', and will appear on side 1 starting position. We're going to let him appear there because that's what we usually want, but let's name him, he's our hero after all:

<syntaxhighlight lang=wml>
id = Lezarek
name = _"Lezarek"
</syntaxhighlight>

We also set his id, because it simplifies referencing him later, and we usually reference our heroes a lot. Note that id is often, but not necessarily the same, and id must not be translatable, while name should be, because some languages use different alphabets.

If we want to prevent players from changing his name, we can add the following:

<syntaxhighlight lang=wml>
unrenamable = yes
</syntaxhighlight>

Heroes usually come in pairs or trios, for a simple reason - it simplifies dialogue writing a lot. It would be a pity if our single hero talked to air, or to enemies only, and using a narrator is the last resort. Wars are a group sport, and most commanders have an adiutant. Therefore, we're going to add another unit inside our ''[side]'' tag:

<syntaxhighlight lang=wml>
[unit]
id = Verbott
name = _"Verbott"
unrenamable = yes
type = White Mage
gender = female
placement = leader
[modifications]
{TRAIT_LOYAL_HERO}
[/modifications]
[/unit]
</syntaxhighlight>

There's a lot going on here, let's skip the first four keys we already know and focus on new ones. We made our White Mage ''female'' - she's a hero, so it's recommended to make their gender non-random. If we left it out, it would be ''male'' by default. To make gender random we have to explicitly use a different key, '''random_gender=yes'''.

Then, '''placement = leader''' tells the game to put her near our leader. We could provide a named location or x and y instead or do some other tricky stuff, but if we do nothing she will silently appear on our recall list, which is obviously not recommended under normal circumstances.

Then, we placed a macro '''{TRAIT_LOYAL_HERO}''' inside '''[modifications]'''. The ''[modifications]'' tag is used to place certain things, usually traits, but also custom advancements and objects. ''{TRAIT_LOYAL_HERO}'' is a variant of the loyal trait, with different visuals - it gives a silver crown instead of a bronze ring and changes unit ellipse. Those are markings of a story-important hero, but will not cause defeat when they die by themselves - we'll fix that later.

Note that units normally have 2 trait slots, and we just took one. The other one will be randomly filled, but that shouldn't be a case for our hero - let's also give her the intelligent trait using the '''{TRAIT_INTELLIGENT}''' macro by placing it inside ''[modifications]'' as well.

And that's it. We could obviously add more, but it's usually better to let the player recruit them. Note that we can add units dynamically later but we have to keep some things in mind:
*There's no ''[leader]'' tag outside ''[side]'', you must use [https://wiki.wesnoth.org/DirectActionsWML#.5Bunit.5D '''[unit]'''] with '''canrecruit=yes''' and specify placement;
*Outside ''[side]'', the ''[unit]'' tag must have a specified ''side='' key;
*There are [https://www.wesnoth.org/macro-reference.html#file:unit-utils.cfg macros] that might help you with those.

== Configuring enemy side ==

The last thing in this part will be configuring the enemy. First let's fill the same keys as with player side, but with different values:

<syntaxhighlight lang=wml>
[side]
side = 2
controller = ai
recruit = Skeleton Archer, Skeleton

{GOLD 100 150 200}
{INCOME 3 6 9}

team_name = Undead
user_team_name = _"Undead"

[leader]
id = MalShack
name = _"Mal-Shack"
#ifdef EASY
type = Dark Sorcerer
#else
type = Necromancer
#endif
[/leader]
[/side]
</syntaxhighlight>

Note that we didn't set fog for this side because usually there's no point in doing that. However, we could do that if we needed it for some reason - allies with shared vision, sighted events etc. Also, gold and income are growing instead of shrinking with difficulty.

We also didn't set ''unrenamable=yes'' because ai won't ever rename its units. We don't need to think about players using console commands because that's not a normal game state.

Another thing to note is that you don't necessarily have to avoid most special characters in ids, but it's better if you do, or at least wrap them in double quotes. There are working examples of id with minus sign though. In many cases we can avoid setting the enemy leader's id, but it's preferable to set it if we're planning to have them say something.

We're not giving the enemy any additional units this time (well, we could but we don't have to), so we're done.

== Troubleshooting ==

Mistakes that are usually done at this stage include:

Typos
:If something doesn't work, you might have not typed the key or value properly
invalid, misplaced or not closed tags - this tutorial should make it clear where to put everything, but refer to the full code below just in case. Once more a reminder, that order of tags and macro arguments usually matters, while order of keys usually doesn't. However, different tags placed in [scenario] should usually work the same regardless of which order they are placed in, that is, [item] and [side] can appear in any order, while [side] and [side] must appear in order of their side= keys.

Invalid macros, wrong argument order
:Macros are very inflexible and you have to do things exactly as defined, so pay attention to examples

Images don't show
:Check filename, path, extension, pay attention to underscores/minuses in names as they sometimes differ, this tutorial assumes you set your [binary_path] properly

Problems with unit types
:Consult units.wesnoth.org or source to check if your ids are valid

Full code:

<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"

{DEFAULT_SCHEDULE}
current_time = 5

{TURNS 25 23 20}

[story]
[part]
story = _"The Example village lived in peace, protected by its mighty garrison of volunteers. Until one night the ugly necromancer came with its fearsome minions..."
background = "story/landscape-hills-01.jpg"
show_title = yes
[/part]
[/story]
{INTRO_AND_SCENARIO_MUSIC "transience.ogg" "the_city_falls.ogg"}
{EXTRA_SCENARIO_MUSIC "siege_of_laurelmor.ogg"}
{EXTRA_SCENARIO_MUSIC "frantic.ogg"}
{EXTRA_SCENARIO_MUSIC "vengeful.ogg"}
{EXTRA_SCENARIO_MUSIC "frantic-old.ogg"}

{SET_LABEL 3 1 _"To the far lands"}
{PLACE_IMAGE "scenery/signpost.png" 3 1}

[event]
name = prestart
[label]
location_id = 2
text = _"The ugly necromancer's camp"
[/label]
[/event]

[side]
side = 1
controller = human
recruit = Bowman, Spearman

{GOLD 250 200 150}
{INCOME 5 4 3}

fog = yes

team_name = Humans
user_team_name = _"Humans"

[leader]
id = Lezarek
name = _"Lezarek"
unrenamable = yes
type = Longbowman
[/leader]
[unit]
id = Verbott
name = _"Verbott"
unrenamable = yes
type = White Mage
gender = female
placement = leader
[modifications]
{TRAIT_LOYAL_HERO}
{TRAIT_INTELLIGENT}
[/modifications]
[/unit]
[/side]

[side]
side = 2
controller = ai
recruit = Skeleton Archer, Skeleton

{GOLD 100 150 200}
{INCOME 3 6 9}

team_name = Undead
user_team_name = _"Undead"

[leader]
id = MalShack
name = _"Mal-Shack"
#ifdef EASY
type = Dark Sorcerer
#else
type = Necromancer
#endif
[/leader]
[/side]

[/scenario]
</syntaxhighlight>

----

[[MakingCampaignInWML4|Part 4: Custom macros and events]]

MakingCampaignInWML2

2021-11-25T15:24:29Z

Jarom: fixed heading

'''Expanding the campaign definition (and macros)'''

In the [[MakingCampaignInWML|previous part]] of this tutorial we made a minimal working example that could be run and played, but it's far from the usual content of a campaign. If you have ADHD or for some other reason don't want to read all the descriptions, jump to the [[#TL;DR|TL;DR]].

== Textdomain ==
Let's start by introducing the very common content of add-on's _main.cfg file, that is the textdomain. It allows your campaign to be translated and it's better to do that at the very start than try to add it later, especially since it's mostly unobtrusive and doesn't take much time. First, let's add a [[GettextForWesnothDevelopers#The_textdomain_tag|'''[textdomain]''']] tag, it's typically located before [[CampaignWML|'''[campaign]''']] and looks like:

<syntaxhighlight lang=wml>
[textdomain]
name = wesnoth-WML_Tutorial
path = data/add-ons/WML_Tutorial/translations
[/textdomain]
</syntaxhighlight>

The '''name=''' key is most important. Your textdomain name should start with ''wesnoth-'', and after that it typically uses your add-on's folder name for a good reason - this name will be used as folder name again.

The '''path=''' key contains the path to your translation root relative to the userdata folder, typically it's the same as in ''[binary_path]'' but with ''/translations'' at the end.
:You don't have to add /translations at the end but you should. Although having your main folder as translation root will flatten your folder structure for translation, which can possibly make access to it faster, it'll be confusing for others, so it's discouraged.

The reference advises to create translations folder now, but it doesn't need to have content for now and actually everything will work even if you don't.

Note that mainline campaigns have different content in this tag because their translations are handled by game core, so don't copy their way.

Now, we're going to add a '''#textdomain''' directive. It's typically the first line of any ''.cfg'' file containing translatable strings. For our example it'll be:

<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial
</syntaxhighlight>

'''#texdomain''' is a fixed part, and after a space there should be your textdomain name, exactly the same as in ''name='' key in ''[textdomain]'' tag. You should place the exact same line in your scenario file, but not in your map file. If you have a .cfg file that you're sure that it won't have any translatable strings, you can use '''#wmllint: no translatables''' instead, but if you're not sure, just add the full ''#textdomain'' directive or leave nothing. Don't put any of these in files other than those with .cfg extension.

== Visuals ==

Your campaign entry in the campaigns menu looks very barebones for now. Let's add a little variety.
First, an icon. It will show on campaigns list and is considered pretty mandatory. It's customary to use an image that's usually displayed on the map, like an item or a unit. In this example we're going to use a book from mainline as an icon:

<syntaxhighlight lang=wml>
icon = "items/book3.png"
</syntaxhighlight>

Place this inside your ''[campaign]'' tag. If you're planning to use custom images, see the [[#Note about custom images|note about paths]] below. Note that it's customary to wrap file paths and certain other strings in double quotes, but usually they are not necessary. Don't add the _ (underscore) before though, because this is NOT translatable.

Other images also go inside ''[campaign]'' tag but are much more optional, even mainline campaigns not always use them:

<syntaxhighlight lang=wml>
image = "portraits/humans/longbowman.png"
</syntaxhighlight>

This will show below the description (we'll add one soon) and it's usually a unit/character portrait. It's optional, but quite common. We're using the portrait of Wesnoth's longbowman as an example.

<syntaxhighlight lang=wml>
background = "story/grim-altar.jpg"
</syntaxhighlight>

This is a new feature, introduced in 1.15 versions, so it's not commonly used. It replaces the default background of the campaign menu when our campaign is selected. Typically uses story/cutscene background images. Note that Wesnoth backgrounds in the story folder have atypical .jpg extension, but it's not necessarily the case for other background images.

=== Note about custom images ===
:Usually you could access an image, e.g. "snow-golem.png" in your add-on's images folder by just writing "snow-golem.png". But that's because you use [binary_path] to access it. However, our [binary_path] is inside #ifdef, which only loads AFTER we start the campaign, so the game doesn't know about it when we're in campaign selection menu.
:To use custom images in your [campaign] tag you have to use fully qualified names, relative to userdata folder, that is, the same as you used in [binary_path] and [textdomain]. For the afforementioned snow golem image you'd have to write ''data/add-ons/WML_Tutorial/images/snow-golem.png''.
:There's a trick that can simplify it, but you'll learn it later.

Now, let's move to the '''description'''. In mainline campaigns it's usually splitted into two parts, the actual description and difficulty/length addition, for translation purposes. Don't forget to mark each part as translatable whether you split or not.

<syntaxhighlight lang=wml>
description = _"Basic, but slowly expanding example for tutorial.
Great, emotional story not yet guaranteed.

" + _"(Novice? level, 1 scenario.)"
</syntaxhighlight>

Note that you mustn't tabulate the description inside quotes in multiline description, as it'll be added to the string and shown in the game. You can use fancy formatting, as described [[InterfaceActionsWML#Formatting|here]].
:Centering the description
:There exists a key description_alignment= if you want to center your description like the one in The Sceptre of Fire. It doesn't add the italics though.
:<syntaxhighlight lang=wml>
description_alignment = center
</syntaxhighlight>
:It won't appear in code examples later.

There's one more purely visual thing, but it only shows in save filenames - the '''abbrev'''. It's recommended to set that. First derive an abbreviation of your campaign from its name. For example, The Rise of Wesnoth is abbreviated TRoW and Under the Burning Suns is UtBS. For this example add-on, we'll use WMLT. Note that abbreviations vary between languages, so this is translatable.

<syntaxhighlight lang=wml>
abbrev = _"WMLT"
</syntaxhighlight>

:You should, but don't have to avoid clashes in the abbrev= key.
:It's preferable, but not necessary that it doesn't clash with other add-ons. However, as it only affects save filenames, it's unlikely to cause problems for the game itself - it could at most overwrite saves if for some reason scenario names are the same. It might affect the community though.
:Example: the abbreviation conflict between Era of Magic and Era of Myths, causing the former to use the abbreviation EoMa. But you don't have to bother about it at this point that much.

== Sorting ==
There's a default order of campaigns appearing in the menu and ours will probably be last for now. Set your campaign's rank to something bigger than 300, the lower it is, the bigger priority on default sorting it's going to have, if not set it will appear somewhere near the end. Check in [[CampaignWML]] for a detailed explanation.

<syntaxhighlight lang=wml>
rank = 970
</syntaxhighlight>

Note that you can also sort by name (alphabetically) and by time. For the former, set ''start_year='' and ''end_year='' keys, for example:

<syntaxhighlight lang=wml>
start_year = "10 BW"
end_year = "10 YW"
</syntaxhighlight>

In this campaign we're going to use a simpler form that replaces both of them to set our campaign to happen a year after "The Story of Two Brothers":

<syntaxhighlight lang=wml>
year = "364 YW"
</syntaxhighlight>

As it was said, it only affects sorting by timeline and nothing else, so if your campaign for some reason isn't placed in the Wesnoth universe or the date is not determined, just omit this key.

== Difficulty ==

Difficulty in campaigns is currently added using '''[difficulty]''' tags. It was different before, so not all add-ons follow this convention. The tag looks as follows:

<syntaxhighlight lang=wml>
[difficulty]
define = EASY
image = "units/human-loyalists/bowman.png"
label = _"Recruit"
description = _"Beginner"
[/difficulty]
</syntaxhighlight>

It should be placed inside the ''[campaign]'' tag, like ''[side]'' in ''[scenario]''. Don't forget about correct indentation.

First key, '''define=''' works similarly to the one in ''[campaign]'' tag, and is also checked with ''#ifdef''. But instead of only loading resources when campaign starts, it will only put certain parts of code in the campaign when it's started with the right difficulty, so it doesn't have effect on the ''[campaign]'' tag itself and will be used in scenarios (or units) instead. Example:

<syntaxhighlight lang=wml>
#ifdef EASY
type = Dark Sorcerer
#else
type = Necromancer
#endif
</syntaxhighlight>

This code if put inside the enemy's ''[side]'' tag will cause their leader to be a Dark Sorcerer if the difficulty is set to ''EASY'', and a Necromancer otherwise. Note that it'll show in examples later.

It's strongly recommended to use a set of: ''EASY, NORMAL, HARD'' if you have three difficulties and add ''NIGHTMARE'' if you have four, because there are some improvements (namely macros) that make use of those.

Second key, '''image=''' should point to an image illustrating the difficulty. It usually follows level progression for a unit or several similar units of different levels. For example, Liberty uses a Peasant (lvl 0) for ''EASY'', Outlaw (lvl 2) for ''NORMAL'' and Fugitive (lvl 3) for ''HARD''. It's purely visual.

Third key, '''label=''' is a translatable string with a flavour text representing the difficulty. It's often the name of the unit on image, but not necessarily.

Fourth key, '''description=''' is also translatable, and it serves as the actual user-visible difficulty name for the ones confused by flavour texts. Note, that you might want to choose from the ones used in mainline and save time on translating and devising a clever descriptive name. Just start the game and look at what was used so far.

Having a single difficulty doesn't really change anything so we'll add two more:

<syntaxhighlight lang=wml>
[difficulty]
define = NORMAL
image = "units/human-loyalists/longbowman.png"
label = _"Veteran"
description = _"Intermediate"
[/difficulty]
[difficulty]
define = HARD
image = "units/human-loyalists/masterbowman.png"
label = _"Commander"
description = _"Hard"
[/difficulty]
</syntaxhighlight>

We'll now use a little trick and append '''~RC(magenta>blue)''' to the images, so their paths will look like:

<syntaxhighlight lang=wml>
image = "units/human-loyalists/longbowman.png~RC(magenta>blue)"
</syntaxhighlight>

It'll cause their images to be coloured like units of default side 2. Again, it's purely visual. See [[ImagePathFunctions#RC: Re-Color function|documentation]] for more.

Note that players can change difficulty mid-campaign by default. To prevent that, you can add '''allow_difficulty_change = no''' to your ''[campaign]'' tag.

== MACROS ==

Now we're going to use another trick. We'll replace those tags with macros. Macro is literally telling the game to put a certain code in a certain place when loading the files. So in our code we're going to replace this:

<syntaxhighlight lang=wml>
[difficulty]
define = EASY
image = "units/human-loyalists/bowman.png"
label = _"Recruit"
description = _"Beginner"
[/difficulty]
</syntaxhighlight>

With this:

<syntaxhighlight lang=wml>
{CAMPAIGN_DIFFICULTY EASY "units/human-loyalists/bowman.png~RC(magenta>blue)" _"Recruit" _"Beginner"}
</syntaxhighlight>

And the game will swap it back for us. Note, that the order of values in macros (they are called '''arguments''' in this context), unlike keys, does matter and has to be strictly followed. You also have to watch out for spaces, as anything that's not within () parentheses or "" double quotes and contains a space will count as two separate arguments. If we used the Wesnoth core's syntax for translatables the third argument would have to look like that: ''( _ "Recruit")''

Macros are great for saving time on typing and space on the screen when developing. You can also make your own macros but we'll do that later. There's a big collection of macros already made in Wesnoth and most are documented in [https://www.wesnoth.org/macro-reference.html the reference], along with the one we just used.

We'll also replace the other two with macros to save space. Usually you'd use a macro from the beginning and never write the tag in full. Note that we treat macros like keys for the purpose of indentation.

<syntaxhighlight lang=wml>
{CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/longbowman.png~RC(magenta>blue)" _"Veteran" _"Intermediate"}
{CAMPAIGN_DIFFICULTY HARD "units/human-loyalists/masterbowman.png~RC(magenta>blue)" _"Commander" _"Hard"}
</syntaxhighlight>

== Credits ==
Those will appear when the player finishes the campaign, just before mainline credits. They look like that:

<syntaxhighlight lang=wml>
[about]
title = _"Designers"
[entry]
name = "John Doe (hisnickname)"
comment = "Served as excellent example on how an entry usually looks like"
[/entry]
[/about]
[about]
title = _"Programmers"
[entry]
name = "You"
comment = "Assuming you actually did something"
[/entry]
[entry]
name = "John Smith (jhnsmth)"
[/entry]
[/about]
</syntaxhighlight>

The '''[about]''' tag describes a section in credits, its '''title=''' key is usually translatable and describes what the people inside did (usually role name), '''[entry]''' describes a single person, its '''name=''' key shouldn't be translatable and does what says on the tin, '''comment=''' is optional, provides an extra insight in their achievements and shouldn't be bothered to be translated.

That's it. You don't even need those at all, but you probably will add them anyway, for fame and future generations, or something.

Alternatively you can use '''end_credits = no''' instead and this will cause the game to display no credits at the end of your campaign, obviously, including mainline credits.

Consult [[CreditsWML]] for more. Or just check any other campaign's credits. It's actually the least important thing for your campaign.

== TL;DR ==
[[#Troubleshooting|Skip]]
In this part we added a '''[textdomain]''' tag to ''_main.cfg'' file and '''#textdomain''' definition at the beginning.

<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial

[textdomain]
name = wesnoth-WML_Tutorial
path = data/add-ons/WML_Tutorial/translations
[/textdomain]
</syntaxhighlight>

In the ''[campaign]'' tag:
We added an '''icon''' to display next to the campaign's name, and '''abbrev''' for prefixing save filenames.

<syntaxhighlight lang=wml>
icon = "items/book3.png"
abbrev = _"WMLT"
</syntaxhighlight>

We also added the '''description''', along with its optional visuals - '''image''' and '''background'''.

<syntaxhighlight lang=wml>
description = _"Basic, but slowly expanding example for tutorial.
Great, emotional story not yet guaranteed.

" + _"(Novice? level, 1 scenario)"
image = "portraits/humans/longbowman.png"
background = "story/grim-altar.jpg"
</syntaxhighlight>

We also added '''rank''' and '''year''' for sorting purposes. Both are optional and almost unnoticeable for the average user. You can replace the latter with '''start_year''' and '''end_year'''.

<syntaxhighlight lang=wml>
rank = 970
year = "364 YW"
</syntaxhighlight>

We added three '''difficulties''' using '''macros''' in place of tags and keys:

<syntaxhighlight lang=wml>
{CAMPAIGN_DIFFICULTY EASY "units/human-loyalists/bowman.png~RC(magenta>blue)" _"Recruit" _"Beginner"}
{CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/longbowman.png~RC(magenta>blue)" _"Veteran" _"Intermediate"}
{CAMPAIGN_DIFFICULTY HARD "units/human-loyalists/masterbowman.png~RC(magenta>blue)" _"Commander" _"Hard"}
</syntaxhighlight>

Macros are good and [https://www.wesnoth.org/macro-reference.html here's] the list.

We also added '''credits''' but if you're reading the TL;DR you're not worthy to put those yet. Go back after actually making your own campaign.

== Troubleshooting ==
Campaign doesn't appear on the list anymore
:Probably macros are badly written or your tags are not opened/closed properly. Error message shown when running the game might say more.
Images don't show
:Assuming your [binary_path] is correct (this was done in the previous part), check your paths and. They should be relative to the game's 'images' folder, or have full path relative to userdata folder. Watch out for typos and extensions.
Code so far:
:_main.cfg
<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial

[textdomain]
name = wesnoth-WML_Tutorial
path = data/add-ons/WML_Tutorial/translations
[/textdomain]

[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
icon = "items/book3.png"
abbrev = _"WMLT"

description = _"Basic, but slowly expanding example for tutorial.
Great, emotional story not yet guaranteed.

" + _"(Novice? level, 1 scenario)"
image = "portraits/humans/longbowman.png"
background = "story/grim-altar.jpg"

rank = 970
year = "364 YW"

first_scenario = 01_Initial_Scenario
define = WML_TUTORIAL

{CAMPAIGN_DIFFICULTY EASY "units/human-loyalists/bowman.png~RC(magenta>blue)" _"Recruit" _"Beginner"}
{CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/longbowman.png~RC(magenta>blue)" _"Veteran" _"Intermediate"}
{CAMPAIGN_DIFFICULTY HARD "units/human-loyalists/masterbowman.png~RC(magenta>blue)" _"Commander" _"Hard"}

[about]
title = _"Designers"
[entry]
name = "John Doe (hisnickname)"
comment = "Served as excellent example on how an entry usually looks like"
[/entry]
[/about]
[about]
title = _"Programmers"
[entry]
name = "You"
comment = "Assuming you actually did something"
[/entry]
[entry]
name = "John Smith (jhnsmth)"
[/entry]
[/about]
[/campaign]

#ifdef WML_TUTORIAL
[binary_path]
path = data/add-ons/WML_Tutorial
[/binary_path]
{~add-ons/WML_Tutorial/scenarios}
#endif
</syntaxhighlight>

:scenarios/01_Initial_Scenario.cfg

<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
type = Longbowman
recruit = Bowman, Spearman
[/side]
[side]
side = 2
controller = ai
#ifdef EASY
type = Dark Sorcerer
#else
type = Necromancer
#endif
recruit = Skeleton Archer, Skeleton
[/side]
[/scenario]
</syntaxhighlight>

----

[[MakingCampaignInWML3|Part 3: Improving the first scenario]]

MakingCampaignInWML2

2021-11-25T15:09:19Z

Jarom: Created page with "'''Expanding the campaign definition (and macros)''' In the previous part of this tutorial we made a minimal working example that could be run and pla..."

'''Expanding the campaign definition (and macros)'''

In the [[MakingCampaignInWML|previous part]] of this tutorial we made a minimal working example that could be run and played, but it's far from the usual content of a campaign. If you have ADHD or for some other reason don't want to read all the descriptions, jump to the [[#TL;DR|TL;DR]].

== Textdomain ==
Let's start by introducing the very common content of add-on's _main.cfg file, that is the textdomain. It allows your campaign to be translated and it's better to do that at the very start than try to add it later, especially since it's mostly unobtrusive and doesn't take much time. First, let's add a [[GettextForWesnothDevelopers#The_textdomain_tag|'''[textdomain]''']] tag, it's typically located before [[CampaignWML|'''[campaign]''']] and looks like:

<syntaxhighlight lang=wml>
[textdomain]
name = wesnoth-WML_Tutorial
path = data/add-ons/WML_Tutorial/translations
[/textdomain]
</syntaxhighlight>

The '''name=''' key is most important. Your textdomain name should start with ''wesnoth-'', and after that it typically uses your add-on's folder name for a good reason - this name will be used as folder name again.

The '''path=''' key contains the path to your translation root relative to the userdata folder, typically it's the same as in ''[binary_path]'' but with ''/translations'' at the end.
:You don't have to add /translations at the end but you should. Although having your main folder as translation root will flatten your folder structure for translation, which can possibly make access to it faster, it'll be confusing for others, so it's discouraged.

The reference advises to create translations folder now, but it doesn't need to have content for now and actually everything will work even if you don't.

Note that mainline campaigns have different content in this tag because their translations are handled by game core, so don't copy their way.

Now, we're going to add a '''#textdomain''' directive. It's typically the first line of any ''.cfg'' file containing translatable strings. For our example it'll be:

<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial
</syntaxhighlight>

'''#texdomain''' is a fixed part, and after a space there should be your textdomain name, exactly the same as in ''name='' key in ''[textdomain]'' tag. You should place the exact same line in your scenario file, but not in your map file. If you have a .cfg file that you're sure that it won't have any translatable strings, you can use '''#wmllint: no translatables''' instead, but if you're not sure, just add the full ''#textdomain'' directive or leave nothing. Don't put any of these in files other than those with .cfg extension.

== Visuals ==

Your campaign entry in the campaigns menu looks very barebones for now. Let's add a little variety.
First, an icon. It will show on campaigns list and is considered pretty mandatory. It's customary to use an image that's usually displayed on the map, like an item or a unit. In this example we're going to use a book from mainline as an icon:

<syntaxhighlight lang=wml>
icon = "items/book3.png"
</syntaxhighlight>

Place this inside your ''[campaign]'' tag. If you're planning to use custom images, see the [[#Note about custom images|note about paths]] below. Note that it's customary to wrap file paths and certain other strings in double quotes, but usually they are not necessary. Don't add the _ (underscore) before though, because this is NOT translatable.

Other images also go inside ''[campaign]'' tag but are much more optional, even mainline campaigns not always use them:

<syntaxhighlight lang=wml>
image = "portraits/humans/longbowman.png"
</syntaxhighlight>

This will show below the description (we'll add one soon) and it's usually a unit/character portrait. It's optional, but quite common. We're using the portrait of Wesnoth's longbowman as an example.

<syntaxhighlight lang=wml>
background = "story/grim-altar.jpg"
</syntaxhighlight>

This is a new feature, introduced in 1.15 versions, so it's not commonly used. It replaces the default background of the campaign menu when our campaign is selected. Typically uses story/cutscene background images. Note that Wesnoth backgrounds in the story folder have atypical .jpg extension, but it's not necessarily the case for other background images.

:=== Note about custom images ===
:Usually you could access an image, e.g. "snow-golem.png" in your add-on's images folder by just writing "snow-golem.png". But that's because you use [binary_path] to access it. However, our [binary_path] is inside #ifdef, which only loads AFTER we start the campaign, so the game doesn't know about it when we're in campaign selection menu.
:To use custom images in your [campaign] tag you have to use fully qualified names, relative to userdata folder, that is, the same as you used in [binary_path] and [textdomain]. For the afforementioned snow golem image you'd have to write ''data/add-ons/WML_Tutorial/images/snow-golem.png''.
:There's a trick that can simplify it, but you'll learn it later.

Now, let's move to the '''description'''. In mainline campaigns it's usually splitted into two parts, the actual description and difficulty/length addition, for translation purposes. Don't forget to mark each part as translatable whether you split or not.

<syntaxhighlight lang=wml>
description = _"Basic, but slowly expanding example for tutorial.
Great, emotional story not yet guaranteed.

" + _"(Novice? level, 1 scenario.)"
</syntaxhighlight>

Note that you mustn't tabulate the description inside quotes in multiline description, as it'll be added to the string and shown in the game. You can use fancy formatting, as described [[InterfaceActionsWML#Formatting|here]].
:Centering the description
:There exists a key description_alignment= if you want to center your description like the one in The Sceptre of Fire. It doesn't add the italics though.
:<syntaxhighlight lang=wml>
description_alignment = center
</syntaxhighlight>
:It won't appear in code examples later.

There's one more purely visual thing, but it only shows in save filenames - the '''abbrev'''. It's recommended to set that. First derive an abbreviation of your campaign from its name. For example, The Rise of Wesnoth is abbreviated TRoW and Under the Burning Suns is UtBS. For this example add-on, we'll use WMLT. Note that abbreviations vary between languages, so this is translatable.

<syntaxhighlight lang=wml>
abbrev = _"WMLT"
</syntaxhighlight>

:You should, but don't have to avoid clashes in the abbrev= key.
:It's preferable, but not necessary that it doesn't clash with other add-ons. However, as it only affects save filenames, it's unlikely to cause problems for the game itself - it could at most overwrite saves if for some reason scenario names are the same. It might affect the community though.
:Example: the abbreviation conflict between Era of Magic and Era of Myths, causing the former to use the abbreviation EoMa. But you don't have to bother about it at this point that much.

== Sorting ==
There's a default order of campaigns appearing in the menu and ours will probably be last for now. Set your campaign's rank to something bigger than 300, the lower it is, the bigger priority on default sorting it's going to have, if not set it will appear somewhere near the end. Check in [[CampaignWML]] for a detailed explanation.

<syntaxhighlight lang=wml>
rank = 970
</syntaxhighlight>

Note that you can also sort by name (alphabetically) and by time. For the former, set ''start_year='' and ''end_year='' keys, for example:

<syntaxhighlight lang=wml>
start_year = "10 BW"
end_year = "10 YW"
</syntaxhighlight>

In this campaign we're going to use a simpler form that replaces both of them to set our campaign to happen a year after "The Story of Two Brothers":

<syntaxhighlight lang=wml>
year = "364 YW"
</syntaxhighlight>

As it was said, it only affects sorting by timeline and nothing else, so if your campaign for some reason isn't placed in the Wesnoth universe or the date is not determined, just omit this key.

== Difficulty ==

Difficulty in campaigns is currently added using '''[difficulty]''' tags. It was different before, so not all add-ons follow this convention. The tag looks as follows:

<syntaxhighlight lang=wml>
[difficulty]
define = EASY
image = "units/human-loyalists/bowman.png"
label = _"Recruit"
description = _"Beginner"
[/difficulty]
</syntaxhighlight>

It should be placed inside the ''[campaign]'' tag, like ''[side]'' in ''[scenario]''. Don't forget about correct indentation.

First key, '''define=''' works similarly to the one in ''[campaign]'' tag, and is also checked with ''#ifdef''. But instead of only loading resources when campaign starts, it will only put certain parts of code in the campaign when it's started with the right difficulty, so it doesn't have effect on the ''[campaign]'' tag itself and will be used in scenarios (or units) instead. Example:

<syntaxhighlight lang=wml>
#ifdef EASY
type = Dark Sorcerer
#else
type = Necromancer
#endif
</syntaxhighlight>

This code if put inside the enemy's ''[side]'' tag will cause their leader to be a Dark Sorcerer if the difficulty is set to ''EASY'', and a Necromancer otherwise. Note that it'll show in examples later.

It's strongly recommended to use a set of: ''EASY, NORMAL, HARD'' if you have three difficulties and add ''NIGHTMARE'' if you have four, because there are some improvements (namely macros) that make use of those.

Second key, '''image=''' should point to an image illustrating the difficulty. It usually follows level progression for a unit or several similar units of different levels. For example, Liberty uses a Peasant (lvl 0) for ''EASY'', Outlaw (lvl 2) for ''NORMAL'' and Fugitive (lvl 3) for ''HARD''. It's purely visual.

Third key, '''label=''' is a translatable string with a flavour text representing the difficulty. It's often the name of the unit on image, but not necessarily.

Fourth key, '''description=''' is also translatable, and it serves as the actual user-visible difficulty name for the ones confused by flavour texts. Note, that you might want to choose from the ones used in mainline and save time on translating and devising a clever descriptive name. Just start the game and look at what was used so far.

Having a single difficulty doesn't really change anything so we'll add two more:

<syntaxhighlight lang=wml>
[difficulty]
define = NORMAL
image = "units/human-loyalists/longbowman.png"
label = _"Veteran"
description = _"Intermediate"
[/difficulty]
[difficulty]
define = HARD
image = "units/human-loyalists/masterbowman.png"
label = _"Commander"
description = _"Hard"
[/difficulty]
</syntaxhighlight>

We'll now use a little trick and append '''~RC(magenta>blue)''' to the images, so their paths will look like:

<syntaxhighlight lang=wml>
image = "units/human-loyalists/longbowman.png~RC(magenta>blue)"
</syntaxhighlight>

It'll cause their images to be coloured like units of default side 2. Again, it's purely visual. See [[ImagePathFunctions#RC: Re-Color function|documentation]] for more.

Note that players can change difficulty mid-campaign by default. To prevent that, you can add '''allow_difficulty_change = no''' to your ''[campaign]'' tag.

== MACROS ==

Now we're going to use another trick. We'll replace those tags with macros. Macro is literally telling the game to put a certain code in a certain place when loading the files. So in our code we're going to replace this:

<syntaxhighlight lang=wml>
[difficulty]
define = EASY
image = "units/human-loyalists/bowman.png"
label = _"Recruit"
description = _"Beginner"
[/difficulty]
</syntaxhighlight>

With this:

<syntaxhighlight lang=wml>
{CAMPAIGN_DIFFICULTY EASY "units/human-loyalists/bowman.png~RC(magenta>blue)" _"Recruit" _"Beginner"}
</syntaxhighlight>

And the game will swap it back for us. Note, that the order of values in macros (they are called '''arguments''' in this context), unlike keys, does matter and has to be strictly followed. You also have to watch out for spaces, as anything that's not within () parentheses or "" double quotes and contains a space will count as two separate arguments. If we used the Wesnoth core's syntax for translatables the third argument would have to look like that: ''( _ "Recruit")''

Macros are great for saving time on typing and space on the screen when developing. You can also make your own macros but we'll do that later. There's a big collection of macros already made in Wesnoth and most are documented in [https://www.wesnoth.org/macro-reference.html the reference], along with the one we just used.

We'll also replace the other two with macros to save space. Usually you'd use a macro from the beginning and never write the tag in full. Note that we treat macros like keys for the purpose of indentation.

<syntaxhighlight lang=wml>
{CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/longbowman.png~RC(magenta>blue)" _"Veteran" _"Intermediate"}
{CAMPAIGN_DIFFICULTY HARD "units/human-loyalists/masterbowman.png~RC(magenta>blue)" _"Commander" _"Hard"}
</syntaxhighlight>

== Credits ==
Those will appear when the player finishes the campaign, just before mainline credits. They look like that:

<syntaxhighlight lang=wml>
[about]
title = _"Designers"
[entry]
name = "John Doe (hisnickname)"
comment = "Served as excellent example on how an entry usually looks like"
[/entry]
[/about]
[about]
title = _"Programmers"
[entry]
name = "You"
comment = "Assuming you actually did something"
[/entry]
[entry]
name = "John Smith (jhnsmth)"
[/entry]
[/about]
</syntaxhighlight>

The '''[about]''' tag describes a section in credits, its '''title=''' key is usually translatable and describes what the people inside did (usually role name), '''[entry]''' describes a single person, its '''name=''' key shouldn't be translatable and does what says on the tin, '''comment=''' is optional, provides an extra insight in their achievements and shouldn't be bothered to be translated.

That's it. You don't even need those at all, but you probably will add them anyway, for fame and future generations, or something.

Alternatively you can use '''end_credits = no''' instead and this will cause the game to display no credits at the end of your campaign, obviously, including mainline credits.

Consult [[CreditsWML]] for more. Or just check any other campaign's credits. It's actually the least important thing for your campaign.

== TL;DR ==
[[#Troubleshooting|Skip]]
In this part we added a '''[textdomain]''' tag to ''_main.cfg'' file and '''#textdomain''' definition at the beginning.

<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial

[textdomain]
name = wesnoth-WML_Tutorial
path = data/add-ons/WML_Tutorial/translations
[/textdomain]
</syntaxhighlight>

In the ''[campaign]'' tag:
We added an '''icon''' to display next to the campaign's name, and '''abbrev''' for prefixing save filenames.

<syntaxhighlight lang=wml>
icon = "items/book3.png"
abbrev = _"WMLT"
</syntaxhighlight>

We also added the '''description''', along with its optional visuals - '''image''' and '''background'''.

<syntaxhighlight lang=wml>
description = _"Basic, but slowly expanding example for tutorial.
Great, emotional story not yet guaranteed.

" + _"(Novice? level, 1 scenario)"
image = "portraits/humans/longbowman.png"
background = "story/grim-altar.jpg"
</syntaxhighlight>

We also added '''rank''' and '''year''' for sorting purposes. Both are optional and almost unnoticeable for the average user. You can replace the latter with '''start_year''' and '''end_year'''.

<syntaxhighlight lang=wml>
rank = 970
year = "364 YW"
</syntaxhighlight>

We added three '''difficulties''' using '''macros''' in place of tags and keys:

<syntaxhighlight lang=wml>
{CAMPAIGN_DIFFICULTY EASY "units/human-loyalists/bowman.png~RC(magenta>blue)" _"Recruit" _"Beginner"}
{CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/longbowman.png~RC(magenta>blue)" _"Veteran" _"Intermediate"}
{CAMPAIGN_DIFFICULTY HARD "units/human-loyalists/masterbowman.png~RC(magenta>blue)" _"Commander" _"Hard"}
</syntaxhighlight>

Macros are good and [https://www.wesnoth.org/macro-reference.html here's] the list.

We also added '''credits''' but if you're reading the TL;DR you're not worthy to put those yet. Go back after actually making your own campaign.

== Troubleshooting ==
Campaign doesn't appear on the list anymore
:Probably macros are badly written or your tags are not opened/closed properly. Error message shown when running the game might say more.
Images don't show
:Assuming your [binary_path] is correct (this was done in the previous part), check your paths and. They should be relative to the game's 'images' folder, or have full path relative to userdata folder. Watch out for typos and extensions.
Code so far:
:_main.cfg
<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial

[textdomain]
name = wesnoth-WML_Tutorial
path = data/add-ons/WML_Tutorial/translations
[/textdomain]

[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
icon = "items/book3.png"
abbrev = _"WMLT"

description = _"Basic, but slowly expanding example for tutorial.
Great, emotional story not yet guaranteed.

" + _"(Novice? level, 1 scenario)"
image = "portraits/humans/longbowman.png"
background = "story/grim-altar.jpg"

rank = 970
year = "364 YW"

first_scenario = 01_Initial_Scenario
define = WML_TUTORIAL

{CAMPAIGN_DIFFICULTY EASY "units/human-loyalists/bowman.png~RC(magenta>blue)" _"Recruit" _"Beginner"}
{CAMPAIGN_DIFFICULTY NORMAL "units/human-loyalists/longbowman.png~RC(magenta>blue)" _"Veteran" _"Intermediate"}
{CAMPAIGN_DIFFICULTY HARD "units/human-loyalists/masterbowman.png~RC(magenta>blue)" _"Commander" _"Hard"}

[about]
title = _"Designers"
[entry]
name = "John Doe (hisnickname)"
comment = "Served as excellent example on how an entry usually looks like"
[/entry]
[/about]
[about]
title = _"Programmers"
[entry]
name = "You"
comment = "Assuming you actually did something"
[/entry]
[entry]
name = "John Smith (jhnsmth)"
[/entry]
[/about]
[/campaign]

#ifdef WML_TUTORIAL
[binary_path]
path = data/add-ons/WML_Tutorial
[/binary_path]
{~add-ons/WML_Tutorial/scenarios}
#endif
</syntaxhighlight>

:scenarios/01_Initial_Scenario.cfg

<syntaxhighlight lang=wml>
#textdomain wesnoth-WML_Tutorial
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
type = Longbowman
recruit = Bowman, Spearman
[/side]
[side]
side = 2
controller = ai
#ifdef EASY
type = Dark Sorcerer
#else
type = Necromancer
#endif
recruit = Skeleton Archer, Skeleton
[/side]
[/scenario]
</syntaxhighlight>

[[MakingCampaignInWML3|Part 3: Improving the first scenario]]

MakingCampaignInWML

2021-11-21T23:53:25Z

Jarom: Created page with "'''Step-by-step tutorial - making a campaign using WML.''' '''Part 1: Making a basic campaign''' Parts 2-4 are actually written already and waiting for me to format them pro..."

'''Step-by-step tutorial - making a campaign using WML.'''

'''Part 1: Making a basic campaign'''

Parts 2-4 are actually written already and waiting for me to format them properly. Please be patient in the meanwhile.
----
This tutorial's goal is to provide a step-by-step explanation on how to build a campaign using WML. It's not as comprehensive as other existing tutorials, because it's designed to minimize information in order to lower the entry barrier, so after doing it you won't gain all the necessary information, but you will be able to make a basic campaign. It's recommended to download WML Guide, The Final Exam or a simple add-on like Story of the Wose (from 1.14 add-ons server) or An Orcish Incursion (from 1.16 add-ons server).

== Getting started ==

First, locate your add-ons folder. Following screenshot is for 1.16.0 version:

--SCREENSHOT--

Then, create a folder for your add-on. It's customary that it starts with a capital letter and advisable that it has no spaces – use _ (underscores) or [https://en.wikipedia.org/wiki/Camel_case PascalCase] instead. In this tutorial we'll create a folder named WML_Tutorial. Pick a folder name that refers to your add-ons's name, it's often the same as in id below. Replace spaces with underscores.

'''Important note: after making any changes in your add-on, save all modified files first, then reload Wesnoth either by closing and running it again or by clicking f5 in the main menu.'''

== The main file ==
Now inside create a file _main.cfg (the filename has to be exactly like that), then open it with your preferred code editor. Windows notepad is theoretically sufficient, but the author strongly recommends [https://code.visualstudio.com/ Visual Studio Code] with [https://marketplace.visualstudio.com/items?itemName=Bitron.wml WML add-in], alternatively [https://notepad-plus-plus.org/downloads/ Notepad++], preferably with imported [https://forums.wesnoth.org/viewtopic.php?t=44392 WML language definition]. If using VS Code, it's advisable to open the whole add-on folder and use it as a workspace.

Then, we create the basic structure. Refer to the code below:

<syntaxhighlight lang=wml>
[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
[/campaign]
</syntaxhighlight>

It's just four lines that tell the campaign that there exists a campaign named WML Tutorial. You can now run the game and see the following entry in campaigns menu:

--SCREENSHOT--

However, it will show an error "Failed to load the scenario" if we try to start. Let's analyse the code step by step.

[[CampaignWML|'''[campaign]''']] tag is an opening tag. In the last line there's also a closing tag, '''[/campaign]'''. All tags must have both opening tag and closing tag, and the closing tag is always the same as opening tag but with / (slash) before the name. In this case the tag name is campaign and it means that everything inside describes a single campaign.
----
Important syntax information – omit at your own risk unless you read [[SyntaxWML]] or the [[WML_for_Complete_Beginners:_Chapter_1|other tutorial]].
* (Almost) all valid tags (tag names) are listed in alphabetical order in the right panel on all WML Reference pages, but keep in mind that most of them are only valid within a certain context. There are also "tag amendments" with [+name] (e.g. [+campaign]) syntax, but we'll talk about them later.
* Everything between opening tag (e.g. [campaign]) and matching closing tag (e.g. [/campaign]) is this tag's content. It consists of subtags (aka children) with the same syntax (check tag's reference for possible subtags), and keys, in this example second and third lines are keys. Order of tags usually matters.
* Keys follow the ''name=value'' syntax, which is somewhat flexible – ''name = value'' as in the example above works as well. Wesnoth core uses ''name=value'' to save disc space but this tutorial will use ''name = value'' for clarity. Contrary to tags, order of keys is not important, unless there are duplicate keys, but those should be avoided. Therefore feel free to sort them however you want. However in some cases there are implicit conventions, usually established by extensive use in mainline - this tutorial often breaks them on purpose. One that is recommended to be followed is to put id-like and type-like keys first, if there are any, and group name with id.
* It's strongly recommended that each opening tag causes the following lines of code to have one more tab stop (or four spaces) at the beginning – it's called indentation. Wesnoth core typically uses tabs – this example we will use spaces because they are easier to use with webpages.
* Note for XML/SGML programmers – there are no void tags, self-closing tags, or keys within the opening tag – keys are only within content, so WML does not conform to both conventions. Not to mention the use of [] square brackets in place of <> angled brackets.
----
'''id = WML_Tutorial''' - this key tells the game that the campaign we describe has an identifier "WML_tutorial. Pick an id that doesn't conflict with any other campaign, preferably including all add-ons, and forget about it forever.
:You can enclose WML_tutorial (or your own id) in double quotes, it won't change anything. IDs are recommended to have no spaces but it's not mandatory. Typically campaign's id is its name but with underscores in place of spaces.
'''name = _"WML Tutorial"''' - tells the game to show a text (string) WML Tutorial to the user every time it needs this campaign's name. Note the _ (underscore) – it means that this text is translatable. Every text that's visible to the user should always be translatable.
:Wesnoth core's usual syntax for translatable keys is ''name= _ "visible"'' but we'll do things our own way as always, and this time for a good reason that will be explained in the second part. Unlike ids, names don't have to be unique, but it's advisable in this case.

So we did tell the game that there exists a campaign named WML Tutorial, but it has currently no content. Wesnoth should always know that our campaign exists, but should only load its content when necessary. Therefore, we'll use [[PreprocessorRef|WML Preprocessor]] to load the content when the campaign is started. All you need to know for now is that we add '''define=''' key to the ''[campaign]'' tag, and then after the tag we'll put the '''#ifdef''' directive along with closing '''#endif''' directive.

<syntaxhighlight lang=wml>
[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
define = WML_TUTORIAL
[/campaign]
#ifdef WML_TUTORIAL
#endif
</syntaxhighlight>

The text after ''#ifdef'' (WML_TUTORIAL in this case) must match the value of ''define='' key. It's recommended to use [https://en.wikipedia.org/wiki/Snake_case SCREAMING_SNAKE_CASE] for it. It's customary that it matches the campaign's id somehow. Now everything between ''#ifdef'' and matching ''#endif'' will be loaded when the campaign starts. Though there's nothing there for now – let's make it load scenarios.
:It's possible to delegate your campaign's content loading to a different file, especially if you're planning to have dependencies based on it – which rarely happens actually. If you need an example you can check the add-on Era of Magic's ''campaign.cfg'' file.

First, make a folder scenarios within your add-on folder (WML_Tutorial). You can use a different name but you shouldn't. Then add a magic line '''{~add-ons/WML_Tutorial/scenarios}''' between ''#ifdef'' and ''#endif'' in your ''_main.cfg'' file. If you used a different folder name for your add-on, change the line accordingly.

Now when your campaign is loaded, all files with .cfg extension inside scenarios folder (we'll add one soon) will be loaded, as well as all ''_main.cfg'' files in its subfolders (this feature is almost never used so forget it, there are better ways if you need nested folder structure).

== Basic scenario ==
Before we move to create the first scenario, we're going to need a map. Create a folder named maps – unlike scenarios, the folder's name is important. Now make a simple map with two starting positions marked and save it in your newly created maps folder. Refer to [[BuildingMaps|this tutorial on making maps]]. You can also copy one from other campaigns for training purposes, e.g. ''01_At_the_East_Gate.map'' from The Hammer of Thursagan – [https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/The_Hammer_of_Thursagan/maps/01_At_the_East_Gate.map link to Wesnoth's github].
:You might need to navigate a bit, assuming you're in the editor's maps folder, go two steps higher to reach the userdata folder, then go to data/add-ons/WML_Tutorial. You can add your add-on's maps folder to the quick access panel on the left for future ease of use.

Having created the map, let's create a scenario. For demonstration purposes, we'll name it Initial Scenario. First let's create a .cfg file in the scenarios folder. In our case it'll be ''01_Initial_Scenario.cfg''. Numbering isn't necessary, but it helps keep track of order, so it's recommended. Now consider the following code that you should copy to your scenario file:

<syntaxhighlight lang=wml>
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
[/side]
[/scenario]
</syntaxhighlight>

[[ScenarioWML|'''[scenario]''']] tag tells the game that everything inside describes a single scenario.

''id='' and ''name='' are pretty much the same as in ''[campaign]'', except this time id is important for you because you'll be using it in other places.
:You need to note that your scenario's id mustn't clash with other scenarios loaded at the same time, that is, other scenarios in your campaign. It's advised to match scenario's id with its name and filename. Prefixing scenario ids with numbers helps in debugging and keeping track of order, and it's customary not to use spaces.

''map_file='' key refers to the filename of map file within maps folder. You could also use ''map_data='' like in other tutorials and many add-ons, but it's somewhat obsolete, more difficult and error-prone.
:It's advisable that your map file has exactly the same filename as your scenario file, except that it's in a different folder and has .map instead of .cfg extension.

[[SideWML|'''[side]''']] tag describes a single side. In this example it has a ''side='' key, which describes the turn order (usually side 1 is player's but not necessarily). It also has a mandatory ''controller='' key. It's ''"human"'' value tells the game that the player is the one playing this side.

== Adjustments to main file ==
Now add a ''first_scenario = 01_Initial_Scenario'' key to your ''[campaign]'' tag in ''_main.cfg'' file. If you gave your scenario a different id, adjust the code accordingly.
Now you can try to actually run your campaign, but it's going to throw an error because it can't find the map. To make it work, add the following code to ''#ifdef'' in ''_main.cfg'':

<syntaxhighlight lang=wml>
[binary_path]
path = data/add-ons/WML_Tutorial
[/binary_path]
</syntaxhighlight>

This [[BinaryPathWML|'''[binary_path]''']] will tell the game to look for resources (images/maps/sounds/music files) in their respective folders. Like always, if your add-on uses a different folder name, adjust the code accordingly.

Now you can actually run your campaign. It should load, but you'll instantly lose.

== Troubleshooting ==
In case your scenario doesn't load, troubleshoot it before proceeding to next steps. Otherwise, you can skip it.

If the game doesn't show your campaign on the list at all:
:Either you made a mistake in the naming ''_main.cfg'' file, or your add-on's directory is in the wrong place – start again from the beginning. There's also a possibility that you used wrong syntax in your ''[campaign]'' tag, in this case copy the code from here again and check for conflicting ids.
If your scenario doesn't load:
:Check if your include directive ''{~add-ons/WML_Tutorial/scenarios}'' points to the valid scenarios folder and your scenario file is there (filename doesn't matter as long as it has the correct .cfg extension). Check if your ''#ifdef'' and ''define='' are matching. Check if your ''[scenario]'' tag has correct syntax (unlikely to be the problem).
If your scenario throws an error about the map:
:Check if your map file is in the correct folder (maps). Check if your ''[binary_path]'''s ''path='' key points correctly to your add-on's folder (WML_Tutorial in this case). Check if ''map_file='' key in ''[scenario]'' matches the filename of your map (including extension).
Code up to this point:
:Your ''_main.cfg'' file should look more or less like that:

<syntaxhighlight lang=wml>
[campaign]
id = WML_Tutorial
name = _"WML Tutorial"
first_scenario = 01_Initial_Scenario
define = WML_TUTORIAL
[/campaign]

#ifdef WML_TUTORIAL
[binary_path]
path = data/add-ons/WML_Tutorial
[/binary_path]
{~add-ons/WML_Tutorial/scenarios}
#endif
</syntaxhighlight>

:While your ''01_Initial_Scenario.cfg'' (or however it's named) in scenarios folder should look like that:

<syntaxhighlight lang=wml>
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
[/side]
[/scenario]
</syntaxhighlight>

:And there should be a correct map file in the maps folder, named ''01_Initial_Scenario.map'' (or whatever is written in ''map_file='' key).

== Adding playability ==
Now, as it was said before, if you run the scenario you'll instantly lose. Solution is trivial: add a ''type='' key to your '''[side]''' tag with valid unit id as value. Here we'll use ''type = Longbowman''. This key tells the game that your leader is a unit of type Longbowman, so it can create this unit on the starting point defined in the map editor.

Now if you run the game, you'll instantly win. Reason – there's no enemy. If it's intended, you can add a ''victory_when_enemies_defeated = no'' key to your '''[scenario]''' tag, but it's an advanced feature – we're going to add an enemy instead. Consider the following code:

<syntaxhighlight lang=wml>
[side]
side = 2
controller = ai
type = Dark Sorcerer
[/side]
</syntaxhighlight>

Insert it in your ''[scenario]'' tag. It adds a second (''side=2'') side, controlled by ai, whose leader is a Dark Sorcerer. It's pretty similar to the previous ''[side]'' tag, so the further explanation will be omitted.
Now you can run your scenario and it'll actually work, except that you can only move your leader – there's nothing to recruit.

Add a ''recruit='' key to both ''[side]'' tags. In this example, it'll be ''recruit = Bowman, Spearman'' for ''side = 1'' and ''recruit = Skeleton Archer, Skeleton'' for ''side = 2''. This tells the game which units the side can recruit, of course, and the value should be a comma-separated list of valid unit ids.

Run the game. You should have a simple one-scenario campaign in which your human army of bowmans and spearmans fight a disgusting horde of skeletons led by a dark sorcerer. All values like gold, income etc are their respective default values. This concludes a [https://en.wikipedia.org/wiki/Minimal_working_example Minimal Working Example].

== Troubleshooting part 2: ==
If your or enemy leader don't appear
:Check if their unit ids in ''type='' are valid. Check if starting positions for side 1 and 2 are properly defined in the map file. There exists a way for placing leaders without a defined starting position but it's an advanced feature.
If you can't recruit, or enemy doesn't recruit
:The respective ''recruit='' key has invalid syntax or contains an invalid unit id. Try the example first.
scenario code at this point:

<syntaxhighlight lang=wml>
[scenario]
id = 01_Initial_Scenario
name = _"Initial Scenario"
map_file = "01_Initial_Scenario.map"
[side]
side = 1
controller = human
type = Longbowman
recruit = Bowman, Spearman
[/side]
[side]
side = 2
controller = ai
type = Dark Sorcerer
recruit = Skeleton Archer, Skeleton
[/side]
[/scenario]
</syntaxhighlight>

[[MakingCampaignInWML2|Part 2: Expanding the campaign definition]] - not yet uploaded

EraWML

2021-11-14T19:43:52Z

Jarom: /* The [era] top level tag */

{{WML Tags}}
== 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.
* <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'.
* '''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''': {{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.
* '''hide_help''': {{DevFeature1.13|0}} 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 [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR 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.
* '''[modify_unit_type]''': {{DevFeature1.15|2}} Applies minor modifications to existing unit types when this era is active. See entry in [[ModificationWML]] for list of possible attributes.

== See Also ==

* [[ReferenceWML]]
* [[SideWML]]

[[Category: WML Reference]]

CampaignWML

2021-11-14T19:42:51Z

Jarom:

{{WML Tags}}



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)
* '''background''': {{DevFeature1.15|9}} the image used as a backdrop for the Campaigns menu (typically a high resolution image intended for displaying fullscreen in story screens). If blank or unspecified, a stock story background from core is used.
* '''description''': (translatable) text shown in the information pane when this campaign is selected in the campaign selection menu
* '''description_alignment''': {{DevFeature1.13|3}} 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:
<ul>
;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 {{DevFeature1.13|0}}
:allows the advancement ''Orcish Slayer'' -> ''Orcish Nightblade''
;ENABLE_PARAGON {{DevFeature1.15|1}}
:allows the advancement ''Dune Blademaster'' -> ''Dune Paragon''
;ENABLE_WOSE_SHAMAN {{DevFeature1.15|1}}
:allows the advancement ''Wose'' -> ''Wose Shaman''
</ul>
* '''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 [https://www.wesnoth.org/macro-reference.html#file:utils.cfg| 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. {{DevFeature1.13|2}} 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. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=
* '''[difficulty]''': {{DevFeature1.13|2}} 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''': {{DevFeature1.15|0}} 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]''': {{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.) {{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.
* '''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 [[CreditsWML]] 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. {{DevFeature1.15|6}} This value is capped at 5000 (5 seconds).
* '''[event]''': {{DevFeature1.13|2}} events placed here will be automatically inserted into all scenarios of the campaign.
* '''[modify_unit_type]''': {{DevFeature1.15|2}} Applies minor modifications to existing unit types when this campaign is active. See entry in [[ModificationWML]] for list of possible attributes.

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 allow era selection (when set to ''yes'') or hide it and use a default one when creating a game (when set to ''no''). 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'.

== See Also ==

* [[PreprocessorRef]]
* [[ScenarioWML]]
* [[ReferenceWML]]
* [[PblWML]]

[[Category: WML Reference]]