The Battle for Wesnoth Wiki - User contributions [en]

InternalActionsWML

2019-01-14T08:12:00Z

Zookeeper: /* [random_placement] */ Documented the .n and .terrain container attributes

{{WML Tags}}

Part of [[ActionWML]], Internal actions are actions that WML uses internally that do not directly affect game play (or, at least, are not readily apparent to the player). For example, storing a variable is an internal action.

== Variable Actions ==

These actions are focused, in one way or another, on [[VariablesWML|variables]]. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.

=== [set_variable] ===

The '''[set_variable]''' tag is used to create and manipulate WML variables. The [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE VARIABLE] macro is a quick syntactic shortcut for simple variable creation and the [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE_OP VARIABLE_OP] macro is a quick syntactic shortcut for performing simple mathematical operations on variables.

* '''name''': the name of the variable to manipulate

* '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])

* '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollar signs.

* '''to_variable''': set the variable to the value of the given variable, e.g. 'to_variable=temp' would be equivalent to 'value=$temp'.

* '''add''': add the given amount to the variable.

* '''sub''': subtract the given amount from the variable.

* '''multiply''': multiply the variable by the given number. The result is a float.<br />To negate a number, multiply by -1. If you negate 0, the result is a floating-point negative zero -0. To display -0 as 0, use a second tag with add=0; it will flip -0 to 0 but not affect other numbers.

* '''divide''': divide the variable by the given number. The result is a float. Wesnoth 1.9 and later no longer uses integer division. Use a second tag with round=floor if you relied on this.

* '''modulo''': returns the remainder of a division.

* '''abs''': Returns the absolute value of the variable.

* '''root''': Use '''root=square''' to calculate the square root. {{DevFeature1.15|0}} Also supports '''root=cube''' and arbitrary integer roots.

* '''power''': Raise the variable to some power.

* '''rand''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'rand=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'rand=3..5'.<br>You may combine these, e.g. 'rand=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. If a number or item is repeated, it is sampled more frequently as appropriate. See [[MultiplayerContent]] for more info on the MP case.<br>Using rand= will automatically result in the current action being non undoable. Ignoring possible [allow_undo].

* '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.

* '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).

* '''[join]''' joins an array of strings to create a textual list
** '''variable''': name of the array
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored
** '''separator''': separator to connect the elements
** '''remove_empty''': whether to ignore empty elements

* '''ipart''': Assigns the integer part (the part to the left of the decimal point) of the referenced variable.

* '''fpart''': Assigns the decimal part (the part to the right of the decimal point) of the referenced variable.

* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
**'''round=ceil''': Rounds upward to the nearest integer.
**'''round=floor''': Rounds down to the nearest integer.
**'''round=trunc''': {{DevFeature1.15|0}} Rounds towards zero; this is the same operation as '''ipart''', but operating on the value already contained in the variable rather than the value assigned to the key.

* '''formula''': Calculate the new value of the variable from a WFL formula operating on the old value. This is similar to using the '''$(...)''' syntax but avoids the possibility of WFL syntax errors if a referenced variable is empty.

=== [set_variables] ===

Manipulates a WML array or container

* '''name''': the name of the array or container to manipulate

* '''mode''': one of the following values:
** ''replace'': will clean the array '''name''' and replace it with given data
** ''append'': will append given data to the current array
** ''merge'': will merge in the given data into '''name'''. Attributes in '''[value]''' will overwrite any existing already in '''name'''. Tags in '''[value]''' modify the corresponding tag of the original value of '''name''', so for example the first '''[attack]''' tag in '''[value]''' would modify the first '''[attack]''' tag of '''name''' rather than appending a new '''[attack]''' tag. A few special syntaxes are supported:
*** ''__remove=yes'': When used in a subtag, causes the corresponding subtag in '''name''' to be deleted rather than merged. Deletion happens after any other subtags have been merged.
*** ''add_to_xxx'': Adds its integer value to the integer value of ''xxx'' in '''name'', and sets ''xxx'' in '''name''' to the result. {{DevFeature1.13|8}} Now adds as real numbers rather than integers.
*** ''concat_to_xxx'': {{DevFeature1.13|8}} Similar to ''add_to_xxx'', but does string concatenation instead of numerical addition.
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index greater than (or equal to) the array's current length. This limitation may be removed in future versions.

* '''to_variable''': data will be set to the given array

* '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags. ([[#Using_.5Bset_variables.5D_to_Create_Arrays_of_WML|See Example]])

* '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags

*'''[split]''' splits a textual list into an array which will then be set to data
** '''list''': textual list to split
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored
** '''separator''': separator to separate the elements
** '''remove_empty''': whether to ignore empty elements

{{DevFeature1.13|4}} You can now mix '''[value]''', '''[literal]''', and '''[split]''' in the same '''[set_variables]''' tag. They will be processed in order of appearance. Multiple instances of [split] are also supported now.

=== Capturing Game Data ===

These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.

==== [store_gold] ====

Stores a side's gold into a variable.

* '''[[StandardSideFilter]]''': The first matching side's gold will be stored in the variable "variable".
* '''variable''': (default='gold') the name of the variable to store the gold in

==== [store_locations] ====

Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only). The array will include any unreachable border hexes, if applicable.

* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. By default, all locations on the map are stored.

* '''variable''': the name of the variable (array) into which to store the locations.

* '''mode''': {{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and locations which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to ''append'', the variable will not be cleared, and locations which match the filter will be added to the array after the existing elements.

==== [store_reachable_locations] ====

Stores locations reachable by the given units. Can store either the movement, attack or vision ranges.

* '''[filter]''': a [[StandardUnitFilter]]. The locations reachable by any of the matching units will be stored.
* '''[filter_location]''': (optional) a [[StandardLocationFilter]]. Only locations which also match this filter will be stored.
* '''range''': possible values ''movement'' (default), ''attack'', ''vision''. If ''movement'', stores the locations within the movement range of the unit, taking Zone of Control into account. If ''attack'', stores the attack range (movement range + 1 hex). If ''vision'', stores the vision range (movement range ignoring Zone of Control + 1 hex).
* '''moves''': possible values ''current'' (default), ''max''. Specifies whether to use the current or maximum movement points when calculating the range.
* '''viewing_side''': (optional) the side whose vision to use when calculating the reach. This only has meaning in the presence of fog, shroud, or units with the ambush ability. If left out, then fog, shroud and ambushers are ignored and the real reach of the units is stored.
* '''variable''': the name of the variable (array) into which to store the locations.

==== [store_map_dimensions] ====

Stores the map dimensions in a variable.

* '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.

==== [store_side] ====

Stores information about a certain side in a variable.

'''Keys:'''
* '''[[StandardSideFilter]]''': All matching sides are stored. (An array is created if several sides match - access it with side[2].team_name and so on.)
* '''variable''': the name of the variable to store the information in (default: "side")
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are sides matching the filter. If mode is set to ''append'', the variable will not be cleared, and sides which match the filter will be added to the array after the existing elements.
'''Result'''

Variable will contain following members:
* '''color''': It indicates team color. Can be one of the following:
{| border = 1
| ''color''
| red
| blue
| green
| purple
| black
| brown
| orange
| white
| teal
|-
| ''value''
| 1
| 2
| 3
| 4
| 5
| 6
| 7
| 8
| 9
|}
* '''controller''': Indicates type of player that control this side. ''Note: In networked multiplayer, the controller attribute may not be the same on all clients. Be very careful or you have OOS errors.''
** '''human''': Human player
** '''ai''': If players assigns "Computer Player" to "Player/Type" in game lobby
** '''null''': If players assigns "Empty" to "Player/Type" in game lobby
* '''fog''': Indicates whether this side is affected by fog of war.
* '''gold''': The amount of gold the side has.
* '''hidden''': (boolean) If 'yes', side is not shown in status table.
* '''income''': Income for this side (base income + all village income. AKA gross income. Note that this is different from the [side] income key).
* '''name''': Name of player.
* '''recruit''': A comma-separated list of unit types that can be recruited by this side.
* '''shroud''': Whether this side is affected by shroud.
* '''side''': The $side_number of the side belonging to this container
* '''team_name''': String representing the team's description.
* '''user_team_name''': Translated string representing the team's description.
* '''village_gold''': The amount of gold given to this side per village it controls per turn.
* '''scroll_to_leader''': (boolean) Whether the game view scrolls to the side leader at the start of their turn.
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag animation.
* '''flag_icon''': Flag icon for the status bar for this side (see [[SideWML|[side]]]). Unless previously specified in [side] or changed with WML (see [[DirectActionsWML#.5Bmodify_side.5D|[modify_side]]]), this value may be empty for the default flag icon.
* '''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|7}} When the side will be considered defeated. See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]
* '''faction''': {{DevFeature1.13|7}} id of the selected faction, string (multiplayer-only)
* '''faction_name''': {{DevFeature1.13|7}} Name of the selected faction, string (multiplayer-only)
* '''num_units''' {{DevFeature1.13|7}}: The number of units the side currently has on the map.
* '''num_villages''' {{DevFeature1.13|7}}: The number of villages the side currently controls.
* '''total_upkeep''' {{DevFeature1.13|7}}: The number of unit levels the side is currently supporting.
* '''expenses''' {{DevFeature1.13|7}}: The amount of gold the side is currently spending to support units.
* '''net_income''' {{DevFeature1.13|7}}: The income the side gains per turn after expenses.
* '''base_income''' {{DevFeature1.13|8}}: The income the side gains per turn (same as [side] income key)

* {{DevFeature1.13|7}} All other keys and tags of the side that are contained in [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]] .__cfg

==== [store_starting_location] ====

Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' and 'owner_side' (villages only)

* [[StandardSideFilter]]: The starting locations of all matching sides will be stored. If multiple sides are matched, a WML array will be created.
* '''variable''': (default='location'): the name of the variable to store the location in
* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and the starting locations of the sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to ''append'', the variable will not be cleared, and the starting locations of the matching sides will be added to the array after the existing elements.

==== [store_time_of_day] ====

Stores time of day information from the current scenario into a WML variable container.

* '''x, y''': Location to store the time for. [[DirectActionsWML#.5Btime_area.5D|Time areas]] matter; illumination does not. If this is omitted, the global (location-independent) time is stored.

* '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].

* '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.

==== [store_turns] ====

Stores the turn limit (the maximum number of turns). If there is no limit, this stores ''-1''.

* '''variable''': (default='turns') the name of the variable in which to store the turn limit.

==== [store_unit] ====

Stores details about units into a [[VariablesWML#Container|container]] variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]. A sample '''list of these tags and keys''' can be found at [[InternalActionsWMLUnitTags]].

If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the '''[unit]''' tag(s) in any save file). One can also use the [[CommandMode|:inspect]] command or the [[InterfaceActionsWML#.5Binspect.5D|[inspect]]] tag to open a game-state inspector dialog, which can be used to view unit properties.

Common usage is to manipulate a unit by using '''[store_unit]''' to store it into a variable, followed by manipulation of the variable, and then [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] to re-create the unit with the modified variables.

''Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] and [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH].''

* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables. The units will be stored in order of their internal ''underlying_id'' attribute, which is usually in creation order (but you normally should not depend on the order).

* '''variable''': the name of the variable into which to store the unit(s)

* '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will not be cleared, and units which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are units matching the filter. If mode is set to ''append'', the variable will not be cleared, and units which match the filter will be added to the array after the existing elements.

* '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.

==== [store_unit_defense] ====

{{DevFeature1.13|9}}

Stores in a variable the defense of a unit on a particular terrain. If terrain or location is not specified, the terrain on which the unit currently stands is used. (Note: it is a WML defense, so the higher it is, the weaker unit's defense is.)

* StandardUnitFilter
* '''loc_x''', '''loc_y''': x and y of a valid map location. The terrain on this location will be used for the defense calculation.
* '''terrain''': The terrain code for which unit defense should be calculated. If '''terrain''' is specified, '''loc_x''' and '''loc_y''' are ignored.
* '''variable''': the name of the variable into which to store the defense. default: "terrain_defense"

==== [store_unit_type] ====

Stores a unit type definition into a variable.

* '''type''': (required) the defined ID of the unit type, for example "Goblin Knight". Do not use a translation mark or it will not work correctly for different languages. A comma-separated list of IDs may also be used to store an array of unit types.

* '''variable''': the name of the variable into which to store the unit type information (default "unit_type")

* '''mode''':{{DevFeature1.13|0}} defaults to ''always_clear'', which clears the variable. If mode is set to ''replace'', the variable will not be cleared, and the unit type will overwrite the existing element at the start of the array, leaving any additional elements intact if the original array contained more elements. If mode is set to ''append'', the variable will not be cleared, and the unit type will be added to the array after the existing elements.

==== [store_unit_type_ids] ====

* '''variable''': the name of the variable into which to store a comma-separated list of all unit type IDs including all from all loaded addons

==== [store_villages] ====

Stores a series of locations of villages that pass certain criteria into an array. Each member of the result array will have members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.

Note: This differs from using [store_locations] only in that the hexes considered for match are restricted to those with villages (those whose terrain type has its 'gives_income' flag set to true), in the same way that use of either the 'owner_side' key or the '[filter_owner]' will. In fact, if either of these are present, [store_villages] and [store_locations] will behave identically.

* '''variable''': the name of the variable (array) into which to store the locations (default: "location")
* '''[[StandardLocationFilter]]''' tags and keys as arguments

==== [store_items] ====

Stores current items in the scenario into an array. Each entry has at least members x and y and can have all of the other keys listed in the documentation of [[InterfaceActionsWML#.5Bitem.5D|[item]]] (depending on what was set during creating the item).

*'''variable''': name of the wml variable array to use (default "items")
*'''[[StandardLocationFilter]]''' keys as arguments: only items on locations matching this [[StandardLocationFilter]] will be stored

==== [store_relative_direction] ====

{{DevFeature1.13|0}}

Gets the relative direction from one hex to another. This is an interface to the function wesnoth uses to decide how a unit will face while it is moving / attacking / defending.

* '''[source]''' x and y must describe a map location
* '''[destination]''' similar
* '''variable''' name of the variable to store string result in (one of 'n', 'nw', 'ne', 's', 'sw', 'se')
* '''mode''' optional. 0 is the default setting corresponding to default wesnoth implementation used in animations. 1 is an alternate "radially symmetric" mode. The default mode breaks ties in the direction of south, since this makes more units face the player directly on screen. The radially symmetric mode breaks ties in the direction of counter-clockwise, and might be more appropriate in some cases.

==== [find_path] ====

A WML interface to the pathfinder. Calculates the path between a unit and a location and returns the result in a WML variable, that contains also an array for every step of the path.

*'''[traveler]''': [[StandardUnitFilter]], only the first matching unit will be used for calculation
*'''[destination]''': [[StandardLocationFilter]], only the first matching nearest hex will be used
*'''variable''': the variable name where the result will be stored, if no value is supplied 'path' will be used as default name. Each step will be stored in a [step] array inside that variable.
*'''allow_multiple_turns''': default no, if yes also moves that require more than one turn will be calculated.
*'''check_visibility''': default no, if yes the path will not be computed if some hexes are not visible due to shroud.
*'''check_teleport''': default yes; if no, teleport won't be taken in account while computing path.
*'''check_zoc''': default yes; if no, unit ZOCs won't be considered while calculating the path.
This is the structure of the variable returned by [find_path]:
[path]
hexes = the total length of the path
if the path is calculated to an impassable hex, or the move requires multiple turns
and allow_multiple_turns is no, its value will be 0.
from_x, from_y = location of the unit
to_x, to_y = destination
movement_cost = total movement cost required by unit to reach that hex
required_turns = total turns required by unit to reach that hex
[step]
x, y = location of the step
terrain = terrain of the step
movement_cost = movement cost required by unit to reach that hex
required_turns = turns required by unit to reach that hex
[/step]
[/path]

==== [unit_worth] ====
Takes only an inline [[StandardUnitFilter]] (only the first matching unit will be used for calculation) and outputs the following variables:
*''cost'', the current unit cost;
*''next_cost'', the cost of the most expensive advancement;
*''health'', the health of the unit in percentage;
*''experience'', current experience in percentage;
*''unit_worth'', how much the unit is worth.

Mainly used for internal AI checks, but one could in theory just do anything with it.

[event]
name=moveto
[unit_worth]
x,y=$x1,$y1
[/unit_worth]
[message]
id=$unit.id
message=_"I cost $cost gold, with $health|% of my hitpoints and $experience|% on the way to cost $next_cost|.
I am estimated to be worth $unit_worth"
[/message]
[clear_variable]
name=cost,next_cost,health,experience,unit_worth
[/clear_variable]
[/event]

=== [clear_variable] ===

This will delete the given variable. This tag can delete a scalar or an entire array; it can also delete one container at an array index. The macro [http://www.wesnoth.org/macro-reference.xhtml#CLEAR_VARIABLE CLEAR_VARIABLE] is a shortcut for this tag.

This action is good to use to clean up the set of variables; for example, a well-behaved scenario will delete any variables that should not be kept for the next scenario before the end of the scenario. One can also clear tags and variables of stored units; for example, one can remove [trait]s and [object]s.

* '''name''': the name of the variable to clear. This can also be a comma-separated list of multiple variable names.
** If a name ends with an array index, then it deletes that one container, and shifts the indexes of all subsequent containers. For example, <code>{CLEAR_VARIABLE my_awesome_array[2]}</code> deletes <code>my_awesome_array[2]</code>, but then moves <code>my_awesome_array[3]</code> to <code>my_awesome_array[2]</code>, moves <code>my_awesome_array[4]</code> to <code>my_awesome_array[3]</code>, and so on until the end of the array.
** Note that <code>{CLEAR_VARIABLE my_awesome_array}</code> deletes the entire array, but <code>{CLEAR_VARIABLE my_awesome_array[0]}</code> deletes only the first container.

=== [sync_variable] ===

{{DevFeature1.13|0}}

Sets one or multiple variables to the same value as on all clients and also on replays, it uses the value from the currently active side.
* '''name''' the name of the variable to synchonize this can be a comma seperated list.

== Other Internal Actions ==

Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.

=== [fire_event] ===

Trigger a WML event (used often for [[EventWML#Custom_events|custom events]])

* '''name''': the name of event to trigger
** ''(Optional)'' {{DevFeature1.13|6}}

* '''id''': ''(Optional)'' the id of a single event to trigger {{DevFeature1.13|6}}

* '''[primary_unit]''': ''(Optional)'' Primary unit for the event. Will never match on a recall list unit. The first unit matching the filter will be chosen.
**[[StandardUnitFilter]] as argument. Do not use a [filter] tag.

* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary unit.
**[[StandardUnitFilter]] as argument. Do not use a [filter] tag.

* '''[primary_attack]''': Information passed to the primary attack filter and $weapon variable on the new event.

* '''[secondary_attack]''': Information passed to the second attack filter and $second_weapon variable on the new event.

=== [remove_event] ===
{{DevFeature1.13|0}}

Removes the event with the specified id. Equivalent to <i>[event] id=foo remove=yes</i>. See [[EventWML#remove|EventWML]].

* '''id''': the id of the event to remove. May be a comma separated list.

=== [insert_tag] ===

Inserts a variable as WML. In other words, the value of the passed [[VariablesWML#Container|container variable]] will be injected into the game as if they had been written out in WML form. ([[#.5Binsert_tag.5D_Example|See Example]]).

Tag insertion is a special case in that it can be used in places where other ActionWML cannot be used. The basic rule is that anywhere that $variable syntax works, tag insertion will also work. In practice this means pretty much everywhere except directly within top-level scenario tags.

*'''name''': The ["name"] to be given to the tag. This must be a tag which would be valid at the place where [insert_tag] is used, for anything to happen. (For example, if used as ActionWML, it should be a [[ActionWML]] tag name, and it may be a recognized subtag such as "option" when used within a [message]).

*'''variable''': Name of the container variable which will have its value inserted into the tag.

=== [role] ===

Tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] (without [filter]) with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.

* '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.

* '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.

* '''search_recall_list''': {{DevFeature1.13|5}} whether to consider units on the recall list when assigning the role. Can be either yes or no, defaults to yes. {{DevFeature1.13|6}} If set to 'only', then units on the map are not considered when assigning the role - only units on the recall list can receive it.

* '''[else]''' {{DevFeature1.13|5}} ActionWML to execute if the game is unable to find a unit to assign the role to. For example, this could be used to create a new unit satisfying the role.

* '''[auto_recall]''' {{DevFeature1.13|6}} If present, and the role is assigned to a unit on the recall list, then that unit is recalled. Supports all unique keys of [[DirectActionsWML#.5Brecall.5D|[recall]]], but no [[StandardUnitFilter]].

* [[StandardUnitFilter]], do not use a [filter] sub-tag. SUF's role= and type= keys are not used: if you want to use them, use a nested SUF wrapped inside a [and] tag.

=== [random_placement] ===
{{DevFeature1.13|2}}

Selects randomly a given number of locations from a given set of locations and exectutes the given code for each of those locations.

* '''[filter_location]''': a [[StandardLocationFilter]].
* '''[command]''': contains ActionWml that is executed for each of the locations.
* '''num_items''': the number of locations that should be selected, this can be a (lua) expression to calculate the number of locations based on the number of locations that match the filter, for example (size * 0.5) will execute the command for exactly half of the locations (rounded down)
* '''variable''': The name of the variable that contains the current location during the execution of [command]. This is a container with the attributes x, y, n and terrain.
* '''min_distance''': The minimum distance of 2 chosen locations, a value less than 0 means that the same locations can be chosen more than one time.
* '''allow_less''': If yes, the tag will not show an error in case there were less than num_items locations available.

=== Flow control actions ===

{{DevFeature1.13|2}}

There are three actions that alter the flow of execution. They are '''[break]''', '''[continue]''', and '''[return]'''. All of them take no arguments.

* '''[break]''': The nearest enclosing loop immediately stops executing, and control continues with the next action after the end of that loop. If there is no enclosing loop, this is equivalent to '''[return]'''.
* '''[continue]''': The nearest enclosing loop immediately stops executing, and control continues at the beginning of that loop, with any iteration variables updated for the next iteration. If there is no enclosing loop, this is an error.
* '''[return]''': Control immediately returns to the Wesnoth engine. This completely exits the current event, including any nested events, such that the [message] will not be displayed in the below example. No further WML actions are executed in this context. Any separate, subsequent events will be run as usual.
<syntaxhighlight lang=wml>
[event]
name=moveto
[fire_event]
name=return_please
[/fire_event]
[message]
message="Made it back"
[/message]
[/event]
[event]
name=return_please
[return][/return]
[/event]
</syntaxhighlight>

=== [unsynced] ===

{{DevFeature1.13|?}}

Runs the contained actionwml in a unsynced context, that means actions performed inside [unsynced] are not synced over the network. for example
<syntaxhighlight lang=wml>
[event]
name=moveto
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will print the same message to all clients, but also disallow undoing (regardless of [allow_undo]) for that moveto becasue it requests a synced random seed form the server. However this code
<syntaxhighlight lang=wml>
[event]
name=moveto
[unsynced]
{VARIABLE_OP message rand "Hi,Hello,How are you?"}
[message]
message = $message
[/message]
{CLEAR_VARIABLE message}
[unsynced]
[allow_undo]
[/allow_undo]
[/event]
</syntaxhighlight>
will not prevent undoing, but might print a different message for each client in a multiplayer game (or during a sp replay), so `[unsynced]` should not be used for actions that actually change the gamestate otherwise you'll get OOS

== Examples ==

=== Using [set_variables] to Create Arrays of WML ===

<syntaxhighlight lang=wml>
[set_variables]
name=arr
mode=replace
[value]
foo=bar
[/value]
[value]
foo=more
[/value]
[/set_variables]
{DEBUG_MSG $arr[0].foo}
{DEBUG_MSG $arr[1].foo}
</syntaxhighlight>

This will produce two output messages, first one saying '''bar''' and next one saying '''more'''.

=== [insert_tag] Example ===

<syntaxhighlight lang=wml>
[event]
name=moveto

[set_variable]
name=temp.speaker
value=Konrad
[/set_variable]

[set_variable]
name=temp.message
value= _ "Yo Kalenz!"
[/set_variable]

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]
</syntaxhighlight>

This is effectively identical to:

<syntaxhighlight lang=wml>
[event]
name=moveto

[message]
speaker=Konrad
message= _ "Yo Kalenz!"
[/message]
[/event]
</syntaxhighlight>

== See Also ==
* [[VariablesWML]]
* [[ActionWML]]
** [[ConditionalWML]]
** [[DirectActionsWML]]
** [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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

DirectActionsWML

2018-05-21T21:59:19Z

Zookeeper: Documented default of [kill] animate= and fire_event=

{{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}}

=== [recall] ===
Recalls a unit taking into account any [http://wiki.wesnoth.org/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.
* '''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.
* '''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.

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 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.

=== [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. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
* '''variable''': the name of the variable.
* '''find_vacant''': 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''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".
* '''text''': (translatable) 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 to display the text in. 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.)
* '''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''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.
* '''animate''': (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.
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.
* '''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 add to the types the leader can recruit because of [side]recruit=.
* '''extra_recruit''': the types of units that the unit 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.
* '''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.
* '''extra_recruit''': the types of units that the side 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.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is having its recruitment set. 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.

=== [set_extra_recruit] ===
Sets the units a leader can 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.
* '''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 [http://wiki.wesnoth.org/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]]]).

=== [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 take any arguments.

=== [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]''', '''[secondary_attack]''' {{DevFeature1.13|8}} The attacks to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by.

=== [move_unit] ===
works like the MOVE_UNIT macro.
* [[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.
* '''fire_event''' (optional, 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.
* '''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.

=== [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.
** '''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.
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit.
* 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).

=== [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.
* [[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.
* '''id''': (Optional) allows the item to be removed later. 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.
* '''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.
* '''[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 level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
**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' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* '''[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 is tried 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)
* '''[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 matching the filter have matching objects removed
* '''object_id''': The id of the object to be removed.

=== [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_view=yes).

=== [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, recruitment, 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.

Due to a bug in 1.12 (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]
message = "option 1"
[command]
[/command]
[/option]
[option]
message = "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, [[SyntaxWML#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 exceuted 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 reccomended way to wokr around these issues is to refer to the unit by is 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 {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_hex}} events in that version.

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

{{DevFeature1.13|11}}
In an {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_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] on (3,3) would let the player choose whether to 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.
* '''[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. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.
* '''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. Before 1.9 this is always "no".

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[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.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''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. 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)
[time_area]
x=1-2,4-5
y=1-2,1-2
{UNDERGROUND}
[/time_area]

=== [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''': Content of a wesnoth map file. example:
map="{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.
* '''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.

=== [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).
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
* '''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.

(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.

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 always be replay safe.

=== [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.

== 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 [http://www.wesnoth.org/macro-reference.xhtml 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]]

Geography of Wesnoth

2018-05-20T10:17:46Z

Zookeeper: Removed "The Southern Land" section

{{Translations}}
== Irdya ==

The name of the world in which the kingdom of Wesnoth is situated is "Irdya". This term is , however, only rarely used in the era depicted by the main map. People normally just say "the world" or, poetically, "the wide green world".

== Wesnoth and Surrounding Lands ==

[https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/core/images/maps/titlescreen.png Map of Wesnoth and Surrounding Lands]

This map is current for approximately YW 450. Named cities were founded during the Golden Age of Wesnoth and have thus have existed for at least 200 years.

Place names in '''bold''' are marked on the main map.

* Major features:
** '''The Great Ocean''': Lies to the west of the continent and all rivers eventually flow to it.
** The '''Bay of Pearls''': The Elensefar Peninsula in the North and the '''Isle of Alduin''' in the southwest separate this from the Great Ocean. This is where human refugees from the Green Isle first landed in 1YW.
** '''Isle of Alduin''': Inhabited island off the west coast of the Great Continent. Home of the Great Academy of Magic and a traditional center of magecraft.
** '''The Three Sisters''': Group of three islands north-northwest of Alduin. The nearest is individually known as the Isle of the Damned and has an evil reputation.
** '''The Great River''': Runs east to west on the main map, unmarked.
** '''Ford of Abez''': Easternmost point at which the Great River can be crossed without ships. A traditional invasion route for armies crossing in either direction.
** '''River Weldyn''': Tributary running north from the '''Dulatus Hills''' to the '''Great River'''.
** River Aethen: River running from the '''Dulatus Hills''' to the '''Great Ocean''' through the '''Aethenwood'''.
** '''The Heart Mountains''': the major mountain range surrounding '''Lake Vrug'''.

=== Wesnoth ===
The Kingdom of Wesnoth is located in the north-central portion of the Great Continent. Most of the mainline campaigns revolve around it. It is bounded on the map by the '''Great River''' to the north, the shore of the '''Great Ocean''' to the west, the Aethenwood to the southwest, and the '''Bitter Swamp''' to the southeast (lower right corner of the main map).

Over the '''River Aethen''', south of '''Fort Tahn''', is a Wesnothian frontier region. It is bounded to the south (off-map) by dense woods of which the '''Aethenwood''' may be considered a northernmost extension.

* Notable cities:
** '''Weldyn''': The capital of Wesnoth.
** '''Aldril''': City lying on the Bay of Pearls.
** '''Blackwater Port''': City lying south of the Bay of Pearls.
** '''Carcyn''': Located between the Grey Woods and the Great River.
** '''Dan'Tonk''': Wesnoth's largest city, located in the center of the country, just west and north of Weldyn.
** '''Soradoc''': The northernmost border outpost of Wesnoth, controls the confluence of the Weldyn River and the Great River.
** '''Fort Tahn''': The southernmost border outpost, controls the north/south road crossing the River Aethen.
** '''Tath''': Important fort city north of Dan'Tonk, exerts control over the wilderness country around the east of the Brown Hills and north to the '''Ford of Abez'''.

* Notable land features:
** '''Gryphon Mountain''': Home of the fabled Gryphons
** '''Ford of Abez''': Shallow part of the Great River, it is usually controlled by Wesnothian forces
** '''Weldyn River''': It branches from the Great River and goes south
** Great Central Plain: Area bounded by Weldyn, Dan'Tonk, and Fort Tahn, this plain is Wesnoth's bread basket and home to most of its population
** '''Dulatus Hills''': These rolling hills bordering the Great Central Plain provide much of Wesnoth's livestock and agriculture
** Brown Hills: Wasteland surrounding Gryphon Mountain that is not well-populated and occasionally very dangerous.
** Horse Plains: Region of rolling plains just south of the '''Great River''', bounded by '''Glyn's Forest''' to the west and the '''River Weldyn''' to the east; the southern reach merges into the Central Plain. Home of the powerful Clans; the best horses in Wesnoth are bred here.
** '''Estmark Hills''': Largish range rising south of the Great River and east of the Weldyn River. The northernmost portion, nearest the '''River Weldyn''', has at various times been settled by Wesnothians, but the Kingdom's control is tenuous at best and banditry is common.
** '''Glyn's Forest''': Sometimes known as the Royal Forest, named for one of Haldric II's sons
** '''Grey Woods''': Large forest in the heart of the wilds of Wesnoth, located between Carcyn and Aldril and generally considered to be haunted
** Green Swamp: Large swamp in the heart of the wilds of Wesnoth, south of Aldril. (Not shown on the main map.)

=== Southwest Elven Lands ===
The Wood Elves are separate from those of the north, and have only intermittent relations with them and most other countries. Its borders are the Green Swamp to the northeast, the desert (not shown) to the south, and the Ocean to the west.
* Notable cities
** None known
* Notable land features:
** '''Aethen Forest''': The largest southern forest, it extends far to the southwest - much farther than is charted - and is home to elves

=== Elensefar ===
'''Elensefar''' is at times a province of Wesnoth, at times an independent country, and at times in a treaty federation with Wesnoth. Its borders are the Great River to the north, a loosely defined line with Wesnoth to the east, the Bay of Pearls to the south, and the ocean to the west. More information is found in the [[Timeline of Wesnoth|historical narrative]] of Wesnoth.

* Notable cities:
** '''Elensefar''': The capital, located on an island in the Great River delta
** '''Carcyn''': City on the Wesnoth-Elensefar border, disputed with Wesnoth
* Notable land features:
** '''Great River''': It is very wide at this point, and only ships can cross it.

=== Northlands ===

There is no government of the Northlands. Various groups of orcs, dwarves, barbarian men and even elves populate the region. The northern and eastern borders are not defined, the southern border is the '''Great River''', and the western border is the '''Great Ocean'''.

* Notable cities:
** '''Glamdrol''': An Orcish tribal capital
** '''Romyr''': Another Orcish tribal capital
** '''Wesmere''': The location of the Ka'lian - the Elvish Council
** Dwarven Doors: A mixed human/dwarven town in the region of Knalga in the southern Heart Mountains. A major trade center.
** Dallben and Delwyn: Human villages originally built by settlers who crossed the Great River during Wesnoth's Golden Age expansion. Now abandoned. The forested area northeast of '''Elensefar''', where these villages were located, was named the Annuvin province by men but was known by the elves as Wesmere.

* Notable land features:
** '''Heart Mountains''': A virtually impassable barrier between the river country and the Northern Plains.
** Heartfangs: the particularly forbidding stretch of high peaks southwest of '''Lake Vrug''' and north of the '''Forest of Wesmere'''. The most inhospitable and dangerous portion of the '''Heart Mountains'''; only hermits, madmen, and mages live there.
** '''Swamp of Dread''': a very large bog located between the '''Heart Mountains''' and the '''Great River'''. A notoriously dangerous place.
** '''Lake Vrug''': A large mountain lake whose river carves the only pathway through the Northern Mountains
** '''Arkan-thoria''': The river than comes out of Lake Vrug. This is the elvish name; among humans it is called Longlier.
** '''River Listra''': The south-running tributary of the Great River into which the '''Arkan-thoria''' empties.
** '''Lintanir Forest''': The southernmost portion of the Great Northern Forest, a gigantic wood whose eastern and northern boundaries are known only the elves. Their capitol, Elensiria, has only seldom been visited by humans.
** '''Great River''': The origin of this river is somewhere in the east of the northern lands

==== Wesmere====
The location of the Ka'lian - the Elvish Council in the Eastern part of the forest. The river Telfar flows through the forest. The Kal'ian is on an island in the Telfar. The River Telfar is crossed by the Northern Shallows, the Ford of Alyas, the Ford of Tifranur and the North Bridge. Villages surrounding the Ka'lian are named Telionath, Arthen, Arryn, Illissa, Viricon, Tireas, Essarn, Valcathra, Aelion, Elendor, Erethean. Other areas near the Ka'lian are Brightleaf Wood, Telfar Green (an opening in the forest), Dancer’s Green (an opening in the forest), Karmarth Hills, Westwind Wood (possibly the foothills of the Heart Mountains to the north east of Wesmere), Southwind Wood. East and outside are the forest are the villages of Dallben and Delwyn.

== Far North ==

[https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Son_Of_The_Black_Eye/images/maps/sotbe.png Map of the Far North]

Cold, harsh, and inaccessible, the Far North is the ancestral home of the Orcish Clannate. It lies north of the Heart Mountains, which the Orcs call the Haggid-Dargor and claim (without merit) as their own. To the east lie the Unaligned Tribes of the Wild Steppe, who fell out of the control of the Clannate, instead roaming with wild human barbarians and clashing with the High Elves of the North Plains (known as North Elves in human lands). The High Elves themselves reside further east, where it is rumored they rule a vast kingdom.

* Notable cities:
** Barag Gor, a city home to the Orcish Council
** Bitok
** Borstep
** Castelfrang
** Farzi
** Festog
** Grisbi
** Lmarig
** Melmog
** Prestim
** Tirigaz
* Notable land features:
** Swamp of Desolation
** Mountains of Dorth
** Mountains of Haag
** Green Forest
** Silent Forest
** Forest of Thelien
** River Oumph
** River Bork
** Wild Steppe

===Area around Tirigaz===
Featured in [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_Water Dead Water].

[https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Dead_Water/images/maps/dw.png Map of area around Tirigaz]

* Notable cities:
** Tirigaz
** Jotha
**Agvorad
* Notable land features:
** Swamp of Desolation
** Mountains of Dorth
** Bilheld, a large island.
** A small island of coast of Bilheld

== The Green Isle ==
The geography features in [http://wiki.wesnoth.org/Mainline_Campaigns#The_Rise_of_Wesnoth The Rise of Wesnoth].

[https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/The_Rise_Of_Wesnoth/images/maps/green_isle.png Map of The Green Isle]

=== Wesfolk Land ===
This is where the Wesfolk live, with their Lich overlords. The boundary between it and the Islefolk land is the hilly area running south-west to north-east. The Wesfolk land is in the north-west. Little is known about what happened to the island after Haldric left.
* Notable cities:
** Jevyan's Haven: The capital of the Wesfolk, where Jevyan reigned; presumably where the gates to orcland were opened

=== Islefolk Land ===
This is where the Islefolk (Haldric's folk) live. The boundary is the same as that of the Wesfolk; the islefolk land is to the southeast.
* Notable cities:
** Blackmore: {??}
** Clearwater Port: {??}
** Southbay: {??}

== Campaign References ==

This section collates specific facts about geography asserted in the the text of mainline campaigns, implied by map dots (track) or by features on a battle map (map). It aims to be complete as to locations on the main map and identifiably adjacent to it. Two groups of off-map locations are confined to single campaigns, the Green Isle in ''The Rise of Wesnoth'' and the Far North in ''Son of the Black Eye''; those locations are not listed here.

=== Heir To The Throne ===

Konrad was raised in the '''Aethenwood''' (track, ''The Elves Besieged''). He returns to the mainland very near the location where Haldric the Great first landed in 1YW. (map, ''Bay of Pearls''). The fight with Muff Malal takes place on the peninsula north of the '''Bay of Pearls''' (track, ''Bay of Pearls''). The city of '''Elensefar''' is actually located on a large island in the mouth of the '''Great River''' (map, ''The Siege of Elensefar''). The crossroads fight takes place where the roads from '''Carcyn''', '''Dan'Tonk''' and '''Fort Tahn''' meet (track, ''Crossroads''). Konrad meets Li'sar on the road between '''Dan'Tonk''' and '''Carcyn''' (track, ''The Princess of Wesnoth''). Konrad fights undead in the Brown Hills southeast of '''Gryphon Mountain''' (track, ''Valley of Death''). The track for ''Gryphon Mountain'' unsurprisingly lands on the '''Gryphon Mountain''' map feature; equally unsurprisingly, the track for ''Ford of Abez'' lands on the '''Ford of Abez''' map feature.

North of the '''Great River''' this campaign is our basic textual evidence for several important features. The country around the easternmost tip of the '''Swamp of Dread''' is described as "abundant pine forests nestled in rolling foothills" (track and text, ''Northern Winter'') and, at least during the Turmoil of Asheviere, is inhabited by orcs. Dwarven Doors and Knalga are located in the center of the southern arm of the Heart Mountains, south-southeast of Lake Vrug (''The Dwarven Doors''). Lionel, the Lost General, is found in an orcish warren at the northern edge of the southern '''Heart Mountains''', north-northeast of Knalga and adjacent to the valley of the Arkan-thoria (''The Lost General''). Konrad re-encounters Li'sar north across that valley in the foothills of the northern '''Heart Mountains''' (track, ''Hasty Alliance''). The Scepter of Fire is found in those same foothills a bit further east and south, just north of the southernmost bend of the '''Arkan-thoria''' (''Scepter of Fire'').

Konrad's party travels southeast through the caverns, under the '''Arkan-thoria''', to just south of a northward bend of the river (''A Choice Must Be Made''). Kalenz says that this river is called 'Longlier' by men and 'Arkan-thoria' by the Elves. He further says that the homeland of his people lies to the east and north. Kalenz identifies their location at the easternmost edge of the southern '''Heart Mountains''' (track, ''Snow Plains'') as "...once the home of my people. We left here centuries ago" (text). In the next scenario, the North Elves are contacted at the confluence of the '''Arkan-thoria''' and the '''Listra''' (track, ''Home of the North Elves''). Konrad's party take refuge in Emetria, an Elven castle located just within the border of the southern lobe '''Lintanir Forest'''. ''The Elven Council'' takes place in the elven capital of Elensiria, location not specified.

Konrad crosses the '''Great River''' into Wesnoth just north of '''Soradoc''' (''Return to Wesnoth''). The country between the Elven forests and the river is inhabited by, among other things, "hermit mages" (text). He then crosses the river into the '''Estmark Hills''' hills east of the '''Weldyn River''' (track, ''Test of the Clans'').

Neither the '''Estmark Hills''', nor the '''Heart Mountains''', nor the swamp between them and the '''Great River''' are named in this campaign, but one scenario title refers to the latter as ''Swamp of Dread''.

Continuity problems: the map for 'The Princess of Wesnoth' is difficult to reconcile with the track location; the lake to the south should be large enough to show on the main map and is difficult to fit in a valley in the Brown Hills.
Likewise, the map for ''Home of the North Elves'' shows only an east-west river probably too small to be the '''Arkan-thoria''', and not the '''Listra''' that it should flow into.

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:HttT#Labels map labels]

=== A Tale of Two Brothers ===

This campaign has a tracking map. In text, the village of Maghre is described as being in the "western reaches of Wesnoth" (''Rooting Out a Mage''). In ''The Chase'', the haunted forest is identified as the Grey Woods.

=== An Orcish Incursion ===

This campaign has a map and a journey track. No places are named other than '''Wesmere'''; the action takes place north and west of there. A pass that is bottleneck route through the northern mountains figures in the action.

=== The South Guard ===

This campaign takes place off the main map and has its own background map.

We know from it that the city of Westin is located southwest of '''Fort Tahn''' (track, ''Born To The Banner'') and is capital of the frontier province of Kerlath (text), also that the Aethenwood is to the west (text).

There is no map track after the second scenario. We learn that south of Westin , Kerlath is bounded by dense woods, "a bastion of the ancient heart forest of the Great Continent so dense and gloomy that even elves forbore from dwelling there."
(''Born to the Banner'') South of it an unspecified distance lies the elven Vale of Tears, and much further south of that the Black River, of which Etheliel says "No elf, still living, has crossed it."

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:TSG#Labels map labels]

=== Liberty ===

This campaign uses a modified version of the main Wesnoth map for tracking. The map shows the villages of Dallben and Delwyn, and some small patches of forest, between the forest of Wesmere and the ocean; also it labels the '''Grey Woods'''. Text (''The Raid'') identifies this as the province of Annuvin, a frontier area of Wesnoth. It is clear that '''Elensefar''' is the chief city of Annuvin.

Baldras and his party travel south to '''Elensefar''' (track, ''A Strategy of Hope''). From there they go upriver to '''Carcyn''' (track, ''Hide And Seek''), and south to the '''Grey Woods''' (track, ''The Grey Woods''), then south on the road to ''Aldril''. The campaign finishes at '''Halstead'''. In the Epilogue, there is a reference to villagers fleeing southwest to settle on the '''Three Sisters'''.

The scenario maps feature [http://wiki.wesnoth.org/CampaignDialogue:L#Labels map labels]

=== The Rise of Wesnoth ===

This campaign has its own tracking map for the Green Isle, which is our only actual source of information about the Green Isle's geography. The only Great Continent location of interest is the Ka'lian, which has the same location in the '''Forest of Wesmere''' that it does in other campaigns.

The lady Jessene uses the term "Old Continent" to describe the ancestral home of her people, and implies that it lies in "the far West".

=== The Legend of Wesmere ===
This campaign uses a [http://wiki.wesnoth.org/Geography_of_Wesnoth#LOW_Custom_Map modified version of the main Wesnoth map] for tracking. The map shows far fewer settlements with the notable addition of a castle settlement in the '''Swamp of Dread''', called '''Saurgrath''' (the location of ''The Saurian Treasury'').

The map track for ''Hostile Mountains'' shows Kalenz starting from the '''Lintanir Forest''' and moving across the easternmost '''Heart Mountains''' to a spot on the Arkan-thoria. They travel to '''Wesmere Forest''' (''The Ka'lian Under Attack''); the map tracking runs almost lengthwise through the '''Heart Mountains'''. The Ka'lian is near the northeast edge of '''Wesmere forest'''; the Elvish treasury is further west (track, ''The Elvish Treasury''). The Saurian treasury in the westernmost foothills of the '''Heart Mountains''' (track, ''The Saurian Treasury''); Kalenz and his men avoid the direct route from it back to Wesmere by going north from it and that they return via the eastern approaches to Wesmere. On the way, they re-encounter Olurf in the southeastern reaches of the '''Heart Mountains''' (''Acquaintance In Need''). They march back to the north edge of '''Wesmere Forest''' (track, ''Elves' Last Stand'').

In ''Council of Hard Choices'' we learn that the mage Crelanu lives in "the mountains of Thoria". The route north goes over the mountains to the "Arkan-thoria" (track: ''Bounty Hunters''), the name is confirmed in text. The mountains of Thoria themselves are just north of the valley of the '''Arkan-thoria''' (track, ''Cliffs of Thoria''). Crelanu's keep is well into the northern '''Heart Mountains''', right at the northern edge of the map (track, ''Battle of the Book'').

Kalenz and friends "return to the Ka'lian" (''News From The Front''); then to orcish forces are "encamped south of the '''Great River''', and have surrounded the fortified human settlement of Tath". The track for ''Breaking the Siege'' indicates that the killing of the Great Chief took place at the southeastern tip of the '''Heart Mountains''' and that ''Breaking the Siege'' takes place on the '''River Listra''', just north of the confluence with the '''Arkan-thoria'''.

The remaining scenarios convey no new information; the track points are all east of the '''River Listra''' between it and the '''Lintanir Forest'''.

Kalenz's home map has big water to the east. This has to be a lake off the NE corner of the main map, emptying into the main course of the Listra.

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:LOW#Labels map labels]
====LOW Custom Map====
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Legend_of_Wesmere/images/low-map.png https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Legend_of_Wesmere/images/low-map.png]

=== Eastern Invasion ===

This campaign has its own map, with the River Guard outposts shown, and a tracking map. The intro describes the location of the River Guard posts on "the near bank of the Weldyn", alludes to trouble in the Estmarks, and refers to "raiders from the great desert", location unspecified.

One path from ''An Unexpected Appearance'' leads west, the other east (text). But the western path forces Gweddry and his men to travel north, into "known forest country just south of the Great River" (text). On the other branch, Mal-Ravanal's capitol is in the '''Bitter Swamp''' (''Mal-Ravanal's Capitol''); the party flees "west and north" until they find a "low pass in the Estmarks, and [are] greatly relieved to see the valley of the Weldyn open before them." (text). In ''Undead Crossing'', Gweddry's party crosses the '''Great River''' to the north (text). One of the following scenarios is named '''Lake Vrug'''. In ''Drowned Plains'' the party goes south to the '''Great River''', crosses it, and Owaec announces that they have entered the Horse Plains. '''Weldyn''' is on the map of the final scenario.

The Orc kings stronghold map has [http://wiki.wesnoth.org/CampaignDialogue:EI#King_Dra-Nak.27s_City_.28labels.29 map labels]

=== The Hammer of Thursagan ===

This campaign has a tracking map. It begins at Knalga, and the heroes travel generally eastwards. There are no other specific geographical references in it, except to "the High Pass" about halfway between Knalga and Kal Kartha.

=== Descent Into Darkness ===

This campaign has a journey track, and a map on which the the "northern border town of Parthyn" (''Saving Parthyn'') appears. An eartly fight (''Orc War'') takes place near the river Longlier (the '''Arkan-thoria'''). This is denoted by a [http://wiki.wesnoth.org/CampaignDialogue:DID#Places_.28labels.29 map label]. Later in the campaign (''Return To Parthyn'') it is specified that Malin follows a trail south across the '''Great River''' and west to Parthyn. Part of the action (''A Small Favor'' and three sequels) takes place in the city of '''Tath'''.

=== Scepter of Fire ===

This campaign has a tracking map.
The campaign begins in "the foothills of Knalga" (text, ''A Bargain Is Struck'') when Haldric II rides north from there from the '''Ford of Abez'''. Rugnur looks for Thursagan in "the northern wastelands", which is near the coast north-northeast of Rumyr (''Searching for the Runecrafter''). Much of the rest of the campaign takes place in the old eastern mines just north of the Arkan-thoria; this is where the Scepter will be found in ''Heir To The Throne''. Alanin's running battle with the outriders takes place just north of the '''Ford of Abez''' (track, ''Outriding the Outriders'').

(Note: earlier versions of SoF were set in a completely different location in the far western foothills of the Heart Mountains. This was an error by some hapless chronicler.)

=== Son Of The Black Eye ===

This campaign takes place off the northern edge of the main map and has its own tracking map (see "The Far North") above. There is no reference to anywhere on the main map other than Dwarven Doors, and that does not indicate either distance or direction.

=== Dead Water ===

This campaign has a tracking map. It takes place on and near the coast of the Far North; the port city of Tirigaz, mentioned in '''Son of the Black-Eye''', is a locale of one scenario. We learn that one of the small islands off the coast is called Bilheld and is inhabited by drakes.

=== Secrets of the Ancients ===

This campaign has a tracking map. It begins at the Great Academy on Alduin.

=== Delfador's Memoirs ===

This campaign has a tracking map. Its scenario locations are in general well known from other campaigns. The campaign maps feature some [http://wiki.wesnoth.org/CampaignDialogue:DM#Places_.28labels.29 map labels]

=== Northern Rebirth ===

This campaign has a tracking map. It begins in Dwarven Doors. No distances or directions to places elsewhere in canon are indicated.

=== Under The Burning Suns ===

This campaign has no tracking map. It takes place long after the fall of Wesnoth and none of its locations can be clearly tied to anywhere in the main map.

== See Also ==

* [[Timeline of Wesnoth]]

[[Category:World of Wesnoth]]

Geography of Wesnoth

2018-05-20T09:33:09Z

Zookeeper: Updated SotBE and DW map links, and added Green Isle map link

{{Translations}}
== Irdya ==

The name of the world in which the kingdom of Wesnoth is situated is "Irdya". This term is , however, only rarely used in the era depicted by the main map. People normally just say "the world" or, poetically, "the wide green world".

== Wesnoth and Surrounding Lands ==

[https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/core/images/maps/titlescreen.png Map of Wesnoth and Surrounding Lands]

This map is current for approximately YW 450. Named cities were founded during the Golden Age of Wesnoth and have thus have existed for at least 200 years.

Place names in '''bold''' are marked on the main map.

* Major features:
** '''The Great Ocean''': Lies to the west of the continent and all rivers eventually flow to it.
** The '''Bay of Pearls''': The Elensefar Peninsula in the North and the '''Isle of Alduin''' in the southwest separate this from the Great Ocean. This is where human refugees from the Green Isle first landed in 1YW.
** '''Isle of Alduin''': Inhabited island off the west coast of the Great Continent. Home of the Great Academy of Magic and a traditional center of magecraft.
** '''The Three Sisters''': Group of three islands north-northwest of Alduin. The nearest is individually known as the Isle of the Damned and has an evil reputation.
** '''The Great River''': Runs east to west on the main map, unmarked.
** '''Ford of Abez''': Easternmost point at which the Great River can be crossed without ships. A traditional invasion route for armies crossing in either direction.
** '''River Weldyn''': Tributary running north from the '''Dulatus Hills''' to the '''Great River'''.
** River Aethen: River running from the '''Dulatus Hills''' to the '''Great Ocean''' through the '''Aethenwood'''.
** '''The Heart Mountains''': the major mountain range surrounding '''Lake Vrug'''.

=== Wesnoth ===
The Kingdom of Wesnoth is located in the north-central portion of the Great Continent. Most of the mainline campaigns revolve around it. It is bounded on the map by the '''Great River''' to the north, the shore of the '''Great Ocean''' to the west, the Aethenwood to the southwest, and the '''Bitter Swamp''' to the southeast (lower right corner of the main map).

Over the '''River Aethen''', south of '''Fort Tahn''', is a Wesnothian frontier region. It is bounded to the south (off-map) by dense woods of which the '''Aethenwood''' may be considered a northernmost extension.

* Notable cities:
** '''Weldyn''': The capital of Wesnoth.
** '''Aldril''': City lying on the Bay of Pearls.
** '''Blackwater Port''': City lying south of the Bay of Pearls.
** '''Carcyn''': Located between the Grey Woods and the Great River.
** '''Dan'Tonk''': Wesnoth's largest city, located in the center of the country, just west and north of Weldyn.
** '''Soradoc''': The northernmost border outpost of Wesnoth, controls the confluence of the Weldyn River and the Great River.
** '''Fort Tahn''': The southernmost border outpost, controls the north/south road crossing the River Aethen.
** '''Tath''': Important fort city north of Dan'Tonk, exerts control over the wilderness country around the east of the Brown Hills and north to the '''Ford of Abez'''.

* Notable land features:
** '''Gryphon Mountain''': Home of the fabled Gryphons
** '''Ford of Abez''': Shallow part of the Great River, it is usually controlled by Wesnothian forces
** '''Weldyn River''': It branches from the Great River and goes south
** Great Central Plain: Area bounded by Weldyn, Dan'Tonk, and Fort Tahn, this plain is Wesnoth's bread basket and home to most of its population
** '''Dulatus Hills''': These rolling hills bordering the Great Central Plain provide much of Wesnoth's livestock and agriculture
** Brown Hills: Wasteland surrounding Gryphon Mountain that is not well-populated and occasionally very dangerous.
** Horse Plains: Region of rolling plains just south of the '''Great River''', bounded by '''Glyn's Forest''' to the west and the '''River Weldyn''' to the east; the southern reach merges into the Central Plain. Home of the powerful Clans; the best horses in Wesnoth are bred here.
** '''Estmark Hills''': Largish range rising south of the Great River and east of the Weldyn River. The northernmost portion, nearest the '''River Weldyn''', has at various times been settled by Wesnothians, but the Kingdom's control is tenuous at best and banditry is common.
** '''Glyn's Forest''': Sometimes known as the Royal Forest, named for one of Haldric II's sons
** '''Grey Woods''': Large forest in the heart of the wilds of Wesnoth, located between Carcyn and Aldril and generally considered to be haunted
** Green Swamp: Large swamp in the heart of the wilds of Wesnoth, south of Aldril. (Not shown on the main map.)

=== Southwest Elven Lands ===
The Wood Elves are separate from those of the north, and have only intermittent relations with them and most other countries. Its borders are the Green Swamp to the northeast, the desert (not shown) to the south, and the Ocean to the west.
* Notable cities
** None known
* Notable land features:
** '''Aethen Forest''': The largest southern forest, it extends far to the southwest - much farther than is charted - and is home to elves

=== Elensefar ===
'''Elensefar''' is at times a province of Wesnoth, at times an independent country, and at times in a treaty federation with Wesnoth. Its borders are the Great River to the north, a loosely defined line with Wesnoth to the east, the Bay of Pearls to the south, and the ocean to the west. More information is found in the [[Timeline of Wesnoth|historical narrative]] of Wesnoth.

* Notable cities:
** '''Elensefar''': The capital, located on an island in the Great River delta
** '''Carcyn''': City on the Wesnoth-Elensefar border, disputed with Wesnoth
* Notable land features:
** '''Great River''': It is very wide at this point, and only ships can cross it.

=== Northlands ===

There is no government of the Northlands. Various groups of orcs, dwarves, barbarian men and even elves populate the region. The northern and eastern borders are not defined, the southern border is the '''Great River''', and the western border is the '''Great Ocean'''.

* Notable cities:
** '''Glamdrol''': An Orcish tribal capital
** '''Romyr''': Another Orcish tribal capital
** '''Wesmere''': The location of the Ka'lian - the Elvish Council
** Dwarven Doors: A mixed human/dwarven town in the region of Knalga in the southern Heart Mountains. A major trade center.
** Dallben and Delwyn: Human villages originally built by settlers who crossed the Great River during Wesnoth's Golden Age expansion. Now abandoned. The forested area northeast of '''Elensefar''', where these villages were located, was named the Annuvin province by men but was known by the elves as Wesmere.

* Notable land features:
** '''Heart Mountains''': A virtually impassable barrier between the river country and the Northern Plains.
** Heartfangs: the particularly forbidding stretch of high peaks southwest of '''Lake Vrug''' and north of the '''Forest of Wesmere'''. The most inhospitable and dangerous portion of the '''Heart Mountains'''; only hermits, madmen, and mages live there.
** '''Swamp of Dread''': a very large bog located between the '''Heart Mountains''' and the '''Great River'''. A notoriously dangerous place.
** '''Lake Vrug''': A large mountain lake whose river carves the only pathway through the Northern Mountains
** '''Arkan-thoria''': The river than comes out of Lake Vrug. This is the elvish name; among humans it is called Longlier.
** '''River Listra''': The south-running tributary of the Great River into which the '''Arkan-thoria''' empties.
** '''Lintanir Forest''': The southernmost portion of the Great Northern Forest, a gigantic wood whose eastern and northern boundaries are known only the elves. Their capitol, Elensiria, has only seldom been visited by humans.
** '''Great River''': The origin of this river is somewhere in the east of the northern lands

==== Wesmere====
The location of the Ka'lian - the Elvish Council in the Eastern part of the forest. The river Telfar flows through the forest. The Kal'ian is on an island in the Telfar. The River Telfar is crossed by the Northern Shallows, the Ford of Alyas, the Ford of Tifranur and the North Bridge. Villages surrounding the Ka'lian are named Telionath, Arthen, Arryn, Illissa, Viricon, Tireas, Essarn, Valcathra, Aelion, Elendor, Erethean. Other areas near the Ka'lian are Brightleaf Wood, Telfar Green (an opening in the forest), Dancer’s Green (an opening in the forest), Karmarth Hills, Westwind Wood (possibly the foothills of the Heart Mountains to the north east of Wesmere), Southwind Wood. East and outside are the forest are the villages of Dallben and Delwyn.

== Far North ==

[https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Son_Of_The_Black_Eye/images/maps/sotbe.png Map of the Far North]

Cold, harsh, and inaccessible, the Far North is the ancestral home of the Orcish Clannate. It lies north of the Heart Mountains, which the Orcs call the Haggid-Dargor and claim (without merit) as their own. To the east lie the Unaligned Tribes of the Wild Steppe, who fell out of the control of the Clannate, instead roaming with wild human barbarians and clashing with the High Elves of the North Plains (known as North Elves in human lands). The High Elves themselves reside further east, where it is rumored they rule a vast kingdom.

* Notable cities:
** Barag Gor, a city home to the Orcish Council
** Bitok
** Borstep
** Castelfrang
** Farzi
** Festog
** Grisbi
** Lmarig
** Melmog
** Prestim
** Tirigaz
* Notable land features:
** Swamp of Desolation
** Mountains of Dorth
** Mountains of Haag
** Green Forest
** Silent Forest
** Forest of Thelien
** River Oumph
** River Bork
** Wild Steppe

===Area around Tirigaz===
Featured in [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_Water Dead Water].

[https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Dead_Water/images/maps/dw.png Map of area around Tirigaz]

* Notable cities:
** Tirigaz
** Jotha
**Agvorad
* Notable land features:
** Swamp of Desolation
** Mountains of Dorth
** Bilheld, a large island.
** A small island of coast of Bilheld

== The Southern Land ==
<tt>Where is this confirmed?</tt>

This is the land to the far south of wesnoth.
* Notable cities:
** Serrul: a peaceful city that excels at sea trade.
** Varrant: a prosperous trade city.
** Kesh: a powerful military city.
** Azen: capitol of the Azgar (a Expansionist clan with a strong military force)
* Notable land features:
** The Ashland Desert: a long and hot desert that leads to Wesnoth.

== The Green Isle ==
The geography features in [http://wiki.wesnoth.org/Mainline_Campaigns#The_Rise_of_Wesnoth The Rise of Wesnoth].

[https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/The_Rise_Of_Wesnoth/images/maps/green_isle.png Map of The Green Isle]

=== Wesfolk Land ===
This is where the Wesfolk live, with their Lich overlords. The boundary between it and the Islefolk land is the hilly area running south-west to north-east. The Wesfolk land is in the north-west. Little is known about what happened to the island after Haldric left.
* Notable cities:
** Jevyan's Haven: The capital of the Wesfolk, where Jevyan reigned; presumably where the gates to orcland were opened

=== Islefolk Land ===
This is where the Islefolk (Haldric's folk) live. The boundary is the same as that of the Wesfolk; the islefolk land is to the southeast.
* Notable cities:
** Blackmore: {??}
** Clearwater Port: {??}
** Southbay: {??}

== Campaign References ==

This section collates specific facts about geography asserted in the the text of mainline campaigns, implied by map dots (track) or by features on a battle map (map). It aims to be complete as to locations on the main map and identifiably adjacent to it. Two groups of off-map locations are confined to single campaigns, the Green Isle in ''The Rise of Wesnoth'' and the Far North in ''Son of the Black Eye''; those locations are not listed here.

=== Heir To The Throne ===

Konrad was raised in the '''Aethenwood''' (track, ''The Elves Besieged''). He returns to the mainland very near the location where Haldric the Great first landed in 1YW. (map, ''Bay of Pearls''). The fight with Muff Malal takes place on the peninsula north of the '''Bay of Pearls''' (track, ''Bay of Pearls''). The city of '''Elensefar''' is actually located on a large island in the mouth of the '''Great River''' (map, ''The Siege of Elensefar''). The crossroads fight takes place where the roads from '''Carcyn''', '''Dan'Tonk''' and '''Fort Tahn''' meet (track, ''Crossroads''). Konrad meets Li'sar on the road between '''Dan'Tonk''' and '''Carcyn''' (track, ''The Princess of Wesnoth''). Konrad fights undead in the Brown Hills southeast of '''Gryphon Mountain''' (track, ''Valley of Death''). The track for ''Gryphon Mountain'' unsurprisingly lands on the '''Gryphon Mountain''' map feature; equally unsurprisingly, the track for ''Ford of Abez'' lands on the '''Ford of Abez''' map feature.

North of the '''Great River''' this campaign is our basic textual evidence for several important features. The country around the easternmost tip of the '''Swamp of Dread''' is described as "abundant pine forests nestled in rolling foothills" (track and text, ''Northern Winter'') and, at least during the Turmoil of Asheviere, is inhabited by orcs. Dwarven Doors and Knalga are located in the center of the southern arm of the Heart Mountains, south-southeast of Lake Vrug (''The Dwarven Doors''). Lionel, the Lost General, is found in an orcish warren at the northern edge of the southern '''Heart Mountains''', north-northeast of Knalga and adjacent to the valley of the Arkan-thoria (''The Lost General''). Konrad re-encounters Li'sar north across that valley in the foothills of the northern '''Heart Mountains''' (track, ''Hasty Alliance''). The Scepter of Fire is found in those same foothills a bit further east and south, just north of the southernmost bend of the '''Arkan-thoria''' (''Scepter of Fire'').

Konrad's party travels southeast through the caverns, under the '''Arkan-thoria''', to just south of a northward bend of the river (''A Choice Must Be Made''). Kalenz says that this river is called 'Longlier' by men and 'Arkan-thoria' by the Elves. He further says that the homeland of his people lies to the east and north. Kalenz identifies their location at the easternmost edge of the southern '''Heart Mountains''' (track, ''Snow Plains'') as "...once the home of my people. We left here centuries ago" (text). In the next scenario, the North Elves are contacted at the confluence of the '''Arkan-thoria''' and the '''Listra''' (track, ''Home of the North Elves''). Konrad's party take refuge in Emetria, an Elven castle located just within the border of the southern lobe '''Lintanir Forest'''. ''The Elven Council'' takes place in the elven capital of Elensiria, location not specified.

Konrad crosses the '''Great River''' into Wesnoth just north of '''Soradoc''' (''Return to Wesnoth''). The country between the Elven forests and the river is inhabited by, among other things, "hermit mages" (text). He then crosses the river into the '''Estmark Hills''' hills east of the '''Weldyn River''' (track, ''Test of the Clans'').

Neither the '''Estmark Hills''', nor the '''Heart Mountains''', nor the swamp between them and the '''Great River''' are named in this campaign, but one scenario title refers to the latter as ''Swamp of Dread''.

Continuity problems: the map for 'The Princess of Wesnoth' is difficult to reconcile with the track location; the lake to the south should be large enough to show on the main map and is difficult to fit in a valley in the Brown Hills.
Likewise, the map for ''Home of the North Elves'' shows only an east-west river probably too small to be the '''Arkan-thoria''', and not the '''Listra''' that it should flow into.

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:HttT#Labels map labels]

=== A Tale of Two Brothers ===

This campaign has a tracking map. In text, the village of Maghre is described as being in the "western reaches of Wesnoth" (''Rooting Out a Mage''). In ''The Chase'', the haunted forest is identified as the Grey Woods.

=== An Orcish Incursion ===

This campaign has a map and a journey track. No places are named other than '''Wesmere'''; the action takes place north and west of there. A pass that is bottleneck route through the northern mountains figures in the action.

=== The South Guard ===

This campaign takes place off the main map and has its own background map.

We know from it that the city of Westin is located southwest of '''Fort Tahn''' (track, ''Born To The Banner'') and is capital of the frontier province of Kerlath (text), also that the Aethenwood is to the west (text).

There is no map track after the second scenario. We learn that south of Westin , Kerlath is bounded by dense woods, "a bastion of the ancient heart forest of the Great Continent so dense and gloomy that even elves forbore from dwelling there."
(''Born to the Banner'') South of it an unspecified distance lies the elven Vale of Tears, and much further south of that the Black River, of which Etheliel says "No elf, still living, has crossed it."

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:TSG#Labels map labels]

=== Liberty ===

This campaign uses a modified version of the main Wesnoth map for tracking. The map shows the villages of Dallben and Delwyn, and some small patches of forest, between the forest of Wesmere and the ocean; also it labels the '''Grey Woods'''. Text (''The Raid'') identifies this as the province of Annuvin, a frontier area of Wesnoth. It is clear that '''Elensefar''' is the chief city of Annuvin.

Baldras and his party travel south to '''Elensefar''' (track, ''A Strategy of Hope''). From there they go upriver to '''Carcyn''' (track, ''Hide And Seek''), and south to the '''Grey Woods''' (track, ''The Grey Woods''), then south on the road to ''Aldril''. The campaign finishes at '''Halstead'''. In the Epilogue, there is a reference to villagers fleeing southwest to settle on the '''Three Sisters'''.

The scenario maps feature [http://wiki.wesnoth.org/CampaignDialogue:L#Labels map labels]

=== The Rise of Wesnoth ===

This campaign has its own tracking map for the Green Isle, which is our only actual source of information about the Green Isle's geography. The only Great Continent location of interest is the Ka'lian, which has the same location in the '''Forest of Wesmere''' that it does in other campaigns.

The lady Jessene uses the term "Old Continent" to describe the ancestral home of her people, and implies that it lies in "the far West".

=== The Legend of Wesmere ===
This campaign uses a [http://wiki.wesnoth.org/Geography_of_Wesnoth#LOW_Custom_Map modified version of the main Wesnoth map] for tracking. The map shows far fewer settlements with the notable addition of a castle settlement in the '''Swamp of Dread''', called '''Saurgrath''' (the location of ''The Saurian Treasury'').

The map track for ''Hostile Mountains'' shows Kalenz starting from the '''Lintanir Forest''' and moving across the easternmost '''Heart Mountains''' to a spot on the Arkan-thoria. They travel to '''Wesmere Forest''' (''The Ka'lian Under Attack''); the map tracking runs almost lengthwise through the '''Heart Mountains'''. The Ka'lian is near the northeast edge of '''Wesmere forest'''; the Elvish treasury is further west (track, ''The Elvish Treasury''). The Saurian treasury in the westernmost foothills of the '''Heart Mountains''' (track, ''The Saurian Treasury''); Kalenz and his men avoid the direct route from it back to Wesmere by going north from it and that they return via the eastern approaches to Wesmere. On the way, they re-encounter Olurf in the southeastern reaches of the '''Heart Mountains''' (''Acquaintance In Need''). They march back to the north edge of '''Wesmere Forest''' (track, ''Elves' Last Stand'').

In ''Council of Hard Choices'' we learn that the mage Crelanu lives in "the mountains of Thoria". The route north goes over the mountains to the "Arkan-thoria" (track: ''Bounty Hunters''), the name is confirmed in text. The mountains of Thoria themselves are just north of the valley of the '''Arkan-thoria''' (track, ''Cliffs of Thoria''). Crelanu's keep is well into the northern '''Heart Mountains''', right at the northern edge of the map (track, ''Battle of the Book'').

Kalenz and friends "return to the Ka'lian" (''News From The Front''); then to orcish forces are "encamped south of the '''Great River''', and have surrounded the fortified human settlement of Tath". The track for ''Breaking the Siege'' indicates that the killing of the Great Chief took place at the southeastern tip of the '''Heart Mountains''' and that ''Breaking the Siege'' takes place on the '''River Listra''', just north of the confluence with the '''Arkan-thoria'''.

The remaining scenarios convey no new information; the track points are all east of the '''River Listra''' between it and the '''Lintanir Forest'''.

Kalenz's home map has big water to the east. This has to be a lake off the NE corner of the main map, emptying into the main course of the Listra.

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:LOW#Labels map labels]
====LOW Custom Map====
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Legend_of_Wesmere/images/low-map.png https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Legend_of_Wesmere/images/low-map.png]

=== Eastern Invasion ===

This campaign has its own map, with the River Guard outposts shown, and a tracking map. The intro describes the location of the River Guard posts on "the near bank of the Weldyn", alludes to trouble in the Estmarks, and refers to "raiders from the great desert", location unspecified.

One path from ''An Unexpected Appearance'' leads west, the other east (text). But the western path forces Gweddry and his men to travel north, into "known forest country just south of the Great River" (text). On the other branch, Mal-Ravanal's capitol is in the '''Bitter Swamp''' (''Mal-Ravanal's Capitol''); the party flees "west and north" until they find a "low pass in the Estmarks, and [are] greatly relieved to see the valley of the Weldyn open before them." (text). In ''Undead Crossing'', Gweddry's party crosses the '''Great River''' to the north (text). One of the following scenarios is named '''Lake Vrug'''. In ''Drowned Plains'' the party goes south to the '''Great River''', crosses it, and Owaec announces that they have entered the Horse Plains. '''Weldyn''' is on the map of the final scenario.

The Orc kings stronghold map has [http://wiki.wesnoth.org/CampaignDialogue:EI#King_Dra-Nak.27s_City_.28labels.29 map labels]

=== The Hammer of Thursagan ===

This campaign has a tracking map. It begins at Knalga, and the heroes travel generally eastwards. There are no other specific geographical references in it, except to "the High Pass" about halfway between Knalga and Kal Kartha.

=== Descent Into Darkness ===

This campaign has a journey track, and a map on which the the "northern border town of Parthyn" (''Saving Parthyn'') appears. An eartly fight (''Orc War'') takes place near the river Longlier (the '''Arkan-thoria'''). This is denoted by a [http://wiki.wesnoth.org/CampaignDialogue:DID#Places_.28labels.29 map label]. Later in the campaign (''Return To Parthyn'') it is specified that Malin follows a trail south across the '''Great River''' and west to Parthyn. Part of the action (''A Small Favor'' and three sequels) takes place in the city of '''Tath'''.

=== Scepter of Fire ===

This campaign has a tracking map.
The campaign begins in "the foothills of Knalga" (text, ''A Bargain Is Struck'') when Haldric II rides north from there from the '''Ford of Abez'''. Rugnur looks for Thursagan in "the northern wastelands", which is near the coast north-northeast of Rumyr (''Searching for the Runecrafter''). Much of the rest of the campaign takes place in the old eastern mines just north of the Arkan-thoria; this is where the Scepter will be found in ''Heir To The Throne''. Alanin's running battle with the outriders takes place just north of the '''Ford of Abez''' (track, ''Outriding the Outriders'').

(Note: earlier versions of SoF were set in a completely different location in the far western foothills of the Heart Mountains. This was an error by some hapless chronicler.)

=== Son Of The Black Eye ===

This campaign takes place off the northern edge of the main map and has its own tracking map (see "The Far North") above. There is no reference to anywhere on the main map other than Dwarven Doors, and that does not indicate either distance or direction.

=== Dead Water ===

This campaign has a tracking map. It takes place on and near the coast of the Far North; the port city of Tirigaz, mentioned in '''Son of the Black-Eye''', is a locale of one scenario. We learn that one of the small islands off the coast is called Bilheld and is inhabited by drakes.

=== Secrets of the Ancients ===

This campaign has a tracking map. It begins at the Great Academy on Alduin.

=== Delfador's Memoirs ===

This campaign has a tracking map. Its scenario locations are in general well known from other campaigns. The campaign maps feature some [http://wiki.wesnoth.org/CampaignDialogue:DM#Places_.28labels.29 map labels]

=== Northern Rebirth ===

This campaign has a tracking map. It begins in Dwarven Doors. No distances or directions to places elsewhere in canon are indicated.

=== Under The Burning Suns ===

This campaign has no tracking map. It takes place long after the fall of Wesnoth and none of its locations can be clearly tied to anywhere in the main map.

== See Also ==

* [[Timeline of Wesnoth]]

[[Category:World of Wesnoth]]

Geography of Wesnoth

2018-05-20T09:19:19Z

Zookeeper: Updated main map link

{{Translations}}
== Irdya ==

The name of the world in which the kingdom of Wesnoth is situated is "Irdya". This term is , however, only rarely used in the era depicted by the main map. People normally just say "the world" or, poetically, "the wide green world".

== Wesnoth and Surrounding Lands ==

[https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/core/images/maps/titlescreen.png Map of Wesnoth and Surrounding Lands]

This map is current for approximately YW 450. Named cities were founded during the Golden Age of Wesnoth and have thus have existed for at least 200 years.

Place names in '''bold''' are marked on the main map.

* Major features:
** '''The Great Ocean''': Lies to the west of the continent and all rivers eventually flow to it.
** The '''Bay of Pearls''': The Elensefar Peninsula in the North and the '''Isle of Alduin''' in the southwest separate this from the Great Ocean. This is where human refugees from the Green Isle first landed in 1YW.
** '''Isle of Alduin''': Inhabited island off the west coast of the Great Continent. Home of the Great Academy of Magic and a traditional center of magecraft.
** '''The Three Sisters''': Group of three islands north-northwest of Alduin. The nearest is individually known as the Isle of the Damned and has an evil reputation.
** '''The Great River''': Runs east to west on the main map, unmarked.
** '''Ford of Abez''': Easternmost point at which the Great River can be crossed without ships. A traditional invasion route for armies crossing in either direction.
** '''River Weldyn''': Tributary running north from the '''Dulatus Hills''' to the '''Great River'''.
** River Aethen: River running from the '''Dulatus Hills''' to the '''Great Ocean''' through the '''Aethenwood'''.
** '''The Heart Mountains''': the major mountain range surrounding '''Lake Vrug'''.

=== Wesnoth ===
The Kingdom of Wesnoth is located in the north-central portion of the Great Continent. Most of the mainline campaigns revolve around it. It is bounded on the map by the '''Great River''' to the north, the shore of the '''Great Ocean''' to the west, the Aethenwood to the southwest, and the '''Bitter Swamp''' to the southeast (lower right corner of the main map).

Over the '''River Aethen''', south of '''Fort Tahn''', is a Wesnothian frontier region. It is bounded to the south (off-map) by dense woods of which the '''Aethenwood''' may be considered a northernmost extension.

* Notable cities:
** '''Weldyn''': The capital of Wesnoth.
** '''Aldril''': City lying on the Bay of Pearls.
** '''Blackwater Port''': City lying south of the Bay of Pearls.
** '''Carcyn''': Located between the Grey Woods and the Great River.
** '''Dan'Tonk''': Wesnoth's largest city, located in the center of the country, just west and north of Weldyn.
** '''Soradoc''': The northernmost border outpost of Wesnoth, controls the confluence of the Weldyn River and the Great River.
** '''Fort Tahn''': The southernmost border outpost, controls the north/south road crossing the River Aethen.
** '''Tath''': Important fort city north of Dan'Tonk, exerts control over the wilderness country around the east of the Brown Hills and north to the '''Ford of Abez'''.

* Notable land features:
** '''Gryphon Mountain''': Home of the fabled Gryphons
** '''Ford of Abez''': Shallow part of the Great River, it is usually controlled by Wesnothian forces
** '''Weldyn River''': It branches from the Great River and goes south
** Great Central Plain: Area bounded by Weldyn, Dan'Tonk, and Fort Tahn, this plain is Wesnoth's bread basket and home to most of its population
** '''Dulatus Hills''': These rolling hills bordering the Great Central Plain provide much of Wesnoth's livestock and agriculture
** Brown Hills: Wasteland surrounding Gryphon Mountain that is not well-populated and occasionally very dangerous.
** Horse Plains: Region of rolling plains just south of the '''Great River''', bounded by '''Glyn's Forest''' to the west and the '''River Weldyn''' to the east; the southern reach merges into the Central Plain. Home of the powerful Clans; the best horses in Wesnoth are bred here.
** '''Estmark Hills''': Largish range rising south of the Great River and east of the Weldyn River. The northernmost portion, nearest the '''River Weldyn''', has at various times been settled by Wesnothians, but the Kingdom's control is tenuous at best and banditry is common.
** '''Glyn's Forest''': Sometimes known as the Royal Forest, named for one of Haldric II's sons
** '''Grey Woods''': Large forest in the heart of the wilds of Wesnoth, located between Carcyn and Aldril and generally considered to be haunted
** Green Swamp: Large swamp in the heart of the wilds of Wesnoth, south of Aldril. (Not shown on the main map.)

=== Southwest Elven Lands ===
The Wood Elves are separate from those of the north, and have only intermittent relations with them and most other countries. Its borders are the Green Swamp to the northeast, the desert (not shown) to the south, and the Ocean to the west.
* Notable cities
** None known
* Notable land features:
** '''Aethen Forest''': The largest southern forest, it extends far to the southwest - much farther than is charted - and is home to elves

=== Elensefar ===
'''Elensefar''' is at times a province of Wesnoth, at times an independent country, and at times in a treaty federation with Wesnoth. Its borders are the Great River to the north, a loosely defined line with Wesnoth to the east, the Bay of Pearls to the south, and the ocean to the west. More information is found in the [[Timeline of Wesnoth|historical narrative]] of Wesnoth.

* Notable cities:
** '''Elensefar''': The capital, located on an island in the Great River delta
** '''Carcyn''': City on the Wesnoth-Elensefar border, disputed with Wesnoth
* Notable land features:
** '''Great River''': It is very wide at this point, and only ships can cross it.

=== Northlands ===

There is no government of the Northlands. Various groups of orcs, dwarves, barbarian men and even elves populate the region. The northern and eastern borders are not defined, the southern border is the '''Great River''', and the western border is the '''Great Ocean'''.

* Notable cities:
** '''Glamdrol''': An Orcish tribal capital
** '''Romyr''': Another Orcish tribal capital
** '''Wesmere''': The location of the Ka'lian - the Elvish Council
** Dwarven Doors: A mixed human/dwarven town in the region of Knalga in the southern Heart Mountains. A major trade center.
** Dallben and Delwyn: Human villages originally built by settlers who crossed the Great River during Wesnoth's Golden Age expansion. Now abandoned. The forested area northeast of '''Elensefar''', where these villages were located, was named the Annuvin province by men but was known by the elves as Wesmere.

* Notable land features:
** '''Heart Mountains''': A virtually impassable barrier between the river country and the Northern Plains.
** Heartfangs: the particularly forbidding stretch of high peaks southwest of '''Lake Vrug''' and north of the '''Forest of Wesmere'''. The most inhospitable and dangerous portion of the '''Heart Mountains'''; only hermits, madmen, and mages live there.
** '''Swamp of Dread''': a very large bog located between the '''Heart Mountains''' and the '''Great River'''. A notoriously dangerous place.
** '''Lake Vrug''': A large mountain lake whose river carves the only pathway through the Northern Mountains
** '''Arkan-thoria''': The river than comes out of Lake Vrug. This is the elvish name; among humans it is called Longlier.
** '''River Listra''': The south-running tributary of the Great River into which the '''Arkan-thoria''' empties.
** '''Lintanir Forest''': The southernmost portion of the Great Northern Forest, a gigantic wood whose eastern and northern boundaries are known only the elves. Their capitol, Elensiria, has only seldom been visited by humans.
** '''Great River''': The origin of this river is somewhere in the east of the northern lands

==== Wesmere====
The location of the Ka'lian - the Elvish Council in the Eastern part of the forest. The river Telfar flows through the forest. The Kal'ian is on an island in the Telfar. The River Telfar is crossed by the Northern Shallows, the Ford of Alyas, the Ford of Tifranur and the North Bridge. Villages surrounding the Ka'lian are named Telionath, Arthen, Arryn, Illissa, Viricon, Tireas, Essarn, Valcathra, Aelion, Elendor, Erethean. Other areas near the Ka'lian are Brightleaf Wood, Telfar Green (an opening in the forest), Dancer’s Green (an opening in the forest), Karmarth Hills, Westwind Wood (possibly the foothills of the Heart Mountains to the north east of Wesmere), Southwind Wood. East and outside are the forest are the villages of Dallben and Delwyn.

== Far North ==

[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Son_Of_The_Black_Eye/images/maps/sotbe.png https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Son_Of_The_Black_Eye/images/maps/sotbe.png]

Cold, harsh, and inaccessible, the Far North is the ancestral home of the Orcish Clannate. It lies north of the Heart Mountains, which the Orcs call the Haggid-Dargor and claim (without merit) as their own. To the east lie the Unaligned Tribes of the Wild Steppe, who fell out of the control of the Clannate, instead roaming with wild human barbarians and clashing with the High Elves of the North Plains (known as North Elves in human lands). The High Elves themselves reside further east, where it is rumored they rule a vast kingdom.

* Notable cities:
** Barag Gor, a city home to the Orcish Council
** Bitok
** Borstep
** Castelfrang
** Farzi
** Festog
** Grisbi
** Lmarig
** Melmog
** Prestim
** Tirigaz
* Notable land features:
** Swamp of Desolation
** Mountains of Dorth
** Mountains of Haag
** Green Forest
** Silent Forest
** Forest of Thelien
** River Oumph
** River Bork
** Wild Steppe

===Area around Tirigaz===
Featured in [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_Water Dead Water].

[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Dead_Water/images/maps/dw.png https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Dead_Water/images/maps/dw.png]
* Notable cities:
** Tirigaz
** Jotha
**Agvorad
* Notable land features:
** Swamp of Desolation
** Mountains of Dorth
** Bilheld, a large island.
** A small island of coast of Bilheld

== The Southern Land ==
<tt>Where is this confirmed?</tt>

This is the land to the far south of wesnoth.
* Notable cities:
** Serrul: a peaceful city that excels at sea trade.
** Varrant: a prosperous trade city.
** Kesh: a powerful military city.
** Azen: capitol of the Azgar (a Expansionist clan with a strong military force)
* Notable land features:
** The Ashland Desert: a long and hot desert that leads to Wesnoth.

== The Green Isle ==
The geography features in [http://wiki.wesnoth.org/Mainline_Campaigns#The_Rise_of_Wesnoth The Rise of Wesnoth]. In this place names are placed over the map below as overlays.
http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/data/campaigns/The_Rise_Of_Wesnoth/images/story/the_green_isle.png
=== Wesfolk Land ===
This is where the Wesfolk live, with their Lich overlords. The boundary between it and the Islefolk land is the hilly area running south-west to north-east. The Wesfolk land is in the north-west. Little is known about what happened to the island after Haldric left.
* Notable cities:
** Jevyan's Haven: The capital of the Wesfolk, where Jevyan reigned; presumably where the gates to orcland were opened
* Notable land features
** None. (its not a very detailed map, is it? :) )

=== Islefolk Land ===
This is where the Islefolk (Haldric's folk) live. The boundary is the same as that of the Wesfolk; the islefolk land is to the southeast.
* Notable cities:
** Blackmore: {??}
** Clearwater Port: {??}
** Southbay: {??}
* Notable land features:
** None. (see Wesfolk land)

== Campaign References ==

This section collates specific facts about geography asserted in the the text of mainline campaigns, implied by map dots (track) or by features on a battle map (map). It aims to be complete as to locations on the main map and identifiably adjacent to it. Two groups of off-map locations are confined to single campaigns, the Green Isle in ''The Rise of Wesnoth'' and the Far North in ''Son of the Black Eye''; those locations are not listed here.

=== Heir To The Throne ===

Konrad was raised in the '''Aethenwood''' (track, ''The Elves Besieged''). He returns to the mainland very near the location where Haldric the Great first landed in 1YW. (map, ''Bay of Pearls''). The fight with Muff Malal takes place on the peninsula north of the '''Bay of Pearls''' (track, ''Bay of Pearls''). The city of '''Elensefar''' is actually located on a large island in the mouth of the '''Great River''' (map, ''The Siege of Elensefar''). The crossroads fight takes place where the roads from '''Carcyn''', '''Dan'Tonk''' and '''Fort Tahn''' meet (track, ''Crossroads''). Konrad meets Li'sar on the road between '''Dan'Tonk''' and '''Carcyn''' (track, ''The Princess of Wesnoth''). Konrad fights undead in the Brown Hills southeast of '''Gryphon Mountain''' (track, ''Valley of Death''). The track for ''Gryphon Mountain'' unsurprisingly lands on the '''Gryphon Mountain''' map feature; equally unsurprisingly, the track for ''Ford of Abez'' lands on the '''Ford of Abez''' map feature.

North of the '''Great River''' this campaign is our basic textual evidence for several important features. The country around the easternmost tip of the '''Swamp of Dread''' is described as "abundant pine forests nestled in rolling foothills" (track and text, ''Northern Winter'') and, at least during the Turmoil of Asheviere, is inhabited by orcs. Dwarven Doors and Knalga are located in the center of the southern arm of the Heart Mountains, south-southeast of Lake Vrug (''The Dwarven Doors''). Lionel, the Lost General, is found in an orcish warren at the northern edge of the southern '''Heart Mountains''', north-northeast of Knalga and adjacent to the valley of the Arkan-thoria (''The Lost General''). Konrad re-encounters Li'sar north across that valley in the foothills of the northern '''Heart Mountains''' (track, ''Hasty Alliance''). The Scepter of Fire is found in those same foothills a bit further east and south, just north of the southernmost bend of the '''Arkan-thoria''' (''Scepter of Fire'').

Konrad's party travels southeast through the caverns, under the '''Arkan-thoria''', to just south of a northward bend of the river (''A Choice Must Be Made''). Kalenz says that this river is called 'Longlier' by men and 'Arkan-thoria' by the Elves. He further says that the homeland of his people lies to the east and north. Kalenz identifies their location at the easternmost edge of the southern '''Heart Mountains''' (track, ''Snow Plains'') as "...once the home of my people. We left here centuries ago" (text). In the next scenario, the North Elves are contacted at the confluence of the '''Arkan-thoria''' and the '''Listra''' (track, ''Home of the North Elves''). Konrad's party take refuge in Emetria, an Elven castle located just within the border of the southern lobe '''Lintanir Forest'''. ''The Elven Council'' takes place in the elven capital of Elensiria, location not specified.

Konrad crosses the '''Great River''' into Wesnoth just north of '''Soradoc''' (''Return to Wesnoth''). The country between the Elven forests and the river is inhabited by, among other things, "hermit mages" (text). He then crosses the river into the '''Estmark Hills''' hills east of the '''Weldyn River''' (track, ''Test of the Clans'').

Neither the '''Estmark Hills''', nor the '''Heart Mountains''', nor the swamp between them and the '''Great River''' are named in this campaign, but one scenario title refers to the latter as ''Swamp of Dread''.

Continuity problems: the map for 'The Princess of Wesnoth' is difficult to reconcile with the track location; the lake to the south should be large enough to show on the main map and is difficult to fit in a valley in the Brown Hills.
Likewise, the map for ''Home of the North Elves'' shows only an east-west river probably too small to be the '''Arkan-thoria''', and not the '''Listra''' that it should flow into.

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:HttT#Labels map labels]

=== A Tale of Two Brothers ===

This campaign has a tracking map. In text, the village of Maghre is described as being in the "western reaches of Wesnoth" (''Rooting Out a Mage''). In ''The Chase'', the haunted forest is identified as the Grey Woods.

=== An Orcish Incursion ===

This campaign has a map and a journey track. No places are named other than '''Wesmere'''; the action takes place north and west of there. A pass that is bottleneck route through the northern mountains figures in the action.

=== The South Guard ===

This campaign takes place off the main map and has its own background map.

We know from it that the city of Westin is located southwest of '''Fort Tahn''' (track, ''Born To The Banner'') and is capital of the frontier province of Kerlath (text), also that the Aethenwood is to the west (text).

There is no map track after the second scenario. We learn that south of Westin , Kerlath is bounded by dense woods, "a bastion of the ancient heart forest of the Great Continent so dense and gloomy that even elves forbore from dwelling there."
(''Born to the Banner'') South of it an unspecified distance lies the elven Vale of Tears, and much further south of that the Black River, of which Etheliel says "No elf, still living, has crossed it."

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:TSG#Labels map labels]

=== Liberty ===

This campaign uses a modified version of the main Wesnoth map for tracking. The map shows the villages of Dallben and Delwyn, and some small patches of forest, between the forest of Wesmere and the ocean; also it labels the '''Grey Woods'''. Text (''The Raid'') identifies this as the province of Annuvin, a frontier area of Wesnoth. It is clear that '''Elensefar''' is the chief city of Annuvin.

Baldras and his party travel south to '''Elensefar''' (track, ''A Strategy of Hope''). From there they go upriver to '''Carcyn''' (track, ''Hide And Seek''), and south to the '''Grey Woods''' (track, ''The Grey Woods''), then south on the road to ''Aldril''. The campaign finishes at '''Halstead'''. In the Epilogue, there is a reference to villagers fleeing southwest to settle on the '''Three Sisters'''.

The scenario maps feature [http://wiki.wesnoth.org/CampaignDialogue:L#Labels map labels]

=== The Rise of Wesnoth ===

This campaign has its own tracking map for the Green Isle, which is our only actual source of information about the Green Isle's geography. The only Great Continent location of interest is the Ka'lian, which has the same location in the '''Forest of Wesmere''' that it does in other campaigns.

The lady Jessene uses the term "Old Continent" to describe the ancestral home of her people, and implies that it lies in "the far West".

=== The Legend of Wesmere ===
This campaign uses a [http://wiki.wesnoth.org/Geography_of_Wesnoth#LOW_Custom_Map modified version of the main Wesnoth map] for tracking. The map shows far fewer settlements with the notable addition of a castle settlement in the '''Swamp of Dread''', called '''Saurgrath''' (the location of ''The Saurian Treasury'').

The map track for ''Hostile Mountains'' shows Kalenz starting from the '''Lintanir Forest''' and moving across the easternmost '''Heart Mountains''' to a spot on the Arkan-thoria. They travel to '''Wesmere Forest''' (''The Ka'lian Under Attack''); the map tracking runs almost lengthwise through the '''Heart Mountains'''. The Ka'lian is near the northeast edge of '''Wesmere forest'''; the Elvish treasury is further west (track, ''The Elvish Treasury''). The Saurian treasury in the westernmost foothills of the '''Heart Mountains''' (track, ''The Saurian Treasury''); Kalenz and his men avoid the direct route from it back to Wesmere by going north from it and that they return via the eastern approaches to Wesmere. On the way, they re-encounter Olurf in the southeastern reaches of the '''Heart Mountains''' (''Acquaintance In Need''). They march back to the north edge of '''Wesmere Forest''' (track, ''Elves' Last Stand'').

In ''Council of Hard Choices'' we learn that the mage Crelanu lives in "the mountains of Thoria". The route north goes over the mountains to the "Arkan-thoria" (track: ''Bounty Hunters''), the name is confirmed in text. The mountains of Thoria themselves are just north of the valley of the '''Arkan-thoria''' (track, ''Cliffs of Thoria''). Crelanu's keep is well into the northern '''Heart Mountains''', right at the northern edge of the map (track, ''Battle of the Book'').

Kalenz and friends "return to the Ka'lian" (''News From The Front''); then to orcish forces are "encamped south of the '''Great River''', and have surrounded the fortified human settlement of Tath". The track for ''Breaking the Siege'' indicates that the killing of the Great Chief took place at the southeastern tip of the '''Heart Mountains''' and that ''Breaking the Siege'' takes place on the '''River Listra''', just north of the confluence with the '''Arkan-thoria'''.

The remaining scenarios convey no new information; the track points are all east of the '''River Listra''' between it and the '''Lintanir Forest'''.

Kalenz's home map has big water to the east. This has to be a lake off the NE corner of the main map, emptying into the main course of the Listra.

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:LOW#Labels map labels]
====LOW Custom Map====
[https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Legend_of_Wesmere/images/low-map.png https://github.com/wesnoth/wesnoth/blob/master/data/campaigns/Legend_of_Wesmere/images/low-map.png]

=== Eastern Invasion ===

This campaign has its own map, with the River Guard outposts shown, and a tracking map. The intro describes the location of the River Guard posts on "the near bank of the Weldyn", alludes to trouble in the Estmarks, and refers to "raiders from the great desert", location unspecified.

One path from ''An Unexpected Appearance'' leads west, the other east (text). But the western path forces Gweddry and his men to travel north, into "known forest country just south of the Great River" (text). On the other branch, Mal-Ravanal's capitol is in the '''Bitter Swamp''' (''Mal-Ravanal's Capitol''); the party flees "west and north" until they find a "low pass in the Estmarks, and [are] greatly relieved to see the valley of the Weldyn open before them." (text). In ''Undead Crossing'', Gweddry's party crosses the '''Great River''' to the north (text). One of the following scenarios is named '''Lake Vrug'''. In ''Drowned Plains'' the party goes south to the '''Great River''', crosses it, and Owaec announces that they have entered the Horse Plains. '''Weldyn''' is on the map of the final scenario.

The Orc kings stronghold map has [http://wiki.wesnoth.org/CampaignDialogue:EI#King_Dra-Nak.27s_City_.28labels.29 map labels]

=== The Hammer of Thursagan ===

This campaign has a tracking map. It begins at Knalga, and the heroes travel generally eastwards. There are no other specific geographical references in it, except to "the High Pass" about halfway between Knalga and Kal Kartha.

=== Descent Into Darkness ===

This campaign has a journey track, and a map on which the the "northern border town of Parthyn" (''Saving Parthyn'') appears. An eartly fight (''Orc War'') takes place near the river Longlier (the '''Arkan-thoria'''). This is denoted by a [http://wiki.wesnoth.org/CampaignDialogue:DID#Places_.28labels.29 map label]. Later in the campaign (''Return To Parthyn'') it is specified that Malin follows a trail south across the '''Great River''' and west to Parthyn. Part of the action (''A Small Favor'' and three sequels) takes place in the city of '''Tath'''.

=== Scepter of Fire ===

This campaign has a tracking map.
The campaign begins in "the foothills of Knalga" (text, ''A Bargain Is Struck'') when Haldric II rides north from there from the '''Ford of Abez'''. Rugnur looks for Thursagan in "the northern wastelands", which is near the coast north-northeast of Rumyr (''Searching for the Runecrafter''). Much of the rest of the campaign takes place in the old eastern mines just north of the Arkan-thoria; this is where the Scepter will be found in ''Heir To The Throne''. Alanin's running battle with the outriders takes place just north of the '''Ford of Abez''' (track, ''Outriding the Outriders'').

(Note: earlier versions of SoF were set in a completely different location in the far western foothills of the Heart Mountains. This was an error by some hapless chronicler.)

=== Son Of The Black Eye ===

This campaign takes place off the northern edge of the main map and has its own tracking map (see "The Far North") above. There is no reference to anywhere on the main map other than Dwarven Doors, and that does not indicate either distance or direction.

=== Dead Water ===

This campaign has a tracking map. It takes place on and near the coast of the Far North; the port city of Tirigaz, mentioned in '''Son of the Black-Eye''', is a locale of one scenario. We learn that one of the small islands off the coast is called Bilheld and is inhabited by drakes.

=== Secrets of the Ancients ===

This campaign has a tracking map. It begins at the Great Academy on Alduin.

=== Delfador's Memoirs ===

This campaign has a tracking map. Its scenario locations are in general well known from other campaigns. The campaign maps feature some [http://wiki.wesnoth.org/CampaignDialogue:DM#Places_.28labels.29 map labels]

=== Northern Rebirth ===

This campaign has a tracking map. It begins in Dwarven Doors. No distances or directions to places elsewhere in canon are indicated.

=== Under The Burning Suns ===

This campaign has no tracking map. It takes place long after the fall of Wesnoth and none of its locations can be clearly tied to anywhere in the main map.

== See Also ==

* [[Timeline of Wesnoth]]

[[Category:World of Wesnoth]]

User:Shadowm/Stable 1.14 Announcement Outline

2018-04-16T10:20:42Z

Zookeeper: Forgot stone floor from new terrains list

'''This is an outline for the 1.14 Press Release-type announcement page'''

Add items you worked on or you know someone else worked on throughout 1.13.x. We don't want prose, we just want to enumerate items we'll talk about in the real release announcement. Someone else (or a plurality of someone elses) will magically turn your bullet points into marketing speech-style text for the announcement so you don't need to worry about doing that yourself.

For each section, try to list items in descending order of importance. The announcement team might not follow the order of the outline but it'd greatly help us to have a rough idea of how visible each item should be.

Tag platform specific features like this: "(<b>Windows only</b>) New user files location".

== For Players ==

=== Highlights ===

* <b>Steam launch</b>
* New title screen music, refined background and overall UI design, new UI font.
* New or updated terrains (notably: water, lava, desert mountains, walls (mine, straight mine, white, clean stone), aquatic camp and castle, troll encampment, sconces, stone floor and carpets, rusty and wooden gates, fake map edge now fully functional, added time of day variants for many villages)
* New unit animations
* New portraits
* Completely redesigned add-ons manager, more intuitive and featureful like.
* Revamped Preferences dialog.
* SDL 2.0, including:
** (<b>macOS only</b>) Resolves issues like non-working controls on Retina displays
** Borderless windowed instead of real fullscreen on all platforms
** Performance improvements when scrolling
** (TODO other stuff)

=== Campaigns ===

* <cite>Secrets of the Ancients</cite> addition to mainline
* <cite>Under the Burning Suns</cite> playable units refresh
* Refreshed maps in <cite>Northern Rebirth</cite>
* Ability to use mod add-ons in single-player campaigns

=== Multiplayer ===

* New MP UI and interaction flow
* Khalifate renamed to Dunefolk, balancing changes to the faction
* Addition of the ability to forfeit a game

=== Others ===

* Version info dialog with build info, paths, library versions, Copy to Clipboard option for bug reports
* (<b>Windows only</b>) New user files location, need to document how to make a "portable Wesnoth" on the wiki somewhere as well
* Possibility to change unit status orb colours to make it easier for people who require it to tell them apart.
* Music is now silenced by default when the game window loses focus.
* Cache Manager dialog.

== For Content Creators ==

* Lua interpreter update from version ??? to 5.3.4 compared to 1.12
* New WML preprocessor feature for named optional arguments (<code>#arg/#endarg</code>)
* Lua console and redesigned gamestate inspector
* Expand the Wesnoth Formula Language (WFL) with new syntax features and functions
* Allow use of WFL in many new places, including all four types of filter, unit abilities, weapon specials, and even some Image path Functions
* Several built-in predefined dialogs are now exposed to Lua, including the storyscreen
* Many expansions and some simplifications to the specification of AI parameter in WML and the Lua AI API
* [modification]s for singleplayer
* [on_undo] to make gamechanging actions undoable.
* New looping tags
* custom mapgenerator written in lua
* New file dialog to make it easier to open and edit your own and others' maps in the editor
* (<b>Windows only</b>) <code>--wconsole</code> to make Wesnoth's console output display in real time in a native console window
* (<b>Windows only</b>) Log files folder and new location for logs, easy access to the log for the current session from the build info UI
* Add-on <b>and</b> mainline content licensing policy changes

[[Category:Development]]

User:Shadowm/Stable 1.14 Announcement Outline

2018-04-16T10:19:47Z

Zookeeper: Listed notable terrain additions

'''This is an outline for the 1.14 Press Release-type announcement page'''

Add items you worked on or you know someone else worked on throughout 1.13.x. We don't want prose, we just want to enumerate items we'll talk about in the real release announcement. Someone else (or a plurality of someone elses) will magically turn your bullet points into marketing speech-style text for the announcement so you don't need to worry about doing that yourself.

For each section, try to list items in descending order of importance. The announcement team might not follow the order of the outline but it'd greatly help us to have a rough idea of how visible each item should be.

Tag platform specific features like this: "(<b>Windows only</b>) New user files location".

== For Players ==

=== Highlights ===

* <b>Steam launch</b>
* New title screen music, refined background and overall UI design, new UI font.
* New or updated terrains (notably: water, lava, desert mountains, walls (mine, straight mine, white, clean stone), aquatic camp and castle, troll encampment, sconces, carpets, rusty and wooden gates, fake map edge now fully functional, added time of day variants for many villages)
* New unit animations
* New portraits
* Completely redesigned add-ons manager, more intuitive and featureful like.
* Revamped Preferences dialog.
* SDL 2.0, including:
** (<b>macOS only</b>) Resolves issues like non-working controls on Retina displays
** Borderless windowed instead of real fullscreen on all platforms
** Performance improvements when scrolling
** (TODO other stuff)

=== Campaigns ===

* <cite>Secrets of the Ancients</cite> addition to mainline
* <cite>Under the Burning Suns</cite> playable units refresh
* Refreshed maps in <cite>Northern Rebirth</cite>
* Ability to use mod add-ons in single-player campaigns

=== Multiplayer ===

* New MP UI and interaction flow
* Khalifate renamed to Dunefolk, balancing changes to the faction
* Addition of the ability to forfeit a game

=== Others ===

* Version info dialog with build info, paths, library versions, Copy to Clipboard option for bug reports
* (<b>Windows only</b>) New user files location, need to document how to make a "portable Wesnoth" on the wiki somewhere as well
* Possibility to change unit status orb colours to make it easier for people who require it to tell them apart.
* Music is now silenced by default when the game window loses focus.
* Cache Manager dialog.

== For Content Creators ==

* Lua interpreter update from version ??? to 5.3.4 compared to 1.12
* New WML preprocessor feature for named optional arguments (<code>#arg/#endarg</code>)
* Lua console and redesigned gamestate inspector
* Expand the Wesnoth Formula Language (WFL) with new syntax features and functions
* Allow use of WFL in many new places, including all four types of filter, unit abilities, weapon specials, and even some Image path Functions
* Several built-in predefined dialogs are now exposed to Lua, including the storyscreen
* Many expansions and some simplifications to the specification of AI parameter in WML and the Lua AI API
* [modification]s for singleplayer
* [on_undo] to make gamechanging actions undoable.
* New looping tags
* custom mapgenerator written in lua
* New file dialog to make it easier to open and edit your own and others' maps in the editor
* (<b>Windows only</b>) <code>--wconsole</code> to make Wesnoth's console output display in real time in a native console window
* (<b>Windows only</b>) Log files folder and new location for logs, easy access to the log for the current session from the build info UI
* Add-on <b>and</b> mainline content licensing policy changes

[[Category:Development]]

TerrainGraphicsWML

2017-09-14T23:38:26Z

Zookeeper: Documented random_start=<int>

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''x''','''y''': constrains the rule to given absolute map coordinates. Primarily useful to place map-specific features.
* '''mod_x''','''mod_y''': {{DevFeature1.13|1}} constrains the rule to absolute map coordinates which are multiples of the given values. For example, mod_x=4 would only match locations with an x coordinate of 4, 8, 12, 16, etc.
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches.
** '''name''': for animated terrain this takes the form of a comma separated list of images with durations specified after ':'. A square bracket expansion can also be used as in AnimationWML (see in example below).
** '''no_draw''' (default: no): {{DevFeature1.13|5}} whether to actually draw images of this rule onto this hex.
** '''set_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate (See [[ImagePathFunctionWML]] for additional options).
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile {{DevFeature1.13|9}} If given a positive integer, limits the range of the random shift of the start time to the given amount of milliseconds. For example, if the animation duration is 700ms, then ''random_start=yes'' and ''random_start=700'' are equivalent, whereas ''random_start=100'' limits the start times of different instances of the animation to be at most 100ms apart.
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
**** '''has_flag''' {{DevFeature1.13|1}} comma-separated list of flags that the tile must have for this variant to apply.
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version.<br>For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne".<br>Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

To define an animated campfire at coordinates (4,5) with files "misc/fire-A01.png" to "misc/fire-A08.png" with an inter-frame transition time of 140, the following can be placed at the scenario top level (adapted from the CAMPFIRE macro):

[terrain_graphics]
x,y=4,5
[tile]
x=0
y=0
[image]
layer=0
name="misc/fire-A[01~08].png:140"
[/image]
[/tile]
[/terrain_graphics]

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* [[ImagePathFunctionWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

EventWML

2017-04-14T08:45:10Z

Zookeeper:

{{WML Tags}}
== The [event] Tag ==

This tag is a subtag of the [scenario], [unit_type] and [era] tags which is used to describe a set of [[ActionWML|actions]] which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit_type] tag, the event will occur in all scenarios in which a unit of that type appears in (only after such a unit appears during the scenario, however). When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the word "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

=== The 'name' Key (Mandatory) ===

Usage:
name=<value>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

name=attacker misses,defender misses

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

All predefined event types are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else.

Spaces in event names can be interchanged with ''underscores'' (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

==== Predefined Events Without Filters ====

These events do not take filter parameters (except [filter_condition] which works for all events).

===== preload =====

Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.

'''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

===== prestart =====

Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

===== start =====

Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

===== new turn =====

Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

===== turn end =====

Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

===== turn ''X'' end =====

Triggers at the end of turn ''X''.

===== side turn =====

Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

===== ai turn =====

Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.

'''Note:''' ''This event currently breaks replays since it is not explicitly saved in a replay and there is no AI involved in replays...''

===== turn refresh =====

Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.

Note that the turn refresh event does occur on turn 1, even though healing, income and unit refreshing do not.

===== turn ''X'' =====

Triggers at the start of turn ''X''. It's the first side initialization event.

Side initialization events go in the order of:

# '''turn ''X'''''
# '''new turn'''
# '''side turn'''
# '''side ''X'' turn'''
# '''side turn ''X'''''
# '''side ''X'' turn ''Y'''''
# '''turn refresh'''
# '''side ''X'' turn refresh'''
# '''turn ''X'' refresh'''
# '''side ''X'' turn ''Y'' refresh'''

===== side ''X'' turn ''Y'' =====

This event triggers at the start of turn ''Y'' of side X

===== side ''X'' turn =====

This event triggers at the start of any turn of side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side turn ''X'' =====

This event triggers at the start of any side on turn X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side X turn Y refresh =====

This event triggers at the turn refresh for side X on turn Y

===== side ''X'' turn refresh =====

This event triggers at the turn refresh for side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== turn ''X'' refresh =====

This event triggers for any side at the refresh of turn X.

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side turn end =====

Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:

# '''side turn end'''
# '''side ''X'' turn end'''
# '''side turn ''X'' end'''
# '''side ''X'' turn ''Y'' end'''
# '''turn end'''
# '''turn ''X'' end'''

===== time over =====

Triggers on turn ''turns''. (''turns'' is specified in [scenario])

===== enemies defeated =====

Triggers when all sides that are not defeated are allied and if there is at least one human (or human networked) side among them. Especially this event triggers in a situaltion that would normaly cause a victory due to enemies defeated. (regardless of whether this was disabled with victory_when_enemies_defeated=no).

===== victory =====

In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]]). This event is not synchonized in networked mp or in replays. The reason is that it is possible to have diffrent results in a mp game (one player wins so a '''victory''' event is fired on that client, other player loses so a '''defeat''' event is fired on his client)

===== defeat =====

In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]]). Like '''victory''', this event is not synchonized in networked mp or in replays.

==== Predefined Events With Filters ====

Filters (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]. weapon and second_weapon variables are available inside attack, attacker_hits, defender_hits, die and last_breath events. See [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] for more information.

===== moveto =====

Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. If the unit moves to a village, the capture event will be fired before this event. <br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not undo other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' $x2 and $y2 refer to the hex the unit came from.

===== sighted =====

A '''sighted''' event is triggered by a unit becoming visible to a side (other than the unit's own side). This is mostly useful when the side seeing the unit uses [[fog of war]] or [[shroud]], but they still fire even when fog/shroud is not in use, and they do take into account the {{tag2|AbilitiesWML#The_.5Babilities.5D_tag|hides}} ability (for a moving unit and for ambushers). The ''primary unit'' is the unit that became visible, and the ''secondary unit'' belongs to the side that now sees the primary unit. In some cases, sighted events can be delayed from when they "should" occur. If that happens, the secondary unit will be filtered as if it was at the location where the event "should" have occurred, and ''x2,y2'' will store that location (not the current position of the secondary unit). To understand when sighted events fire, it is helpful to distinguish the times the acting unit sights other units from the times when the acting unit is sighted.

An acting unit can sight other units when it is recruited, recalled, leveled, or moved, and when fog or shroud is cleared from occupied hexes as a result. In these cases, the acting unit is always the ''secondary unit''. For the first three actions, there are two events associated with the action; clearing occurs between these events, but any sighted events are fired after the second event. (For example, when a unit is recruited, the ''prerecruit'' event fires, then fog is cleared, then the ''recruit'' event fires, then ''sighted'' events fire.) For movement, the sighted events fire between ''enter_hex'' and ''exit_hex'' events, but sometimes sighted events are postponed until the moving unit reaches a good place to stop (e.g. not in an occupied hex). As a major exception to the above, players have the option to delay shroud (and fog) updates. If the player delays shroud updates, sighted events are also delayed until the shroud is updated.

An acting unit can be sighted by other sides when it is recruited, recalled, leveled (in rare cases), or moved. In these cases, the acting unit is always the ''primary unit''. These events fire after sightings by the acting unit (unless the player delayed shroud updates). For the first two, the sighted event fires for all sides that can see the unit, other than the unit's own side (even if those sides use neither fog nor shroud). For leveling units, sides that could see the unit before it leveled are excluded. (This is why these events are rare – the leveling unit must have lost a [hides] ability as a result of leveling in order to be seen after, but not before, leveling.) For movement, a sighted event is fired for each side that could see the unit after movement, but not before. In particular, only the starting and ending hexes are considered; a unit that moves through seen hexes but ends movement in a fogged hex does not trigger a sighted event for itself. In all cases where the acting unit is sighted, a (single) ''secondary unit'' is chosen from the sighting team. This choice should be considered arbitrary, but units within their sight range of the acting unit are chosen in preference to units further away. You may want to use [filter_second] in order to restrict a sighted event in a single player scenario to only being triggered by the player and not by other non-allied sides.

Sighted events are not triggered by a ''hides'' ability becoming inactive, unless it becomes inactive due to that unit's movement or to that unit ambushing another. (To detect a ''nightstalk'' ability becoming inactive due to time of day, use a ''new_turn'' event. Custom ''hides'' abilities might need similar handling.)

Sighted events have some special caveats for WML authors. First and foremost, {{tag|DirectActionsWML|allow_undo}} should generally be avoided in sighted events. It can be used if current unit positions have no bearing on the event, but otherwise it could cause a replay to go out of sync if a player delays shroud updates and undoes a move. This should not be an onerous restriction, though, as clearing fog will block the ability to undo, regardless of what happens within an event. Secondly, it is currently possible for WML to kill a unit involved in a sighted event before that event fires. If that happens, filters on the killed unit will not match anything and the event may seem to have not fired.

===== enter_hex =====

Triggers for each hex entered during movement, with $x1,$y1 identifying the hex entered and $x2,$y2 identifying the previous hex (just exited). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the entered hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

===== exit_hex =====

Triggers for each hex exited during movement, with $x1,$y1 identifying the hex exited and $x2,$y2 identifying the next hex (to be entered). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the exited hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

===== attack =====

Triggers when the primary unit attacks the secondary unit. Variables $weapon and $second_weapon contain weapons used for this attack by primary and secondary units respectively for all attack-related events (attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath).

===== attack end =====

Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

===== attacker hits =====

Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

===== attacker misses =====

Same as ''attacker hits'', but is triggered when the attacker misses.

===== defender hits =====

Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

===== defender misses =====

Same as ''defender hits'', but is triggered when the defender misses.

===== petrified =====
Triggers when the primary unit is hit by an attack with the 'petrifies' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'petrifies' ability).

===== last breath =====

Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

===== die =====

Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want to the primary unit to make a final [message], use name=last_breath, see above.

===== capture =====

Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture. This event will be fired before the moveto event. Villages becoming neutral (via [capture_village]) do not fire capture events. The variable $owner_side contains the previous owner side of the village. 0 means neutral.

===== recruit =====

Triggers when the primary unit is recruited (by the secondary unit). (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

===== prerecruit =====

Triggers when the primary unit is recruited (by the secondary unit) but before it is displayed.

===== recall =====

Triggers after the primary unit is recalled (by the secondary unit).

===== prerecall =====

Triggers when the primary unit is recalled (by the secondary unit) but before it is displayed.

===== advance =====

Triggers just before the primary unit is going to advance to another unit, or advance by AMLA. (This is after the player selects which advancement, if there is a choice). If this event removes the unit, changes the unit's type, or reduces the unit's experience below what it needs to advance, then the advancement is aborted. This also applies to advancement by AMLA.

===== pre advance =====

{{DevFeature1.13|0}} Triggers before the unit advancement dialog is shown. If this event removes the unit or reduces the unit's experience below what it needs to advance, then the advancement is aborted.

===== post advance =====

Triggers just after the primary unit has advanced to another unit, or advance by AMLA.

===== select =====

Triggers when the primary unit is selected. Prior to version 1.11, this also triggered when a move was interrupted, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

===== menu item ''X'' =====

Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

===== unit placed {{DevFeature1.13|3}}=====

Triggers when the primary unit is placed on the map, regardless of method. This includes but might not be limited to:
* Leaders and units placed in side definitions (fired once for every unit right before prestart events)
* Recruited and recalled units
* Units placed on the map with the [unit] tag ('''not''' units created directly onto a recall list or variable)
* Units placed by the wesnoth.put_unit() Lua function
* Units created via debug mode
* Units created by plague
* Every use of [unstore_unit]
This event is solely intended for special cases where no other event types suffice, for example if you must immediately apply a modification to every unit that ever appears. The event does '''not''' keep track of which units it has previously fired for, but can fire an unlimited number of times for the same unit as long the unit is "placed" several times and the event filter doesn't prevent it.

==== Custom events ====

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives. Also, custom events come very handy in [[Wml_optimisation]].

Example:
#The following is the definition of a custom event "unit recruited"
[event]
name=unit_recruited
first_time_only=no
[message]
speaker=unit
message=_ "Reporting for duty!"
[/message]
[/event]

#This is a standard recruit event that triggers whenever a unit is recruited by side 1
[event]
name=recruit
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

#And now a fire_event tag is used to trigger the previously defined event
[fire_event]
name=unit_recruited
[/fire_event]

#As a result, every time side 1 recruits a unit, this unit says "Reporting for duty!"
[/event]

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== id ====
: If an id is specified, then the event will not be added if another event with the same id already exists. An id will also allow the event to be removed, see below. Supplying a non-empty id= is mandatory in case of a [unit_type][event].

==== remove ====
: Whether to remove an event instead of adding a new one. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; if yes, then the contents of the event are ignored and the event with the specified id is removed instead. {{DevFeature1.13|0}} May be a comma separated list.

[event]
id=id_of_event_to_remove
remove=yes
[/event]

<b>Note:</b> {{DevFeature1.13|0}} You can now use [[InternalActionsWML#.5Bremove_event.5D|[remove_event]]] instead (the [event] remove= syntax still works). It also accepts a comma separated list.

[remove_event]
id=id_of_event_to_remove
[/remove_event]

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria based on the weapon used by the primary unit. This is usable in the events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'', ''attack end'', ''last breath'', and ''die''. For more information and filter keys, see [[FilterWML#Filtering Weapons|Filtering Weapons]]. The most commonly used keys are the following.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the weapon used by the secondary unit.

==== [filter_condition] ====
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* [[ConditionalActionsWML#Condition_Tags|Condition Tags]]
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

==== [filter_side] ====
: The current side (usually the side $side_number) must match the passed [[StandardSideFilter]] for the event to fire.
:* SSF tags and keys as arguments as described in [[StandardSideFilter]].
: note: This tag makes most sense in side turn and turn refresh events. However, all wml events have a current side so one could also prevent e.g. a moveto event from firing if you put a [filter_side] tag there and the moving unit's side doesn't match.

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all [[ActionWML|action tags]] within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

More details in [[ActionWML]].

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* enter hex
* exit hex
* sighted
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* pre advance
* post advance
* attack
* attack end
* attacker hits
* attacker misses
* defender hits
* defender misses
* start
* prestart (prestart are synced but [message][option] & [unstore_unit] advancement choices will do a random decision because UI things don't work during prestart events.)
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh
* side turn end
* side X turn end
* side turn X end
* side X turn Y end
* turn end
* turn X end
* {{DevFeature1.13|0}} enemies defeated
* {{DevFeature1.13|0}} time over
The following are <b>not</b> synced:
* select
* preload
* victory
* defeat
* ai turn

If an event is not listed here, ask someone to be sure.

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

You need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

=== Event IDs ===

This problem can be avoided by setting an '''id''' on the event, i.e.:

#define DOUBLE
[event]
name=multiply_by_2
id=doubler_event
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

Events with the same ID will only be accepted once by the engine no matter how many times they are included, and will only be saved once to the scenario's savefile. Events with an ID can also be removed by using the '''remove''' key, i.e.:

[event]
id=doubler_event
remove=yes
[/event]

After that WML is encountered (at toplevel or after created from another event), the event with this ID is removed from the scenario wml, thus firing it has no effect. After an event is removed, it can still be re-added later.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

[event]
name=die
[message]
speaker='''second_unit'''
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker='''unit'''
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]

An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.

=== Delayed Variable Substitution Example ===

This code will display a message showing the turn number on which the nested ''moveto'' event happens.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

The following code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Finally, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $|turn_number"}
[/event]
[/event]

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.
[event]# parent
name=turn 2
#delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event]# child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event]# great-grandchild
name=turn 5
{DEBUG_MSG $turn_number}# output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

ImagePathFunctions

2017-02-17T16:10:43Z

Zookeeper: Corrected ~LIGHTEN into ~BRIGHTEN and added removal notices

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester'' from the 1.10 add-on server.

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like "units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)" would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

= Changing the colors =

== BLEND: Color-blend function ==
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.

'''~BLEND(r,g,b,o)'''

The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

== BW: Black and White Function ==
{{devfeature1.13|1}}
May be used to convert the image to pure black and white, without grey pixels.

'''~BW(threshold)'''
* ''threshold'': a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.

== CS: Color-shift function ==
Performs simple per-channel color shifts by adding the arguments to the respective color channels.

''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

== GS: Greyscale Function ==
May be used to greyscale the image (turn to black and white)

'''~GS( )'''

== L: Lightmap color-shift function ==
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

'''~L(lightmap)'''

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully gray image (RGB = 128,128,128) and any non-gray pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

== NEG: Negative Function ==
{{devfeature1.13|0}}
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.

'''~NEG( )'''

Inverts the image, giving it an effect like a photographic negative.

{{devfeature1.13|1}} '''~NEG(''' ''threshold'' ''')'''

If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as ''solarization''.
Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

{{devfeature1.13|1}} '''~NEG(''' ''threshold_red, threshold_green, threshold_blue'' ''')'''

If a channel has a value greater than the corresponding threshold, the channel will be inverted.
Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

== PAL: Palette-switch Function ==
May be used to change colors in an image following the specifications of a source and target (new) palette.

'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

== RC: Re-Color Function ==
May be used to change some colors in an image.

'''~RC(''' ''source color palette'' '''>''' ''color range ID'' ''')'''
*''source color palette'' - the first parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.
*''color range ID'' - this is the second parameter, signifying the ID of a color range defined in the file ''data/core/team-colors.cfg'' (or it may be a custom ID for a color range defined locally).

=== Example ===
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

== SEPIA: Sepia Function ==
{{devfeature1.13|0}}
May be used to give to the image a sepia tint (like in old pictures).

'''~SEPIA()'''

== SWAP: Channel Swap Function ==
{{devfeature1.13|1}}
May be used to swap the RGBA channels of an image.

'''~SWAP(''' ''r, g, b'' ''')'''
'''~SWAP(''' ''r, g, b, a'' ''')'''
* ''r'', ''g'', ''b'', ''a'': each of these arguments may have a value equal to ''red'', ''green'', ''blue'' or ''alpha''. The RGBA channels of the original image will be exchanged accordingly (for example, <tt>~SWAP(blue,green,red)</tt> swaps the blue and red channels).

== TC: Team-Color Function ==
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

= Transformations =

== FL: Flip Function ==
May be used to flip an image horizontally and/or vertically.

'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizantally.
*if the argument list is empty, the image will only be flipped horizontally.

== ROTATE: Rotate Function ==
May be used to rotate an image by a multiple of 90 degrees.

'''~ROTATE(''' ''degrees'' ''')'''
* ''degrees'' - The number of degrees by which the image will be rotated. This must be a multiple of 90. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

== SCALE: Image-scaling function ==
Scales a graphic up or down.

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.

== SCALE_INTO function ==
{{DevFeature1.13|5}}

Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.

== SCALE_SHARP function ==

{{DevFeature1.13|0}}

Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

'''~SCALE_SHARP(200,300)'''

== SCALE_INTO_SHARP function ==
{{DevFeature1.13|5}}

Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear intorpolation.

== XBRZ function ==

{{DevFeature1.13|0}}

Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

'''~XBRZ(n)'''

= Cut-and-paste =

== BLIT: Blit Function ==
Blit the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)

'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. Must be greater or equal than zero. If missing assume (0,0).

== CROP: Crop Function ==
Extracts a rectangular section of an image file.

'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

== MASK: Mask Function ==
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.

'''~MASK(mask,x,y)'''
* ''mask'': an image file used as mask, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

= Opacity =

== ADJUST_ALPHA ==

{{DevFeature1.13|0}}

Scales the alpha value at each pixel down by a fixed factor. The argument is either a %, or an integer from 0 to 255, in which case it is divided by 255 and reinterpretted as a %.

'''~ADJUST_ALPHA(n)'''.

== O: Opacity modifying function ==
Changes an image's opacity at render time.

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

== PLOT_ALPHA ==

{{DevFeature1.13|0}}

At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

'''~PLOT_ALPHA()'''

== WIPE_ALPHA ==

{{DevFeature1.13|0}}

At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

'''~WIPE_ALPHA()'''

== Background coloring function ==
Sets the color of all the (semi-)transparent pixels of the image.

'''~BG(r,g,b)'''

= Miscellaneous =

== BL: Blurring function ==
Blurs a graphic at render time using the same algorithm used for in-game dialogs.

'''~BL( ''radius'' )'''

== DARKEN: Overlay function ==
{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-dark.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.

'''~DARKEN()'''

== BRIGHTEN: Overlay function ==
{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-bright.png) call instead.

Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.

'''~BRIGHTEN()'''

== NOP: Null function ==
Does nothing.

'''~NOP()'''

[[Category:WML Reference]]

ImagePathFunctions

2017-02-17T11:51:00Z

Zookeeper: Clarified ~LIGHTEN and ~DARKEN

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester'' from the 1.10 add-on server.

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like "units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)" would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.

= Changing the colors =

== BLEND: Color-blend function ==
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.

'''~BLEND(r,g,b,o)'''

The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.

== BW: Black and White Function ==
{{devfeature1.13|1}}
May be used to convert the image to pure black and white, without grey pixels.

'''~BW(threshold)'''
* ''threshold'': a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.

== CS: Color-shift function ==
Performs simple per-channel color shifts by adding the arguments to the respective color channels.

''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

== GS: Greyscale Function ==
May be used to greyscale the image (turn to black and white)

'''~GS( )'''

== L: Lightmap color-shift function ==
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.

'''~L(lightmap)'''

For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.

The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully gray image (RGB = 128,128,128) and any non-gray pixel will shift the colors of the original.

Note that the lightmap will be scaled to the same dimensions as the original image.

== NEG: Negative Function ==
{{devfeature1.13|0}}
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.

'''~NEG( )'''

Inverts the image, giving it an effect like a photographic negative.

{{devfeature1.13|1}} '''~NEG(''' ''threshold'' ''')'''

If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as ''solarization''.
Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

{{devfeature1.13|1}} '''~NEG(''' ''threshold_red, threshold_green, threshold_blue'' ''')'''

If a channel has a value greater than the corresponding threshold, the channel will be inverted.
Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.

== PAL: Palette-switch Function ==
May be used to change colors in an image following the specifications of a source and target (new) palette.

'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

== RC: Re-Color Function ==
May be used to change some colors in an image.

'''~RC(''' ''source color palette'' '''>''' ''color range ID'' ''')'''
*''source color palette'' - the first parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.
*''color range ID'' - this is the second parameter, signifying the ID of a color range defined in the file ''data/core/team-colors.cfg'' (or it may be a custom ID for a color range defined locally).

=== Example ===
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

== SEPIA: Sepia Function ==
{{devfeature1.13|0}}
May be used to give to the image a sepia tint (like in old pictures).

'''~SEPIA()'''

== SWAP: Channel Swap Function ==
{{devfeature1.13|1}}
May be used to swap the RGBA channels of an image.

'''~SWAP(''' ''r, g, b'' ''')'''
'''~SWAP(''' ''r, g, b, a'' ''')'''
* ''r'', ''g'', ''b'', ''a'': each of these arguments may have a value equal to ''red'', ''green'', ''blue'' or ''alpha''. The RGBA channels of the original image will be exchanged accordingly (for example, <tt>~SWAP(blue,green,red)</tt> swaps the blue and red channels).

== TC: Team-Color Function ==
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

= Transformations =

== FL: Flip Function ==
May be used to flip an image horizontally and/or vertically.

'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizantally.
*if the argument list is empty, the image will only be flipped horizontally.

== ROTATE: Rotate Function ==
May be used to rotate an image by a multiple of 90 degrees.

'''~ROTATE(''' ''degrees'' ''')'''
* ''degrees'' - The number of degrees by which the image will be rotated. This must be a multiple of 90. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.

== SCALE: Image-scaling function ==
Scales a graphic up or down.

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.

== SCALE_INTO function ==
{{DevFeature1.13|5}}

Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.

== SCALE_SHARP function ==

{{DevFeature1.13|0}}

Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)

'''~SCALE_SHARP(200,300)'''

== SCALE_INTO_SHARP function ==
{{DevFeature1.13|5}}

Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear intorpolation.

== XBRZ function ==

{{DevFeature1.13|0}}

Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.

'''~XBRZ(n)'''

= Cut-and-paste =

== BLIT: Blit Function ==
Blit the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)

'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. Must be greater or equal than zero. If missing assume (0,0).

== CROP: Crop Function ==
Extracts a rectangular section of an image file.

'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.

== MASK: Mask Function ==
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.

'''~MASK(mask,x,y)'''
* ''mask'': an image file used as mask, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).

Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image.

= Opacity =

== ADJUST_ALPHA ==

{{DevFeature1.13|0}}

Scales the alpha value at each pixel down by a fixed factor. The argument is either a %, or an integer from 0 to 255, in which case it is divided by 255 and reinterpretted as a %.

'''~ADJUST_ALPHA(n)'''.

== O: Opacity modifying function ==
Changes an image's opacity at render time.

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

== PLOT_ALPHA ==

{{DevFeature1.13|0}}

At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.

'''~PLOT_ALPHA()'''

== WIPE_ALPHA ==

{{DevFeature1.13|0}}

At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.

'''~WIPE_ALPHA()'''

== Background coloring function ==
Sets the color of all the (semi-)transparent pixels of the image.

'''~BG(r,g,b)'''

= Miscellaneous =

== BL: Blurring function ==
== DARKEN: Overlay function ==
Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.

'''~LIGHTEN()'''

'''~DARKEN()'''

== LIGHTEN: Overlay function ==
Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.

'''~LIGHTEN()'''

'''~DARKEN()'''

== NOP: Null function ==
Does nothing.

'''~NOP()'''

Blurs a graphic at render time using the same algorithm used for in-game dialogs.

'''~BL( ''radius'' )'''

[[Category:WML Reference]]

DirectActionsWML

2017-01-04T16:56:07Z

Zookeeper: Marked [modify_side] defeat_condition= as 1.13 only

{{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 percentage (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}}

=== [recall] ===
Recalls a unit taking into account any [http://wiki.wesnoth.org/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.
* '''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).

=== [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.
* '''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.

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 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.

=== [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. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
* '''variable''': the name of the variable.
* '''find_vacant''': 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''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".
* '''text''': (translatable) 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 to display the text in. 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.)
* '''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''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.
* '''animate''': (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.
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.
* '''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 add to the types the leader can recruit because of [side]recruit=.
* '''extra_recruit''': the types of units that the unit 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.
* '''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.
* '''extra_recruit''': the types of units that the side 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.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is having its recruitment set. 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.

=== [set_extra_recruit] ===
Sets the units a leader can 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''.
* '''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.
* '''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 [http://wiki.wesnoth.org/AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag [modify_ai]] instead, which always works.
* '''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
* '''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]]]).

=== [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 take any arguments.

=== [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''': if 'yes', displays the unit dying (fading away).
* '''fire_event''': 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. 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).

=== [move_unit] ===
works like the MOVE_UNIT macro.
* [[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.
* '''fire_event''' (optional, 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.
* '''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.

=== [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.
** '''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 to work around a bug when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP, SPECIAL_BACKSTAB, or any other effect that uses variable substitution or when using [effect][filter] with a $this_unit (see http://gna.org/bugs/index.php?18893).
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit.
* 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).

=== [transform_unit] ===
Transforms every unit 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.
* [[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.
* '''id''': (Optional) when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per scenario. In a campaign objects with the same id can be assigned once per scenario. For filtering objects, custom key can be used, such as item_id.
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} Enables the above behaviour. If set to no, the object ID is not used to prevent the object from being taken more than once, but can still be used to remove it using [remove_object].
* '''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 to work around a bug when adding ABILITY_TELEPORT (or any other effect that uses variable substitution) via an [object] or when using [object][effect][filter]with a $this_unit (see http://gna.org/bugs/index.php?18893). {{DevFeature1.13|5}} ABILITY_LEADERSHIP and SPECIAL_BACKSTAB now also use variable substitution and thus require this to be set to "yes".
* '''[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 level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
**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' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* '''[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 is tried 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)
* '''[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.
* '''no_write''': {{DevFeature1.13|1}} (bool, default no). If yes, the contents of [effect] will be applied to the relevant unit, but the [object] tag will not be written to unit.modifications. This renders duration= irrelevant. {{DevFeature1.13|6}} This is deprecated and will probably be removed in the release after 1.13.6. To get the same effect, use [effect] tags in [modify_unit].

=== [remove_object] ===

{{DevFeature1.13|6}}

Removes an object from matching units.

* [[StandardUnitFilter]]: All units matching the filter have matching objects removed
* '''object_id''': The id of the object to be removed.

=== [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_view=yes).

=== [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, recruitment, 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.

Due to a bug in 1.12 (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.syncronize_choice

=== [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, [[SyntaxWML#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.)

=== [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.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser 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.
* '''[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. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.
* '''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. Before 1.9 this is always "no".

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[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.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''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''
* [[TimeWML]]: the new schedule.
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. 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)
[time_area]
x=1-2,4-5
y=1-2,1-2
{UNDERGROUND}
[/time_area]

=== [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''': Content of a wesnoth map file. example:
map="{campaigns/Heir_To_The_Throne/maps/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.

=== [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).
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
* '''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.

(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]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it.

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 always be replay safe.

=== [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.

== 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 [http://www.wesnoth.org/macro-reference.xhtml 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]]

TerrainGraphicsWML

2016-12-23T14:34:08Z

Zookeeper: Documented [tile] no_draw=

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''x''','''y''': constrains the rule to given absolute map coordinates. Primarily useful to place map-specific features.
* '''mod_x''','''mod_y''': {{DevFeature1.13|1}} constrains the rule to absolute map coordinates which are multiples of the given values. For example, mod_x=4 would only match locations with an x coordinate of 4, 8, 12, 16, etc.
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches.
** '''name''': for animated terrain this takes the form of a comma separated list of images with durations specified after ':'. A square bracket expansion can also be used as in AnimationWML (see in example below).
** '''no_draw''' (default: no): {{DevFeature1.13|5}} whether to actually draw images of this rule onto this hex.
** '''set_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
**** '''has_flag''' {{DevFeature1.13|1}} comma-separated list of flags that the tile must have for this variant to apply.
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version.<br>For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne".<br>Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

To define an animated campfire at coordinates (4,5) with files "misc/fire-A01.png" to "misc/fire-A08.png" with an inter-frame transition time of 140, the following can be placed at the scenario top level (adapted from the CAMPFIRE macro):

[terrain_graphics]
x,y=4,5
[tile]
x=0
y=0
[image]
layer=0
name="misc/fire-A[01~08].png:140"
[/image]
[/tile]
[/terrain_graphics]

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

PreprocessorRef

2016-12-03T20:24:29Z

Zookeeper: Typo fixes (enddef -> endarg)

{{WML Tags}}
== Overview ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However the '''WML preprocessor''' allows to include more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).

== Preprocessor directives ==

The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the list of predefined core macros.

The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.

'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.

=== #define ===

'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''

All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. For example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:

<syntaxhighlight lang="wml">
#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor does not distinguish
## data into different types; only the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE} ## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2 ## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
</syntaxhighlight>

(See [[SingleUnitWML]] for further information on creating units using WML.)

'''Important note:''' Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at ''disguising'' WML bloat, but they do nothing to ''alleviate'' it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom [[EventWML|events]] and [[InternalActionsWML#.5Bfire_event.5D|fire_event]] tags. See also: [[Wml_optimisation]].

=== #arg {{DevFeature1.13|7}} ===

Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.

For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:

<syntaxhighlight lang="wml">
#define MESSAGE TEXT

#arg SPEAKER_ID
narrator
#endarg

#arg CAPTION
#endarg

#arg SOUND
#endarg

#arg IMG
#endarg

[message]
speaker={SPEAKER_ID}
message={TEXT}
caption={CAPTION}
sound={SOUND}
image={IMG}
[/message]
#enddef
</syntaxhighlight>

The caller of the macro can then decide which, if any, of the default values to override:
<syntaxhighlight lang="wml">
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}
{MESSAGE _"..."}
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}
</syntaxhighlight>

Note: as with #enddef, the final linebreak before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a linebreak in between.

=== #undef ===

'''Syntax:''' '''#undef ''symbol'' '''

Removes the previous definition of the macro named ''symbol''.

=== Inclusion directive {} ===

This directive can be used to include macros, single files or sets of files from a target directory.

==== File/directory inclusions ====

'''Syntax: {''path''}'''

Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.

The exact location in which the ''path'' will be resolved will depend on its prefix:

* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.

Information for locating the user data and game data directories can be found in [[EditingWesnoth]].

Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.

When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.

Some directories are handled in a special fashion according to their contents:

* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.

==== Macro inclusions ====

'''Syntax: {''symbol'' [''arguments''] [''optional arguments'']}'''

If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed '''after''' all normal arguments, however they can be specified in any order desired.

You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.

Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name '''and''' content:

<syntaxhighlight lang="wml">
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong
</syntaxhighlight>

Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:

<syntaxhighlight lang="wml">
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef
</syntaxhighlight>

=== #ifdef and #ifndef ===

Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).

'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''

If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available.

'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:

'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-stored'' [#else ''substitution-if-stored''] #endif'''

=== #ifhave and #ifnhave ===

'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''

Checks for the existence of a file. Uses the same relative paths as include directives (see below).

Example:

<syntaxhighlight lang="wml">
#ifhave ~add-ons/My_Addon/_main.cfg
{MY_ADDON_MACROS}
#endif
</syntaxhighlight>

'''#ifnhave''' does the opposite of '''#ifhave''':

'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''

=== #ifver and #ifnver ===

'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''

Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.

Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION >= 1.9.7+
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"
[/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
[/message]
#endif
#endif
</syntaxhighlight>

'''#ifnver''' does the opposite of '''#ifver''':

'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''

=== #error ===

'''Syntax:''' '''#error [''message'']'''

Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.

Please note that in spite of the example below, it is '''not''' advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#error This add-on does not support Wesnoth 1.11.10!
#endif
</syntaxhighlight>

=== #warning ===

'''Syntax:''' '''#warning [''message'']'''

Causes the WML preprocessor to emit a warning upon encountering the line. The message will '''only''' be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!
#endif
</syntaxhighlight>

== Built-in macros ==

The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.

* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
* '''MULTIPLAYER''': defined when in multiplayer mode.
* '''TUTORIAL''': defined when playing the tutorial campaign.
* '''EDITOR''': defined when running the built-in map editor.
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line).
* '''APPLE''': defined while processing the main game data when running on Mac OS X.
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.

== Command-line preprocessor ==

'''Syntax: --preprocess ''<source file/directory>'' ''<target directory>'' '''

Or the short form:

'''Syntax: -p ''<source file/directory>'' ''<target directory>'' '''

You can specify a list of predefined defines with:

'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''

comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.

The command will preprocess first the common config files in the main game ''data/'' directory, and afterwards the specified ones. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.

The resulted preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.

If by chance, the simple macro define doesn't suffice, you can use:

'''Syntax: --preprocess-input-macros <file>'''

To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.

There is also the possibility to export the preprocessed defines/macro list with:

'''Syntax: --preprocess-output-macros [<target file>]'''

This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.

If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the game's executable path.

Some examples:

* Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD

If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.

== See Also ==

* [[SyntaxWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

PreprocessorRef

2016-12-03T19:43:24Z

Zookeeper: Documented optional macro arguments

{{WML Tags}}
== Overview ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However the '''WML preprocessor''' allows to include more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).

== Preprocessor directives ==

The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the list of predefined core macros.

The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.

'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.

=== #define ===

'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''

All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. For example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:

<syntaxhighlight lang="wml">
#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor does not distinguish
## data into different types; only the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE} ## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2 ## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
</syntaxhighlight>

(See [[SingleUnitWML]] for further information on creating units using WML.)

'''Important note:''' Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at ''disguising'' WML bloat, but they do nothing to ''alleviate'' it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom [[EventWML|events]] and [[InternalActionsWML#.5Bfire_event.5D|fire_event]] tags. See also: [[Wml_optimisation]].

=== #arg {{DevFeature1.13|7}} ===

Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.

For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:

<syntaxhighlight lang="wml">
#define MESSAGE TEXT

#arg SPEAKER_ID
narrator
#enddef

#arg CAPTION
#enddef

#arg SOUND
#enddef

#arg IMG
#enddef

[message]
speaker={SPEAKER_ID}
message={TEXT}
caption={CAPTION}
sound={SOUND}
image={IMG}
[/message]
#enddef
</syntaxhighlight>

The caller of the macro can then decide which, if any, of the default values to override:
<syntaxhighlight lang="wml">
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}
{MESSAGE _"..."}
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}
</syntaxhighlight>

Note: as with #enddef, the final linebreak before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a linebreak in between.

=== #undef ===

'''Syntax:''' '''#undef ''symbol'' '''

Removes the previous definition of the macro named ''symbol''.

=== Inclusion directive {} ===

This directive can be used to include macros, single files or sets of files from a target directory.

==== File/directory inclusions ====

'''Syntax: {''path''}'''

Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.

The exact location in which the ''path'' will be resolved will depend on its prefix:

* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.

Information for locating the user data and game data directories can be found in [[EditingWesnoth]].

Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.

When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.

Some directories are handled in a special fashion according to their contents:

* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.

==== Macro inclusions ====

'''Syntax: {''symbol'' [''arguments''] [''optional arguments'']}'''

If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed '''after''' all normal arguments, however they can be specified in any order desired.

You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.

Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name '''and''' content:

<syntaxhighlight lang="wml">
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong
</syntaxhighlight>

Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:

<syntaxhighlight lang="wml">
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef
</syntaxhighlight>

=== #ifdef and #ifndef ===

Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).

'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''

If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available.

'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:

'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-stored'' [#else ''substitution-if-stored''] #endif'''

=== #ifhave and #ifnhave ===

'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''

Checks for the existence of a file. Uses the same relative paths as include directives (see below).

Example:

<syntaxhighlight lang="wml">
#ifhave ~add-ons/My_Addon/_main.cfg
{MY_ADDON_MACROS}
#endif
</syntaxhighlight>

'''#ifnhave''' does the opposite of '''#ifhave''':

'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''

=== #ifver and #ifnver ===

'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''

Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.

Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION >= 1.9.7+
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"
[/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
[/message]
#endif
#endif
</syntaxhighlight>

'''#ifnver''' does the opposite of '''#ifver''':

'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''

=== #error ===

'''Syntax:''' '''#error [''message'']'''

Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.

Please note that in spite of the example below, it is '''not''' advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#error This add-on does not support Wesnoth 1.11.10!
#endif
</syntaxhighlight>

=== #warning ===

'''Syntax:''' '''#warning [''message'']'''

Causes the WML preprocessor to emit a warning upon encountering the line. The message will '''only''' be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.

Example:
<syntaxhighlight lang="wml">
#ifver WESNOTH_VERSION < 1.11.10
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!
#endif
</syntaxhighlight>

== Built-in macros ==

The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.

* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
* '''MULTIPLAYER''': defined when in multiplayer mode.
* '''TUTORIAL''': defined when playing the tutorial campaign.
* '''EDITOR''': defined when running the built-in map editor.
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line).
* '''APPLE''': defined while processing the main game data when running on Mac OS X.
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.

== Command-line preprocessor ==

'''Syntax: --preprocess ''<source file/directory>'' ''<target directory>'' '''

Or the short form:

'''Syntax: -p ''<source file/directory>'' ''<target directory>'' '''

You can specify a list of predefined defines with:

'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''

comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.

The command will preprocess first the common config files in the main game ''data/'' directory, and afterwards the specified ones. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.

The resulted preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.

If by chance, the simple macro define doesn't suffice, you can use:

'''Syntax: --preprocess-input-macros <file>'''

To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.

There is also the possibility to export the preprocessed defines/macro list with:

'''Syntax: --preprocess-output-macros [<target file>]'''

This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.

If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the game's executable path.

Some examples:

* Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD

If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.

== See Also ==

* [[SyntaxWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

GameConfigWML

2016-10-20T19:59:24Z

Zookeeper: Typo fix

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

This tag is a top level WML tag which can only be used once because
it defines basic settings that are used everywhere in the game.
In official versions of Wesnoth it is in ''game_config.cfg''; values used there are labeled 'standard'.

The following keys are recognised
* '''base_income''': (standard 2) how much your leader earns without any villages
* '''village_income''': (standard 1) how much your leader earns for each village you control
* '''poison_amount''': (standard 8) the amount of damage poison deals to a unit
* '''rest_heal_amount''': (standard 2) how much HP a unit gains each turn it rests
* '''recall_cost''': (standard 20) how much it costs to recall a unit; this cost is independent of level.
* '''kill_experience''': (standard 8) killing a unit with ''level=X'' will give ''X''*''kill_experience'' experience to the killing unit. However, if a unit has ''level=0'', it will still give half of ''X'' experience.

* '''icon''': (standard 'wesnoth-icon.png') the game icon file
* '''title''': (standard 'misc/title.png') the title screen image
* '''logo''': (standard 'misc/logo.png') the wesnoth logo which will be put over the title image
* '''default_defeat_music''': (standard 'defeat.ogg,defeat2.ogg') default list of music tracks that are chosen to play on player's defeat; this can be overriden per-scenario
* '''default_victory_music''': (standard 'victory.ogg,victory2.ogg') default list of music tracks that are chosen to play on player's victory; this can be overriden per-scenario
* '''title_music''': (standard 'main_menu.ogg') the music to play at the title screen
* '''logo_x''': (standard 292) the x position of the logo on the title screen
* '''logo_y''': (standard 120) the y position of the logo on the title screen
* '''buttons_x''': (standard 760) the x position of the buttons on the title screen
* '''buttons_y''': (standard 330) the y position of the buttons on the title screen
* '''buttons_padding''': (standard 20) space between buttons, and border in main menu
* '''tip_x''': (standard 100) space between the button panel left edge and the tip-of-the-day panel right edge
* '''tip_y''': (standard 500) not used (the bottom right corner of the tip-of-the-day panel is pegged to align with the bottom of the button panel)
* '''tip_width''': (standard 495) max width in pixels of the tip-of-the-day panel. The width will actually adjust to be the smallest size necessary to fit the text. Once the max width is reached, if text must flow onto multiple lines, then the height will also automatically adjust.
* '''tip_padding''': (standard 20) space between the edge of the tip-of-the-day panel and an imaginary bounding box containing the text inside the panel

* '''map_image''': (standard 'maps/wesnoth.png') the background image for the "About" screen
* '''sidebar_image''': (standard 'misc/rightside.png') border of window when displaying unit statistics
* '''sidebar_image_bottom''': (standard 'misc/rightside-bottom.png') border of image when displaying unit statistics
* '''energy_image''': (standard 'misc/bar-energy.png') the images used to display hp/xp bars.
* '''moved_ball_image''': (standard 'misc/ball-moved.png') the orb image to add on top of the hp bar for player's moved units; see 'Orbs', [[WesnothManual]]
* '''unmoved_ball_image''': (standard 'misc/ball-unmoved.png') like '''moved_ball_image''', but for player's unmoved units
* '''partmoved_ball_image''': (standard 'misc/ball-partmoved.png') like '''moved_energy_image''', but for player's partially moved units
* '''flag_image''': (standard 'image/flag'terrain/flag-1.png:150,terrain/flag-2.png:150,terrain/flag-3.png:150,terrain/flag-4.png:150') the default flag animation to mark captured villages (if no custom flag is defined in the [side] tag). By example, this animation has 4 frames of 150ms each. An automatic side-coloring is applied.
* '''flag_icon_image''': (standard 'flags/flag-icon.png') the default flag icon to indicate the side playing in the statusbar (if no custom flag_icon is defined in the [side] tag). An automatic side-coloring is applied.
* ''' hp_bar_scaling ''': (standard '0.6') The ratio of hitpoints to height used for displaying the hp bar. Can be overwritten in [unit] and [unit_type].
* ''' xp_bar_scaling ''': (standard '0.5') The ratio of xp to height used for displaying the xp bar. Can be overwritten in [unit] and [unit_type].
* '''cross_image''': (standard 'misc/cross.png') the cross image displayed on the map at start of scenarios; see [[IntroWML]]
* '''dot_image''': (standard 'misc/dot.png') the dot image used to draw a path on the map before scenarios

* '''footprint_left_nw''', '''footprint_left_n''', '''footprint_right_nw''', '''footprint_right_n''': images used to display the path that a unit would take to the tile the cursor is on.
The first image of each key is used for tiles which would take only 1 movement point for the selected unit to move onto;
the second for ones which would take more.
The 'n' and 'nw' designations distinguish between tiles which are moved from orthogonally and diagonally in the same way as described in '''[missile_frame]''', [[AnimationWML]].
The 'left' and 'right' designations are used alternately throughout the path;
however, the standard values are the same for 'left' and 'right'.

* '''terrain_mask_image''': (standard 'terrain/alphamask.png') used to give a hex-shape from a rectangular image.
* '''grid_image''': (standard 'terrain/grid.png') the image used by the grid option
* '''unreachable_image''': (standard 'terrain/darken.png') the stripes mask used to show unreachable locations

* '''missile_n_image''': (standard 'projectiles/missile-n.png') orthogonal missile image to use if none is specified; see ''image'', '''[missile_frame]''', [[AnimationWML]]
* '''missile_ne_image''': (standard 'projectiles/missile-ne.png') diagonal missile image to use if none is specified; see ''image_diagonal'', '''[missile_frame]''', [[AnimationWML]]
* '''observer_image''': (standard 'misc/eye.png') the image to use for observer in multi-player games. (The eye in the upper right hand corner.)
* '''download_campaign_image''': (standard no image) the icon for the "Download more Campaigns" campaign menu option.

== See Also ==

* [[ReferenceWML]]

[[Category: WML Reference]]

SingleUnitWML

2016-10-20T19:59:08Z

Zookeeper: Typo fix

{{WML Tags}}
== How to describe a single unit ==

This tag, '''[unit]''', describes a single unit on the map, for example Konrad.
It is different from the [unit_type] in [units], which describes a class of units. However it takes many of the same keys and thus can generally override the inherited properties from the associated [unit_type].

[unit] can be used inside [side] ([[SideWML]]) for units present at start of the scenario, or as [[DirectActionsWML]] for units created during the game. (It is also used in save-files.)

The following keys are recognized:
* '''type''': the ID of the unit's unit type. See [[UnitTypeWML]].

* '''parent_type''': overrides '''type''' if this is present. This is likely of little use to WML authors; it is automatically generated when needed by the game (to keep track of some [unit_type][variation]s).

* '''side''': the side that the unit is on. It has to be an existing side, even if the unit is created in a variable.

* '''gender''': can be set to male or female to designate the gender of the unit. Default is male, but if the unit has only a female variant it will be female.

* '''x''', '''y''': the location of the unit. By default ( see '''placement''') if a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list.

* '''placement''': How the unit should be placed: can be one value or a comma-separated list of values. Default value is 'map,leader' for a leader given directly in [side], "" otherwise. By default, 'map,recall' is implicitly appended to the end of the list.
** '''map''': If x,y are explicitly given and point to a valid on-map location - try to place the unit at the nearest free location to there, never overwriting existing units. Successful if x,y are given and a valid on-map vacant location near it can be found.
** '''leader''': Try to place unit near the leader, if leader is not present or is in recall list - try to place unit near the start location for this side. Successful if a valid on-map vacant location can be found near leader or near start location.
** '''recall''': Place unit on recall list. Always successful.
** '''map_overwrite''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location, if there was a unit there - overwriting it, without firing events.
** '''map_passable''': If x,y are explicitly given and point to a valid on-map location - try to place unit at this location; if the hex is of an impassable terrain for the unit being placed, or is already occupied by another unit, the new unit will be placed in the nearest vacant hex.
** '''leader_passable''': Similar to "leader", with the additional restriction that the selected location is not impassable for the unit being placed.

* '''to_variable''': creates the unit into the given variable instead of placing it on the map.

* '''id''': a unique identifier for the unit. This is (usually) not displayed to the player, but is to be used only for identifying and filtering units. If not specified or when a unit is normally recruited, a random one will be generated for the unit to ensure that each unit has a unique ''id'' attribute. In older versions, the '''description''' attribute specified a unique ID. (The one instance when an id is displayed to the player is when the leader's id is used as the default for a [[SideWML|side]]'s '''current_player''' attribute.)

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this.

* '''generate_name''': (default=yes) will generate a new name if there isn't one specifed for the unit, as if the unit were a freshly-recruited one

* '''unrenamable''': if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).

* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.

* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give a unit less traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.

* '''random_gender''': "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.

* '''canrecruit''': a special key for leaders.
** '''no''': default. Unit cannot recruit.
** '''yes''': unit can recruit.
: Normally when a team controls no units with '''canrecruit=yes''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=yes'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with '''canrecruit=yes''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.
: More than one unit with '''canrecruit=yes''' for the same side (see [[SideWML]]) are allowed in single player, if the side is human-controlled.

* '''extra_recruit''': a list of unit types which this unit can recruit in addition to the ones given by its [side]recruit=, only working for units with '''canrecruit=yes'''.

* '''variation''': the variation of itself the unit should be created as.

* '''upkeep''': the amount of upkeep the unit costs.
** '''loyal''': no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
** '''free''': synonymous with "loyal".
** '''full''': unit costs ''level'' upkeep (see [[UnitTypeWML]]).
** An integer can be used to set the upkeep cost to that number.
** The default is "full".
** Leaders (units with '''canrecruit=yes''') never pay upkeep no matter what upkeep is set to.
** Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.

* {{DevFeature1.13|0}} '''recall_cost''': the recall cost of this unit. Overrides the values specified by the unit's type ([[UnitTypeWML|[unit_type]]]), its side ([[SideWML|[side]]]), and the global [[GameConfigWML|[game_config]]] value. A value of -1 is equivalent to not specifying this attribute.

* '''overlays''': a list of images that are overlayed on the unit.

* '''goto_x''':, '''goto_y''': UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.

* '''hitpoints''': the HP of the unit. Default is the max HP for ''type''.

* {{DevFeature1.13|6}} '''invulnerable''': a shorthand to set the ''invulnerable'' status.

* '''hp_bar_scaling''': Overwrites the attribute in ([[GameConfigWML]]).

* '''experience''': the XP of the unit. Default is 0.

* '''moves''': number of movement points the unit has left. Default is the movement for its unit type.
: '''Note:''' Do not assume that moves=max_moves on turns when a unit doesn't move. The wesnoth AIs sometimes manipulate the moves variable during its turn, for internal reasons.

* '''attacks_left''': number of attacks the unit has left. Default is equal to the attacks key for its unit type, that usually is 1 (see ''max_attacks'' below).

* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.

* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).

* '''ai_special''': causes the unit to act differently
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as '''[status] guardian = 'yes''''.

* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Using '''sw''' is preferred for a "reversed" facing (looking to the left) and '''se''' for a normal (looking to the right) facing.

* '''profile''': sets a portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type. See [[UnitTypeWML]] for the rules used for locating files.
** "unit_image" if given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).

* '''small_profile''': sets a small portrait image for this unit. See the '''profile''' attribute above for advancement and special values. As with [[UnitTypeWML]], the location heuristic of the '''profile''' attribute is disabled when the '''small_profile''' attribute is provided.

* '''max_attacks''': Default is 1. The number of attacks the unit can have per turn.

* '''max_experience''': The experience the unit needs to advance. If left out, this information will be taken from the unit's file.

* '''max_hitpoints''': The maximum hitpoints the unit has. If left out, this information will be taken from the unit's file.

* '''max_moves''': The maximum moves the unit has. If left out, this information will be taken from the unit's file.

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'no', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The Status Table displays the status of each unit using the three images '''misc/poisoned.png''', '''misc/slowed.png''' and '''misc/petrified.png'''; other keys do not appear in the Status Table.
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, ''slowed'' is set to 'no'.
** '''petrified''': if 'yes', the unit cannot move, attack, or be attacked.
** '''uncovered''': if 'yes', the unit has performed an action (e.g. attacking) that causes it to no longer be hidden until the next turn.
** '''guardian''': if 'yes', the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it). Does the same as '''ai_special = "guardian"'''.
** '''unhealable''': if set to 'yes', the unit cannot be healed.
** {{DevFeature1.13|6}} '''invulnerable''': if 'yes', attacks can't hit the unit.
** One can add other keys to [status], but they must have boolean values. For example, a scenario can set unit.status.''my_custom_key'' to 'yes' or 'no'.

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

* '''[modifications]''' changes that have been made to the unit.
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].
** '''[advance]''' an advancement the unit has. Same format as [advancement], [[UnitTypeWML]]. Might be used if the unit type has some advancements, but this particular one is supposed to have some of them already taken. {{DevFeature1.13|2}} In 1.13.2 and later this has been renamed to [advancement], to match the UnitTypeWML tag of the same name.

* '''[filter_recall]''' A leader can only recall those units which pass the SUF.
**'''[[StandardUnitFilter]]''' tags and keys

* '''unit_description''': overrides the unit type description for this unit. You will probably want to set up a ''post_advance'' [[EventWML|event]] to override the default description after promotions. Or better, use an object with a profile [[EffectWML|effect(s)]] to filter on unit type and change the unit description and/or portrait.

* '''[event]''' The event is copied from this unit's wml description into the scenario. The event is carried along with the unit (it can advance etc) and inserted into every scenario where this unit is first created. A [unit][event] requires a non-empty id= attribute.

* '''[ai]''' This affects how the computer will control this unit (currently only used by [[FormulaAI]]).
** '''formula''': if set, the unit will execute this code during the "unit_formulas" stage, assuming that the "unit_formulas" stage has been enabled for this side
** '''priority''', '''loop_formula''', '''[vars]''': see the [[FormulaAI]] documentation for details

== See Also ==

* [[UnitTypeWML]]
* [[InternalActionsWMLUnitTags]]
* [[ReferenceWML]]

[[Category:WML Reference]]

MapLocalization

2016-10-15T16:39:08Z

Zookeeper: Added clear mention of font used, and a few other minor additions

'''This page is a work in progress'''

Like the old maps, the new-style maps can be localized, but the intended method for doing so is quite different.

=== Overview ===

However, the workflow for localizing a map is simple: you create an image which contains the localized labels on a transparent background as simple text, no post-processing effects needed. In GIMP, you then add that image to a corresponding .xcf file as a new layer, and run a script. The script creates an overlay image which covers up the english labels, adds your localized labels and applies a bunch of post-processing effects to them in order to make them look identical to the english labels. All you need to do is to check the output and save.

=== Step-by-step instructions ===

==== Preparations ====

1. If you don't have GIMP, install it.

2. Download the [https://github.com/wesnoth/resources/tree/master/image-localization/maps/wesnoth-map-localization.scm wesnoth-map-localization.scm script] and place it into a script directory recognized by GIMP. You can view and configure the script directories in GIMP's preferences (Preferences -> Folders -> Scripts). If you already have GIMP running, you need to use '''Filters -> Script-Fu -> Refresh Scripts''' to make it recognize the newly added script. In the Filters menu, you should now see a filter category called "Wesnoth", and inside it "Map Localization". However, we don't need it yet.

3. Download the [https://github.com/wesnoth/resources/tree/master/image-localization/maps/ localization.xcf for the map you're localizing].

Now you're all set to begin.

==== Localization ====

# Open the localization.xcf you've downloaded. It contains a bunch of layers needed by the localization script, but at this point all you need is the layer called "label placement guide". It's a version of the map without any perspective or displacement effects added, and it is the one onto which you need to place the localized layers.
# Create a new layer which includes the localized labels, positioning them using the aforementioned layer as a guide. The positions or orientation or curving of the labels does not need to match the english labels in any way. Place them in a way which you think looks good.<br>The requirements for the labels are simple: black text should be pure black, whereas yellow labels on forests should have the RGB value 185,155,85. The script gives you a little bit of leeway so you don't have to stress over very small color deviations, but don't do it intentionally. Background should be transparent.<br>''Note that you can use whatever graphics application you want in creating your labels, as long as you can import the result into GIMP so that it meets the above requirements.''<br>
# Add the layer containing your localized text into the same localization.xcf file and name it "labels". Don't mess with the other layers.
# If ''labels'' and ''label placement guide'' are layer groups, merge them down to single layers. Notice as well that the expected layer names are case-sensitive, so for example ''Labels'' will not work.
# Run the script by choosing Filters -> Wesnoth -> Map Localization. The script will create a new image, and produce the output there. This will take a moment, perhaps as much as a minute or more on a slow computer, and for a few seconds it might seem like nothing is happening.
# You should now have a new image with a single layer called "localized overlay". Inspect that everything's ok by adding the original english map as a new layer underneath the overlay; the english labels should be covered up, the localized labels in place and there should be no glitches anywhere. Export the image to PNG (just remember to hide/delete the english map layer first!) and you're done. In the PNG export dialog, uncheck the option "Save color values from transparent pixels" to get the file of expected size (~100-300 KiB; if the option is not unchecked, it is over 2 MiB).

===== Final notes =====

If there are labels which you don't need to localize, then first of all, don't bother including them among your localized labels. Then, once you've generated the final overlay, simply erase the parts which cover up the original english label.

The localized overlay may end up having some small artifacts along the parchment edges; you can simply erase them if you want.

===== Font and text sizing =====

These are the font and text sizing conventions that have been used on the english maps. Depending on your language, you may want to or need to break some of them.

The font used is Monotype Corsiva.

Major geographical features or other large areas which extend beyond the map edges (including forests): 28px small caps, tracking ~200.
''Note that these are font sizes for Photoshop. GIMP has slightly different text tools and does not have small caps effect. Small caps effect can be reproduced by using caps with 30px for the first letter and 20px bold for the remaining letters. You might also need to make all text bold in Gimp so it will be legible. The corresponding font tracking in GIMP is 5.0.''

Large geographical features: 22px normal or small caps.

Minor geographical features: 18px normal.

Major rivers: 20px, tracking ~200.

Small rivers: 18px, tracking ~200. For names like "R. Weldyn", note that periods are very small in Monotype Corsiva and get very close to the preceding R; I suggest giving the . a size of 24-30px and removing the following space. Other solutions can work too.

Capital cities: 24px normal.

Other major cities: 20px normal.

Small cities: 16px normal. You might need to increase this to 18px for legibility.

Large forests: 24px normal.

Small forests: 18px normal.

===== Text orientation and curving =====

In the english maps, names of large geographical areas and rivers are often curved. River names usually follow the shape of the river, and names of large features such as "Heart Mountains" are curved to roughly match the shape of said feature.

All of the above is optional. You do not need to match the english labels in shape and location. If for some reason you need to, you can even omit some labels or add completely new ones.

==== Duplicate maps ====

The title screen map is identical with the ''Heir to the Throne'' campaign map. Localize the map for ''Heir to the Throne'', create a copy of the overlay and rename it to 'titlescreen--overlay.png', then place it in ''\data\core\images\maps\l10n\<language iso code>'' and you're done.

The same applies to several other maps:

{|
! Copy !! Source
|-
| ''titlescreen'' || ''Heir to the Throne''
|-
| ''A Tale of Two Brothers'' || ''Liberty''
|-
| ''Northern Rebirth'' || ''An Orcish Incursion''
|-
| ''The Hammer of Thursagan'' || ''The Sceptre of Fire''
|}

[[Category:Translations]]

Timeline of Wesnoth

2016-10-15T09:06:05Z

Zookeeper: Removed Gweddry's birth date guess, as he's clearly older than that

This is a chronological history of the country of Wesnoth and surrounding regions, gleaned from written accounts and verbal histories passed down through the generations. Portions of entries surrounded by parentheses and containing a question mark are assumed or unconfirmed information. The history is sorted by era, and within the era by date, using the Foundation of Wesnoth as a base. BW=Before Wesnoth, YW=Years Wesnoth. They function the same way as BC and AD do in our timekeeping system. Each of the eras is summarized before the timeline for that era begins. This history of the Great Continent is a subject of active scholarship.

The world that Wesnoth resides in is called Irdya. Before the Fall and the (unchronicled) technological age, this name is only rarely used.

'''Spoiler warning!'''
This page contains plot spoilers to several campaigns.

__NOTOC__
[[#Prehistory - 20 YW: The Founding of Wesnoth|The Founding of Wesnoth]]

[[#20-130 YW: The Taming of the Wild|The Taming of the Wild]]

[[#200-350 YW: The Golden Age of Wesnoth|The Golden Age of Wesnoth]]

[[#350-417 YW: The First Dark Age of Wesnoth|The First Dark Age of Wesnoth]]

[[#417-530 YW: The Turmoil of Asheviere|The Turmoil of Asheviere]]

[[#530-630 YW: The Age of Fear|The Age of Fear]]

[[#628-673 YW: The Silver Age of Wesnoth|The Silver Age of Wesnoth]]

[[#761-816 YW: The Legacy of Black-Eye Karun|The Legacy of Black-Eye Karun]]

[[#After the Fall|After the Fall]]

== Prehistory - 20 YW: The Founding of Wesnoth ==
During the age of the Founding of Wesnoth, there were two important geographic locations, these being the Green Isle and the Great Continent. Haldric is the main historical figure at this time. This age ends with the founding of Wesnoth as a country in the Great Continent, and with Orcs attacking both elves and men from the sea.

=== Prehistory ===
* Elves and Dwarves inhabit the Great Continent.
* Humans inhabit the distant West.
* Haldric's people colonise the [http://wiki.wesnoth.org/Geography_of_Wesnoth#The_Green_Isle Green Isle] from a continent further to the west.

=== 200 BW ===
* The Lich-Lords arrive on the Green Isle after losing a war in the distant West.
* After a long war Haldric's people come to dominate the Green Isle.
* The 'Wesfolk' and their Lich-Lords are pushed onto marginal lands.

=== 12 BW ===
* The Crown Prince of Southbay discovers the Great Continent.

=== 11-7 BW ===
* The Crown Prince makes several voyages between the Green Isle and the Great Continent.

=== 6 BW ===
* Following these voyages to the Great Continent, the elder Crown Prince falls ill and dies.
* His younger brother is implicated in a plot to kill him.
* As a distraction the younger Prince starts a war with the Wesfolk and their Lich-Lords.
* The Lich-Lords sense they will be destroyed and open gates to the homeland of the Orcs in the West.

=== 5-2 BW ===
* The Green Isle is overrun with Orcs.
* The Wesfolk desert their Lich-Lords as they fear becoming prey for the Orcs.
* [http://wiki.wesnoth.org/CharactersStorys#Prince_HaldricPrince Haldric] leads the evacuation of the survivors to the Great Continent. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Rise_of_Wesnoth '''The Rise of Wesnoth'''] begins.

=== 1 BW ===
* Human settlers, led by Prince Haldric, arrive at the western coast of the Great Continent (the landfall occurs in the future Bay of Pearls) in large numbers.
* Humans arrive in the middle of a simmering dispute between the Elves and Dwarves.
* The Elves and Dwarves are distrustful of humans, and there is a small skirmish.
* Messengers from Wesmere Forest come and ask Haldric to come before the Ka'lian.
* Prince Haldric asks the Four Elvish Lords ([http://wiki.wesnoth.org/CharactersStorys#Lady_Dionli Dionli], [http://wiki.wesnoth.org/CharactersStorys#Lord_Logalmier Logalmier], Aryad, and El'Isomithir) for help and land.
* They set before him four quests to prove his worth, which he completes.

=== 1 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Prince_Haldric Haldric] is granted the plains north and south of the Great River.
* Haldric agrees to a Pact of Mutual Defence with the Elves, but the Ka'lian decides it will betray him and allow humans and orcs to exhaust each other in war if the opportunity presents. Haldric, learning of this, considers the Pact a dead letter.
* The Ruby of Fire is temporarily hidden, and the [http://wiki.wesnoth.org/CharactersStorys#Lich-Lord_Jevyan lich-lord Jevyan] is deceived into believing it is held by the Elves.
* Haldric founds the country of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth Wesnoth] in the central plain south of the great River.
* Reign of Haldric I (formerly prince Haldric) begins. [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth '''The Rise of Wesnoth'''] ends.

=== 2 YW ===
* Orcs, following the ships fleeing from the Green Isle, begin to arrive on the Great Continent.
* These Orcs are defeated by Haldric's forces.
* Some of the Orcish survivors flee back to the Green Isle, others move to attack the Elves.
* King Haldric helps the Elves fight the surviving Orcs.

=== 8 YW ===
* A second wave of Orcs arrive from the Green Isle; these Orcs begin claiming large portions of the northern Great Continent for themselves.
* [http://wiki.wesnoth.org/CharactersStorys#Erlornas Erlornas] of Wesmere is involved in the first direct elvish clash with orcs ([http://wiki.wesnoth.org/Mainline_Campaigns#An_Orcish_Incursion '''An Orcish Incursion'''] takes place in 8-9YW).
* Haldric I publicly repudiates the Pact he spoke with the Elves, refusing to give aid.

=== 9-11 YW ===
* Many Elves are killed in battle by the Orcs.
* Elvish emissaries are turned away from Wesnoth.

=== 12 YW ===
* Orcs fail to take the Wesmere Forest and instead march down the coast, devastating human settlements there.
* Elves refuse to aid the Humans in confronting the Orcs.
* Human refugees from the coastal settlements relocate in what will become known as the Great Central Plain. Dan'Tonk, which will become Wesnoth's largest city, is founded.

=== 20 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Prince_Haldric Haldric I] dies.
* [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] ascends to the throne.
* [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] and [http://wiki.wesnoth.org/CharactersStorys#Landar Landar] escape an orcish invasion of their home in Lintanir Forest. [http://wiki.wesnoth.org/Mainline_Campaigns#Legend_of_Wesmere '''The Legend of Wesmere'''] begins.
* Humans and elves decisively defeat the orcs at Tath, thus halting the orcish advance.
* A new treaty between humans and elves is signed and King Haldric II allows emissaries of the Elves to return to Wesnoth.
* Elves inform [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] of the danger posed by the unshielded Ruby of Fire.
* [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] and [http://wiki.wesnoth.org/CharactersStorys#Landar Landar], later to become successive High Lords of the Elves, are able to sneak into an orcish camp by stealth and assassinate the Great Chief Brurbar. A long orcish civil war for succession follows. The orcs are unable to undertake action against any other race during this period and Wesnoth enjoys a long period during which it can expand with little opposition.

== 20-130 YW: The Taming of the Wild ==
This era is that in which the kingdom of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth Wesnoth] expanded and defined its borders, and settled the area which it had claimed for its own. The Taming of the Wild refers to the settling of the unsettled lands, as well as to the colonization of the Northlands. The end of this era is marked by friction between the city-state of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Elensefar Elensefar] and the country of Wesnoth, which will continue for the next several hundred years.

=== 21 YW ===
* Founding of the Great Academy on Alduin.

* [http://wiki.wesnoth.org/CharactersStorys#Kalenz Kalenz] is relieved of command by the Ka'lian. He retires to Lintanir Forest with [http://wiki.wesnoth.org/CharactersStorys#Cleodil Cleodil]. A faction of xenophobic elves begins to gather around [http://wiki.wesnoth.org/CharactersStorys#Landar Landar].

=== 25-40 YW ===
* In 25 YW [http://wiki.wesnoth.org/CharactersStorys#Haldric_II Haldric II] sends an expedition to retrieve the Ruby of Fire from its place of concealment.
* Haldric II commissions a Dwarven tribe to build the Scepter of Fire with the Ruby of Fire as its centerpiece; Elves associated with [http://wiki.wesnoth.org/CharactersStorys#Landar Landar's] faction attack during the transfer. [http://wiki.wesnoth.org/Mainline_Campaigns#Sceptre_of_Fire '''Scepter of Fire'''] begins.
* Action of '''The Scepter of Fire''' takes place. Haldric II is informed that the Scepter was both completed and lost in the year 40. It will not be recovered for nearly 500 years.
* With the death of [http://wiki.wesnoth.org/CharactersStorys#Thursagan Thursagan], the Runemaster, all runemasters are killed and runesmithing is lost for several centuries.

=== 26-50 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Landar Landar] declares himself High Lord of the Elves, leading to civil war.

=== 51 YW ===
* Wesnothian New Writing (the script later called "steel-hand", to distinguish it from the more complex "brush-hand" cursive brought from the [http://wiki.wesnoth.org/Geography_of_Wesnoth#The_Green_Isle Green Isle]) is promulgated by royal decree. From this date all royal documents and public inscriptions are in New Writing. It spreads rapidly via the mercantile class. The older brush-hand writing continues to be used for magical purposes, scholarship, and in certain elevated literary forms.

=== 50-93 YW ===
* Elvish civil war (and [http://wiki.wesnoth.org/Mainline_Campaigns#Legend_of_Wesmere '''The Legend of Wesmere''']) ends. [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz] declared High Lord, begins reorganizing and militarizing Elvish society to fight the orcs. In late 93 YW he cedes control to a reconstituted Ka'lian and retires again to the Forest of Lintanir.

=== 121 YW ===
* Orcish civil war sputters to a halt. Raids on elves and humans resume. Period of uncontested human expansion ends, but the [http://wiki.wesnoth.org/Geography_of_Wesnoth#Wesnoth Wesnothian] Army is more than equal to any of its opponents in battle.

=== 122 YW ===
* City of [http://wiki.wesnoth.org/Geography_of_Wesnoth#Elensefar Elensefar] is sacked by orcs.
* Meneldur, a sailor of Elensefar, sets out on a quest to regain the city. UMC '''Saving Elensefar''' begins.

=== 123 YW ===
* Elensefar is retaken by Meneldur along with Undead from the Green Isle.
* Elensefar becomes an independent city-state for the first time. UMC '''Saving Elensefar''' ends.

=== 161-164 YW ===
* The newly crowned king sought to make safe once and for all the wildlands that separated the human cities surrounding Weldyn and the coastal regions of Elensefar.
* The grand army of Wesnoth, personally led by the High Council of Archmagi, destroyed all enemies residing within Wesnoth.
* The city-state of Elensefar is formally united to the kingdom. Settlements from it spread north of the river into the new frontier province of Annuvin, carefully avoiding the margins of Wesmere Forest.

=== 164-176 YW ===
* During this twelve year span, the western fortress of Halstead was erected in the very heart of the western wilderlands.

=== 199 YW ===
* Emboldened by the far-reaching arm of Halstead's protection, settlement in the west explodes
* The settlements of Aldril and Carcyn grow to become major cities, the first as an important port due to its position on the Bay of Pearls, and the second as a stop on the road to Elensefar and military outpost along the Great River
* Settlers from Carcyn cross the Great River to establish the first settlements north of it and east of Wesmere.

== 200-350 YW: The Golden Age of Wesnoth ==
The Golden Age of Wesnoth was the time of the great kings, and of peace and prosperity within the kingdom. The Orcs had suffered a grave defeat at the hands of Wesnoth and Elensefar seventy-five years earlier, so they did not pose much of a threat, and whenever they did attack they were quickly defeated. This allowed the army to lessen in size, and the kings of this age to undertake the great public works they are renowned for. The era ends when the king of Wesnoth dies without an heir, and a new dynasty begins.

=== 251 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Cleodil Cleodil], wife of [http://wiki.wesnoth.org/CharactersStorys#Kalenz_2 Kalenz], dies.

=== 350 YW ===
* Disintegration of the Kingdom follows the death of Haldric IV.
* [http://wiki.wesnoth.org/Geography_of_Wesnoth#Elensefar Elensefar] remains a province of Wesnoth but exerts increasing independence due to isolation.
* Treaty between lord of Elensefar and king of Wesnoth signed.

== 350-417 YW: The First Dark Age of Wesnoth ==
The first Dark Age was a time of strife and invasion. When Haldric IV died, he left Wesnoth without a king, and the next 70 years were marked by short-lived dynasties, attacks by ever more aggressive orcs, and the further separation of Wesnoth and Elensefar. The Dark Age ended when Garard I took the throne, and began a new dynasty that would last for several hundred years.

=== 360 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Malin_Keshar Malin Keshar] born in Parthyn.

=== 363 YW ===
* Last of [http://wiki.wesnoth.org/CharactersStorys#Kalenz Kalenz's] children dies. Kalenz, condemned to outlive his offspring by the potion of Crelanu, leaves the Forest of Lintanir and begins wandering the Great Continent.

* Village of Maghre terrorized by a minor necromancer. Action of [http://wiki.wesnoth.org/Mainline_Campaigns#A_Tale_Of_Two_Brothers '''A Tale of Two Brothers'''] takes place.

=== 389 YW ===
* Garard, a future king of Wesnoth, is born.
* [http://wiki.wesnoth.org/CharactersStorys#Malin_Keshar Malin Keshar] returns to Parthyn from the Academy at Alduin. [http://wiki.wesnoth.org/Mainline_Campaigns#Descent_into_Darkness '''Descent Into Darkness'''] begins.

== 417-530 YW: The Turmoil of Asheviere ==
King Garard's dynasty was long-lived and productive, but it was also punctuated by significant turmoil: the end of the first king's reign was marred by orcish and undead raids, and the second was murdered by his own wife and son. It was not until 517 YW that the usurpation of the throne by Queen Mother Asheviere was ended.

=== 417 YW ===
* Ending years of strife and division, Garard I seizes the throne and becomes king of Wesnoth, beginning the [[Garardine Dynasty]].

=== 440 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Garard_II Crown Prince Garard II] is born.

=== 442 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Delfador Delfador], later called "the Great", is born.

=== 450 YW ===
* Prince Arand is born.

=== 468 YW ===
* Zorlan becomes Great Chief of the northern orcs
* [http://wiki.wesnoth.org/CharactersStorys#Delfador Delfador] graduates from the Great Academy. [http://wiki.wesnoth.org/Mainline_Campaigns#Delfador.27s_Memoirs '''Delfador's Memoirs'''] begins.

=== 470 YW ===
* Garard I dies; [http://wiki.wesnoth.org/CharactersStorys#Garard_II Garard II] ascends to the throne of Wesnoth
* Orcs under Great Chief Zorlan and undead raised by the necromancer [http://wiki.wesnoth.org/CharactersStorys#Iliah-Malal Iliah-Malal] raid Wesnoth's borders. All but the first and the last three scenarios of [http://wiki.wesnoth.org/Mainline_Campaigns#Delfador.27s_Memoirs'''Delfador's Memoirs''' ] take place in this year.
* Control of the Estmarks is effectively lost during this war, not to be regained for decades. Outposts are built on the near side of the Weldyn to repel orc raids. The long watch of the River Guard begins.

=== 478 YW ===
* Garard II marries Asheviere.
* Garard issues the Edict of the Scepter, providing that the crown shall settle after his death on whichever member of the royal family successfully retrieves it from the Caverns of Flame.

=== 480 YW ===
* Crown Prince Eldred is born.

=== 483 YW ===
* Erain and Ethyn, identical twins and brothers of Eldred, are born.

=== 498 YW ===
* Princess Li'sar is born.

=== 500 YW ===
* Prince Konrad is born, the youngest of several sons of Prince Arand.
* Wesnoth and the orcs of the north go to war.

=== 501 YW ===

===== Betrayal on the battlefield =====
* Garard leads his army to orc encampment at Galcadar by the Ford of Abez.
* Garard's forces split into two groups, one led by himself and the other by his son Eldred.
* Eldred betrays his father and attacks him with the troops under his control.
* Eldred slays King Garard and his uncle Prince Arand on the battlefield of Abez.

===== Reprisal =====
* Delfador escapes the battle and heads to Weldyn.
* Eldred gives tribute to the Orcish king, who stops his attacks.
* Delfador gathers a force of Loyalists to avenge Garard's Death.
* Eldred's forces confront Delfador's Loyalists at Weldyn.
* The Loyalists are defeated, but Eldred is slain by Delfador in the fight.

===== Asheviere seizes power =====
* Asheviere orders the slaughter of Garard's nephews and declares herself Queen of Wesnoth.
* Hearing of the news Delfador infiltrates the palace.
* Delfador finds the youngest prince Konrad as he is slain.
* Delfador flees, taking Konrad's body for burial to the land of the Elves.
* While traveling through Wesnoth, Elf Lady Parandra finds an orphaned human child.
* Parandra and Delfador agree to give the orphan the identity of Prince Konrad.
* Delfador and Konrad flee to live in refuge with the Wood Elves of the great southwestern forest.

===== The country resists Asheviere =====
* Elensefar refuses to submit to Asheviere and declares itself an independent city-state.
* After several defeats, Wesnoth's army retreats from the remote areas of the kingdom. The western Wesnothian border recedes, is fixed, and remains heavily defended.
* As a result of the loyalist withdrawal, several small human communities on the west coast of the Great Continent live in relative independence while elves flourish in the great forest to the southwest of Wesnoth.
* A band of Wesnoth citizens organizes resistance to Asheviere's siezure of power. They are eventually forced to abandon their home and settle in the Three Sisters ('''Liberty''').

=== 502-517 YW ===
* Delfador raises Konrad under the protection of the Elves.

=== 517 YW ===
* Asheviere hires Orcish forces to hunt down her nephew-in-law Konrad.
* Orcish forces converge on Delfador's refuge.
* Konrad flees his home with the elves and embark upon a quest to regain the throne of Wesnoth. '''Heir To The Throne''' begins.

=== 518 YW ===
* Konrad crosses the Great River into the Northlands on a search for the Sceptre of Fire.
* They enter the Caves of Knalga, allied with Princess Li'sar, and find it.
* They return to Wesnoth and claim the throne. '''Heir to the Throne''' ends.

=== 522 YW ===
* Birth of Princess Ana'sar.

=== 530 YW ===
* Wesnothian colonists begin reclaiming the Estmarks.

=== 544 YW ===
* With both sides of the lower Weldyn River again civilized territory, the River Guard posts south of Soradoc are abandoned. Wesnothian military activity shifts eastward into the Estmarks.

== 530-630 YW: The Age of Fear ==
The Age of Fear takes its names from the events of the end of the era. On the surface, the first 77 years were very uneventful for the kingdom of Wesnoth. However, during this time unexplainable magical events took place, especially in the eastern lands. Previously tamed lands were slowly claimed by wilderness as fear and paranoia gradually overshadowed the spirit of pioneering and adventure displayed earlier in Wesnoth's history. In the last 10 years of the age, Wesnoth bore the brunt of the most powerful Undead attack ever and was nearly destroyed. By the end of the era, most of Wesnoth had been made barren, most of the great buildings inside and outside of Weldyn were razed, and the population of Wesnoth was half of what it had been.

It was in this era that certain areas of the chaotic Northlands were for the first time put into any kind of law and order. A small group of humans and dwarves, accepting anyone of any race who wished to join, formed themselves into the "Northern Alliance”, with the vision of making the Northlands safe to live in. Over time, this alliance grew slowly but steadily in power. By the end of the era, the alliance had succeeded in making a few small areas, including Knalga and the surrounding regions, stable and prosperous. Consequently, many people evacuated from the wasteland that most of Wesnoth had become and moved north - depleting the population of Wesnoth still further.

=== 533 YW ===
* Delfador succumbs to old age and dies, his body is entombed alongside his staff in Eregonor.
* The next great sage of Wesnoth, [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn], is born.

=== 534 YW ===

* The small community of Dwarven Doors, in the Northlands just outside Knalga, rebels against the Orcish overlords. '''Northern Rebirth''' begins.
* The residents, led by Tallin, head underground and find dwarves, whom they ally with.
* Their combined forces destroy a lich who is attempting to claim Knalga as his own.
* Abhai finds the [http://wiki.wesnoth.org/CampaignDialogue:NR#Abhai_Finds_Rod_of_Justice Rod of Justice]

=== 535 YW ===

* The warlord-aspirant Rakshas attacks Tallin and his forces, but does not penetrate the dwarves' defences.
* To help defeat the orcs, Tallin secures the help of two Liches, and rescues an elvish princess to secure the help of the elves.
* Assisted by his new allies, Tallin smashes the forces of Rakshas.
* According to some historians, Tallin and the elvish princess are married; others say they parted in bad blood.
* To preserve the new-found peace in the Northlands, Tallin and his allies form the Northern Alliance. '''Northern Rebirth''' ends.

=== 550 YW ===

* Lord Hamel of Knalga sends an expedition to Kal Kartha to determine the fate of the Hammer of Thursagan ('''The Hammer of Thursagan''' takes place in late 550 YW to early 551 YW.).
* Dwarves at Knalga and elsewhere begin to reclaim the lost art of runesmithing.
* Wesnothian colonization expands southward past Fort Tahn.

=== 563 YW ===
* Konrad and Li'sar die after an extraordinarily long reign.
* Princess Ana'sar becomes queen.
* The seer Galdren becomes prominent at the court of Weldyn.

=== 585 YW ===
* Queen Ana'sar retires.
* Haldric VII becomes king of Wesnoth.

=== 589 YW ===
* Dacyn the White Mage and Ravanal, an eastern wizard, compete to be the king's advisor.
* The seer Galdren dies after advising Haldric VII to choose Dacyn.
* The king does as Galdren advises.

=== 593 YW ===
* Ravanal reveals that he has turned to evil, and flees from Weldyn.
* Konrad II is born.
* Certain southern frontier regions are formally annexed to the Kingdom of Wesnoth as the Province of Kerlath.

=== 598 YW ===
* South Guard organized as a semi-detached formation of the Royal Army, to protect the inhabitants of the frontier province of Kerlath.

=== 607 YW ===
* South Guard ceases reporting. Haldric VII sends Deoran, grandson of Haldiel, to investigate. '''The South Guard''' takes place in 607-608 YW.

=== 612 YW ===
* Haldric VII dies. Konrad II is crowned King of Wesnoth.
* Dacyn continues his duties as advisor with Konrad II.

=== 625 YW ===
* Mysterious disappearances of livestock and peasants cause partial evacuation of the the '''Estmark Hills'''. Lords of the Horse Plains report increased banditry from there.
* Konrad II sends [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn] with [http://wiki.wesnoth.org/CharactersStorys#Owaec Owaec] and [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry] to man the old River Guard strongpoints. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Eastern_Invasion '''Eastern Invasion'''] begins.

=== 626 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal] attacks the middle outpost where [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry] and [http://wiki.wesnoth.org/CharactersStorys#Dacyn Dacyn] are stationed.
* Dacyn and Gweddry travel to the northern outpost, and, with [http://wiki.wesnoth.org/CharactersStorys#Owaec Owaec], retreat into the northlands.
* In the Far North, the wife of Kai Laudiss slain in a large raid by the orcs of Tirigaz on Jotha
* Kai Laudiss slain by poisoned orcish dart during failed attack on the Port of Tirigaz orcs. His son, [http://wiki.wesnoth.org/CharactersStorys#Kai_Krellis Krellis] suceeds him as Kai and relies on the wisdom of [http://wiki.wesnoth.org/CharactersStorys#Cylanna Cylanna], a priestess.
* The merfolk city of Jotha is overrun by undead (Mal Kevek and others). The action of [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_Water '''Dead Water'''] takes place.

=== 627 YW ===
* Wesnoth's last defences are broken and the undead march on Wesnoth
* In the northlands, the orcs drive [http://wiki.wesnoth.org/CharactersStorys#Gweddry Gweddry's] army back across the river.
* Weldyn is besieged.
* Gweddry breaks through undead lines to reach Weldyn and a council is held.
* Gweddry's army is fortunate and kills [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal]. [http://wiki.wesnoth.org/Mainline_Campaigns#The_Eastern_Invasion '''Eastern Invasion''' ] ends. [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_water '''Dead Water'''] ends (about this time).
* Wesnoth is saved, but large portions have been laid waste by the undead.
* After destroying [http://wiki.wesnoth.org/CharactersStorys#Mal-Ravanal Mal-Ravanal's] henchmen the mermen relaxed and began rebuilding in earnest, and soon Jotha was restored.

== 628-673 YW: The Silver Age of Wesnoth ==

The Silver Age, or restoration of the Wesnothian kingdom, essentially coincides with the rest of the long and successful reign of [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II]. During this period Wesnoth largely recovered from the damage that Mal-Ravanal's undead attack had done. It would, however, never quite regain the majesty it had at the height of its power.

The Northlands, aided by a second wave of colonization north from Wesnoth, become more civilised and stable. Although nowhere near as prosperous as Wesnoth was during its Golden Age, the Northlands developed towns of significant size and a thriving - if somewhat dangerous - trade network.

Four major powers soon came to dominate much of the Northlands. First there were the dwarves, who controlled most of the mountains and a vast array of underground tunnels and caverns. To the east, shrouded in mystery, lay the Elvish forests which continued to be inaccessible to anyone not of elvish blood. The remaining landscape was dominated either by orcish tribes, or independent human earldoms. As competition for the land grew fierce, wars smoldered between human and orcish forces.

=== 628-635 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II] begins his attempt to rebuild Wesnoth.

=== 673 YW ===
* [http://wiki.wesnoth.org/CharactersStorys#Konrad_II Konrad II] dies, bringing the [[Garardine Dynasty]] to an end. Second Wesnothian civil war begins.

== 761-816 YW: The Legacy of Black-Eye Karun ==

After decades of struggle, Black-Eye Karun becomes the first warlord since the assassination of Great Chief Brurbar in 20 YW to unite all the different squabbling orcish tribes under his banner. Among his many accomplishments as a Sovereign, his most famous is the creation of the Great Council.

Karun was a far-sighted individual and he knew that after his death the orcish tribes would once again turn to fighting among themselves, with little he could do to prevent that and consequent peril from the Wesnothians and elves.

Consequently, Karun selected from among all the different tribes six of the most sober and wisest orcs and thus created the Great Council. It was the Great Council's job to stay aloof from any tribal or territorial squabbling amongst the orcs, but yet always remain there to give advice to whomever came to seek it. In order to preserve the orcish race in the event of an emergency, he invested in them the power to call up The Great Horde. It was established that every orc, no matter what tribe he came from, must obey the summons of The Great Horde and follow wholeheartedly the leader that the Great Council put at the head of The Great Horde.

===812 YW===
Rahul I becomes Lord Protector of the Northern Alliance

===816 YW===
* Rahul I (Lord Protector of the Northern Alliance) and Black Eye Karun sign a peace treaty ending a 15 year war between the humans and the orcs. Soon after this Karun, is ambushed and killed in mysterious circumstances.

===829===
Howgarth III succeeds Rahul I as Lord Protector of the Northern Alliance

===842 YW===
* Famine in the Northlands. Famine led humans to colonize some orcish lands and push orcs into desolated hill country. The few orcish tribes who had remained part of the Alliance, feeling the pressure, either left Alliance territory or revolted and were destroyed.
* Retaliating, the orcs systematically slaughtered human colonies and villages on their lands. Then, Earl Lanbec'h — the most powerful human warlord of the North — determined to abolish the orcish menace raised an army and conferred leadership of it to his son-in-law Baron Alber.
* In response, the Great Council set up by the Black Eye Karun calls upon The Great Horde and bestows leadership of it upon [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e]; [http://wiki.wesnoth.org/Mainline_Campaigns#Son_of_the_Black_Eye '''Son of the Black Eye'''] begins.

===843 YW===
* Half of the Great Council is treacherously slain by the allied human forces and orcish unity disintegrates. Faced with the extermination of all the orcs on the Great Continent, [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e] forcibly asserts his control over the orcish territories and defeats the enemy forces. The Northern Alliance arrives on the scene in time for the final battle and helps Kapou’e defeat the forces of the northern earldoms, who had broken the treaty. Kapou’e then assumes the position of Sovereign over the northern tribes, and his rule ushers in an unprecedented era of unity and prosperity for the orcs.
* After 843: Portions of Kapou'e's army act as mercenaries in foreign struggles with other races which keeps them from attacking their nearest neighbors.

===852 YW===
*[http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e] repels a large elvish invasion.

===858 YW===

*The humans once again stage an invasion but prove to be no match for the united orcish forces under the leadership of [http://wiki.wesnoth.org/CharactersStorys#Kapou.27e Kapou’e]. [http://wiki.wesnoth.org/Mainline_Campaigns#Son_of_the_Black_Eye '''Son of the Black Eye'''] ends.

==After the Fall==
At some unknown point in the future, an unspeakable cataclysm scorched the surface of the lands. The Wesnoth magicians try to raise up a 3rd sun in the sky, but they fail and the 'sun' falls down over Weldyn. The capital is no more. The King and his family are dead and there is no heir. The local leaders tear apart Wesnoth. The nights become longer, days hotter. Evil creatures show up. Forests die, hills turn into rocky wastelands and fields become barren deserts. In the apocalypse allies turn against each other and friends fight over what few resources remain. The great nations were destroyed, and huge numbers of people died. Still amidst the chaos somehow small groups of people survived, sheltered in hidden places. In this post-apocalyptic world survival is a daily struggle as a few remaining tribes eke out an existence among the ruins of fallen empires. Heroic bands of elves, nomadic refugee humans, savage hordes of orcs and dark necromancers all forge new lives under the merciless dual suns, Sela and Naia, of this new Wesnoth.

===??? Post-Wesnoth===

* The Quenoth elves adapt to life in barren world of the Great Southern Desert. Over time they lost their affinity for the woodlands of their ancestry and embrace life in the sandy wastelands.
* Under the leadership of Tanuil, the Quenoth elves build and sustain a fortified village around a rare oasis. The village thrives amidst the hostilities of the desert.
* One night, a meteor storm rains from the sky and destroys the village of the Quenoth elves. '''Under the Burning Suns''' begins. The next day, Tanuil, like many others, is missing and presumed dead. Kalehssar (Kaleh), nephew of Tanuil, takes leadership of the remaining Quenoth elves as the surviving next of kin.
* Kaleh, heeding the voice of his god Eloh in his dreams, gathers the remaining Quenoth elves and leads them north to a new promised land, foregoing rebuilding of their desert village.
* The Quenoth elves battle their way north through Undead, Orcs, Bandits and other evil, venturing underground beneath a large mountain range at the command of Eloh.
* Befriending unexpected allies underground, Kaleh's forces survive to the other side of the mountain.
* Keratur, son of Tanuil and survivor of the cataclysm, insane with fright attacks Kaleh. Kaleh defeats Keratur.
* Kaleh defies commands given him by a vision of Eloh.
* The Quenoth reach the ocean. Aided by Merfolk, they escape the mainland and head for a newly discovered island, a place where the Quenoth may settle in peace.
* On the island, the Quenoth confront Yechnagoth, the Eater of Souls and impersonator of Eloh. Yechnagoth and army are destroyed by the Quenoth.
* Kaleh and the elves settle on their newfound, and newly named, Quenoth Isle. '''Under the Burning Suns''' ends.

== History Credits ==

* Timelined by Kamahawk and Turin. Revised to incorporate material from later version of Legend of Wesmere and reconcile different versions of the history of the Scepter of Fire by Eric S. Raymond.

* History derived from:
** Eastern Invasion
** Heir to the Throne
** Legend of Wesmere
** Liberty
** Northern Rebirth
** The Hammer of Thursagan
** The Rise of Wesnoth
** Under the Burning Suns
** Dead Water
** Delfador's Memoirs

* Setting details derived from:
** Invasion from the Unknown

== See Also ==

* [[Geography of Wesnoth]]
* [[Poetry of Wesnoth]]
* [[Races]]
* [[FactionHistory]]
* [[Future History]] '''(unofficial)'''

[[Category:World of Wesnoth]]
[[Category:History]]

AnimationWML

2016-08-31T13:45:30Z

Zookeeper: Removed mention of animation-level terrain_type= once having been terrain=

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays its attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine.

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[filter_attack]
name=bow
[/filter_attack]
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
'''start_time'''=-200
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause before attacking
[/frame]
[frame]
image=units/bowshooter-prepare-bow.png:25
[/frame]
#now the time is synchronized with the missile frame for the arrow
[frame]
image=units/bowshooter-fire-bow[1~3].png:50
[/frame]
[frame]
image=units/bowshooter.png:25 #because defense animations could possibly
#be longer and if so this image will display
#Also gives a bit of a pause after attacking
[/frame]
'''sound_start_time'''=-150
[if]
hits=yes
[sound_frame]
sound=bow.ogg
[/sound_frame]
[/if]
[else]
hits=no
[sound_frame]
sound=bow-miss.ogg
[/sound_frame]
[/else]
[/attack_anim]
Note: that the arrow hits the target at time=0. Defense hit sounds are typically played at time=-25, slightly before the arrow hits the centre of the hex (the unit would feel it slightly before). It is the same idea for sword swishes and such, that 'hit' the outside of the unit before they hit the centre of the hex.

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string, dev feature 1.11.2 - progressive string>
image_diagonal=<string, dev feature 1.11.2 - progressive string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=<red, green, blue>
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>
auto_hflip=<boolean>
auto_vflip=<boolean>
primary=<boolean>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has an expanded syntax:

image=image1.png:100,image2.png:100,image3.png:100
halo=halo1.png:100,halo2.png:200,halo3.png:300

or (from Wesnoth 1.11.2+) equivalently,
image=image[1~3]:100
halo=halo[1~3]:[100,200,300]
see below for more information.

==== Progressive string square bracket expansion syntax ====

The square bracket syntax for progressive strings is a syntactic shortcut that, for convenience, works like so:
halo=halo[3,5,7].png is equivalent to halo=halo3.png,halo5.png,halo7.png
halo=halo[07~10].png is equivalent to halo=halo07.png,halo08.png,halo09.png,halo10.png
(if you include leading zeros, the digits will be padded throughout that square bracket expansion to match)
halo=halo[001~100].png is equivalent to halo=halo001.png,halo002.png,...,halo099.png,halo100.png
halo=halo[5~3,1].png is equivalent to halo=halo5.png,halo4.png,halo3.png,halo1.png
image=image[1~2]-ex[4~5].png:[100,200] is equivalent to image=image1-ex4.png:100,image2-ex5:200.png
image=image[1~4].png:[10,20*3] is equivalent to image1.png:10,image2.png:20,image3.png:20,image4.png:20
image=image[1~3].png:50,other.png:40 is equivalent to image1.png:50,image2.png:50,image3.png:50,other.png:40

Each set of square brackets (‘[’ and ‘]’) contains a comma-separated list — an '''''expansion list''''' — of which each element can be:

* a '''plain string''' — e.g., “abc” or “123”;
* a '''range''', expressed as two radix-10 integers, separated by a tilde — e.g., “1~5”; or
* a '''repetition''', notated as a string and a radix-10 integer, separated by an asterisk — e.g., “a*3”.

Ranges can not only be from a lesser number to a greater number (e.g., “1~5”), but can also be '''backward''' — from a greater number to a lesser number (e.g., “5~1”).

===== Range expansion =====

Each '''range''' ''<var>x</var>~<var>y</var>'' is expanded within its expansion list to a comma-separated list of radix-10 integers (which are plain strings), starting from the first endpoint <var>x</var> and ending at the second endpoint <var>y</var>.

If '''<var>x</var> < <var>y</var>''', then the numbers in this list increase by increments of 1; if '''<var>x</var> > <var>y</var>''', then the numbers in this list decrease by decrements of 1. E.g., “1~3” would become “1,2,3”, and “3~1” would become “3,2,1”.

If '''<var>x</var> = <var>y</var>''', then this list has only one element, which is <var>x</var> (and is also <var>y</var>, of course). E.g., “2~2” would becomes “2”.

If either <var>x</var> or <var>y</var> (or both) are padded with '''leading zeros''', then each number in the resultant list will be padded with leading zeros such that it is expressed in at least <var>z</var>+1 digits, where <var>z</var> is the quantity of leading zeros with which one or both endpoints are padded. E.g.,
* “07~11” would become “07,08,09,10,11”,
* “098~100” would become “98,99,100”,
* “003~1” (or “3~001”) would become “003,002,001”, and
* “0098~100” would become “098,099,100” (although poor form), and
* “01~100” would become “01,02,...,10,11,...,999,100”.

If both endpoints are padded with leading zeros, they should both be padded with the same quantity of leading zeros.

===== Repetition expansion =====

Each '''repetition''' ''<var>s</var>*<var>n</var>'' is expanded within its expansion list to a comma-separated list with <var>n</var> elements, each of which is the string <var>s</var>. E.g., “abc*3” would become “abc,abc,abc”.

===== Square bracket expansion =====

A single '''progressive string value''' may contain multiple '''square-bracketed expansion lists''', which must all be of the same length in elements (after range and repetition expansion). This length shall be referred to as <var>L</var> for the remainder of this section.

When a progressive string that contains expansion lists is processed to expand its expansion lists, it is transformed into a comma-separated list with <var>L</var> elements.

For each integer <var>n</var> from 1 to <var>L</var>, the <var>n</var>-th element of this list shall be a copy of the progressive string, with each expansion list it contains replaced with that expansion list’s <var>n</var>-th element (after range and repetition expansion).

When a progressive string that contains expansion lists is processed it is transformed at each bracket pair into a comma-separated list, which is generated as follows (in pseudo code):
for each comma separated string entry
for all square brackets entries at once
expand outwards such that S[A~B]T expands to SAT, ..., SBT preserving any leading zeros
expand outwards such that S[A,B]T expands to SAT, SBT
expand outwards such that S[A*N]T expands to SAT, ..., SAT (n times)
and any combination of above separated by commas executed sequentially
next
next

==== Field Description ====

* '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
* '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
* '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''. If specified by timing in a progressive string, such as a halo, this can be left out and will be automatically calculated.
* '''image''': the image, or sequence of images, to display during the frame.
* '''image_diagonal''': the image, or sequence of images, to display when the attack occurs diagonally (directions ne,se,sw,nw).
* '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
* '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
* '''halo''': the halo to display at the time.
* '''halo_x''', '''halo_y''': the position the halo is displayed in pixel relative to the unit's center. These are directional, taking into account the direction the unit is facing.
* '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
* '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
* '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
* '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255); this color will be mixed to the frame to give it a tint.
* '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
* '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
* '''text_color''': the color of the above floating label.
* '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
* '''x''': x offset applied to the frame
* '''y''': y offset applied to the frame
* '''directional_x''': the x offset, in pixels, applied to the frame in the direction the unit is facing
* '''directional_y''': the y offset, in pixels, applied to the frame in the direction the unit is facing
* '''layer''': layer used to draw the frame, see discussion bellow
* '''auto_hflip''': should the image flip horizontally depending on sprite orientation
* '''auto_vflip''': should the image flip vertically depending on sprite orientation
* '''primary''': should the engine consider that frame as a primary frame (affected by visual effects like stone and poison)

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_color=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
directional_x=<progressive int>
directional_y=<progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_color=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_alpha=<progressive float>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_directional_x=<progressive int>
xxx_directional_y=<progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

Note that xxx_ parameters (e.g. missile_offset) are shortcuts to access parameters from outside of their corresponding frame and have no effect inside of them.

== How animations are chosen ==
Within a unit description block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the following movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptoeing animation when moving next to an enemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an enemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criteria. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criterion that fails on the current situation
* Take the animations that have the most matching criteria
* If there are more than one animation remaining, take an animation randomly
* If all animations have been dropped, the engine will provide a smart default.

here is a pseudo-code explanation of this algorithm:

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''value_second''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain_type''': a list of comma separated terrain codes, the animation will only be used on matching terrains. See [[FilterWML#Filtering Terrains|Filtering Terrains]].
* '''[filter]''': this will filter using a [[StandardUnitFilter|standard unit filter]] on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a [[StandardUnitFilter|standard unit filter]] on the unit in the hex faced. Note that matching all criteria in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter_second]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML#Filtering Weapons|Filtering Weapons]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1). this has been replaced by value_second
* '''base_score''': a number that will always be added to the score. Use with caution

=== Events triggering animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''alpha=0~1:600''

==== recruiting ====

This animation is triggered for the leader when a unit is recruited or recalled

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

no default animation is needed

note that is not triggered for WML triggered animations

==== levelout ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:600" blend_color=255,255,255''

==== levelin ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:600" blend_color=255,255,255''

==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 200ms in each hex. so you typically want to have an offset of ''0~1:200,0~1:200,0~1:200,0~1:200,0~1:200'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' contains the number of steps already taken

''value_second='' contains the number of steps left

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"''

==== pre_movement ====
This animation is used before any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== post_movement ====
This animation is used after any unit movement

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="1~0:200" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0~1:200" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison damage

''value='' is the number of points lost

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_ratio="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''

==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

''value_second='' is the number of the swing, starting from 1

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:200,0.6~0:200"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

''value_second='' is the number of the swing, starting from 1

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''alpha=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

''value_second='' is not used, and always contains 0

No default is provided by the engine

==== draw_weapon ====
This animation is played before a fight

''hit='' is set to HIT for the attacker and MISS for the defender

No default is provided by the engine

==== sheath_weapon ====
This animation is played after a fight simultaneously for all surviving units

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

''value_second='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

''value_second='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that. ('''Attention:''' These do not have the same syntax as the action tag [if] and its subtag [else] in [[ConditionalActionsWML]].)

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, and from 1.11.7+ you can nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

start_time=-100
[if]
hits=no
[frame]
image="units/dwarves/lord-attack.png:200"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
image="units/dwarves/lord-attack.png:200"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

A macro exists under macros/sound-util.cfg called SOUND:HIT_AND_MISS to simplify this type of animation, which is equivalent to:

start_time=-100
[frame]
image="units/dwarves/lord-attack.png:200"
[/frame]
{SOUND:HIT_AND_MISS axe.ogg {SOUND_LIST:MISS} -100}

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[recruiting_anim]''' is an animation with the following parameters automatically set
apply_to=recruiting
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200,0~1:200"
* '''[pre_movement_anim]''' is an animation with the following parameters automatically set
apply_to=pre_movement
* '''[post_movement_anim]''' is an animation with the following parameters automatically set
apply_to=post_movement
* '''[draw_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=draw_weapon
* '''[sheath_weapon_anim]''' is an animation with the following parameters automatically set
apply_to=sheath_weapon_movement
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_color=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== Optimization ==

there is a special flag that goes into the animation block (not the frame)

* ''offscreen'' a boolean saying if the unit's animation should be played when the unit is offscreen. You want the animation to play offscreen if the animation contains some usefull sound effects.This attribute defaults to true (play offscreen) except for standing and idle animations where it defaults to false

== Cycling ==

there is a special boolean parameter that can be put in an animation block (not the frame)

* ''cycles'' a boolean value. if set to true the animation will cycles forever until it is replaced. That animation will not influence the end time of all related animations (for example a cycling defense animation will play normally but the overall duration of the fight animation will be only decided by the attack animation)

== See Also ==

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

[[Category: WML Reference]]

CampaignWML

2016-08-14T11:39:51Z

Zookeeper: Documented [campaign] [event]

{{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)
* '''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_KHALID {{DevFeature1.13|0}}
:allows the advancement ''Shuja'' -> ''Khalid''
</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 [http://www.wesnoth.org/macro-reference.xhtml#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 and 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.
* '''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.)
* '''[about]''': inserts your own credits into the game's list of credits. See below for syntax.
* '''end_credits''': Whether to display the credits screen at the end of the campaign. Defaults to ''yes''.
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End".
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500.
* '''[event]''': {{DevFeature1.13|2}} events placed here will be automatically inserted into all scenarios of the campaign.

The following keys are additionally recognized in multiplayer:
* '''min_players''': Minimum number of players campaign supports. Defaults to 2.
* '''max_players''': Maximum number of players campaign supports. Defaults to '''min_players'''.
* '''allow_era_choice''': Whether to hide era selection and use a default one when creating a game. Defaults to ''yes''.
* '''require_campaign''': Whether clients are required to have this campaign installed beforehand to be allowed join a game using this campaign. Possible values 'yes' (the default) and 'no'.

== Campaign credits ==

The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs. There can be any number of '''[about]''' tags inside a '''[campaign]''' tag, but none of them will display credits if there is no "id" key present inside [campaign] (see above). The '''[about]''' tag has the following keys:
* '''title''': (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits
* '''text''': (translatable, but you probably won't want to make it such) smaller text which is displayed before the contributor names
* '''[entry]''': Contains information about a single contributor. Only the ''name'' key will be used in-game, the other three keys are for display on the [[Credits]] page ('''note:''' the values of these keys will only display on the Credits page for mainline campaigns; they will not display for UMC campaigns)
** '''name''': The name of the contributor
** '''comment''': Optional short note about what that person did
** '''email''': Optional email address
** '''wikiuser''': Optional, the user name on the wiki

== See Also ==

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

[[Category: WML Reference]]

EffectWML

2016-05-19T21:09:58Z

Zookeeper: Documented ellipse=none

{{WML Tags}}

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification. Modifications are permanent changes to a unit; currently there is no way of removing a modification.

The following keys and subtags are always recognized:
* '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details.
* '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level. {{DevFeature1.13|5}} Integers are now supported for ''times''.
* '''apply_to''': describes what the effect actually affects.
[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* '''new_attack''': will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]].
* '''remove_attacks''': remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* '''attack''': find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML#Filtering Weapons|FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''set_icon''': change the attack's icon.
** '''[set_specials]''': change the attack's specials. The specials to add are given exactly as in the [specials] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
** '''remove_specials''': remove the listed specials. The value of this key is the coma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''increase_accuracy''': increases the attack accuracy; can be positive or negative, or a percentage
** '''increase_parry''': increases the attack parry bonus; can be positive or negative, or a percentage
** '''increase_movement_used''': {{DevFeature1.13|2}} increases the movement points used by the attack; can be positive or negative, or a percentage
** '''set_damage''' {{DevFeature1.13|2}} like increase_damage, but sets the damage to a specific value instead of setting it relative to its original value
** '''set_attacks''' {{DevFeature1.13|2}} like increase_attacks, but sets the attacks to a specific value instead of setting it relative to its original value
** '''set_accuracy''' {{DevFeature1.13|2}} like increase_accuracy, but sets the accuracy to a specific value instead of setting it relative to its original value
** '''set_parry''' {{DevFeature1.13|2}} like increase_parry, but sets the parry to a specific value instead of setting it relative to its original value
** '''set_movement_used''' {{DevFeature1.13|2}} like increase_movement_used, but sets the movement used to a specific value instead of setting it relative to its original value
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML#Attacks|UnitTypeWML]] for explanations about defense_weight.
* '''max_attacks''': {{DevFeature1.13|2}} change the unit's maximum attacks per turn
** '''increase''': how much to increase by; can be positive or negative, or a percentage
* '''hitpoints''': modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* '''movement''': modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
* '''vision''': {{DevFeature1.13|2}} modifies the unit's vision points.
** '''increase''': maximum vision is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum vision is set to a specific value.
* '''jamming''': {{DevFeature1.13|2}} modifies the unit's jamming points.
** '''increase''': maximum jamming is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum jamming is set to a specific value.
* '''experience''': affects the unit's current XP.
** '''increase''': current XP is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': current XP is set to a specific value.
* '''max_experience''': affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
* '''loyal''': no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* '''movement_costs''': speed through specific terrain is modified
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[movement_costs]''': a subtag that describes the new movement costs just like in [[UnitsWML#.5Bmovetype.5D|UnitsWML]]
* '''defense''': Sets the unit's chance to be hit in specific terrain (100 - the unit's defense as shown in-game).
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. In most cases, adding a positive number makes the unit easier to hit, while adding a negative number makes the unit harder to hit. The new value is added to the absolute value of the old, and the sign of the old value is preserved.
** '''[defense]''': a subtag that describes the new defense just like in [[UnitsWML#.5Bmovetype.5D|UnitsWML]]
* '''resistance''': Sets percent damage taken from combat (100 - the unit's resistance as shown in-game)
** '''replace''': If set to "yes", any new values replace the old ones. Otherwise, new values are added to old values. Adding a positive number makes the unit take more damage, while adding a negative number makes the unit take less damage.
** '''[resistance]''': a subtag that describes the new resistance just like in [[UnitsWML#.5Bmovetype.5D|UnitsWML]]
* '''variation''': switches the unit into one of its variations.
** '''name''': the id of the variation to invoke.
* '''type''': transforms the unit into a new unit_type.
** '''name''': the id of the unit_type to invoke.
* '''status''': modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* '''zoc''': toggle the zone of control.
** '''value''': new value for zoc (boolean).
* '''profile''': customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
* '''new_ability''': Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag.
* '''new_animation''': contain animations that will be added to the unit, it can contain multiple animation blocks, and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster.
* '''image_mod''': modify the image path function ([[ImagePathFunctionWML]]) of all the unit's frames.
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
* '''ellipse''': Change the image used for the unit's ellipse.
** '''ellipse''' : the new image to use. Can be set to "none" to disable the ellipse.
* '''halo''': Change the image used for the unit's halo.
** '''halo''': the new image to use.
* '''overlay''': Change the unit's overlays.
**'''add''': the specified overlay will be added to the unit's overlays. It can be a comma separated list with multiple overlays. ''Note: overlays added in this way cannot be removed by [remove_unit_overlay] until the effect's duration is over.''
**'''replace''': all the unit's overlays will be removed and replaced with the specified one. Again, it can be a comma separated list. ''Note: overlays replaced in this way cannot be modified by [unit_overlay] or [remove_unit_overlay] until the effect's duration is over.''
* '''recall_cost''': {{DevFeature1.13|2}} change a unit's recall cost
** '''set''': set recall cost to a specific value, or a percentage of original value
** '''increase''': alter recall cost relative to original value; can be positive or negative, or a percentage
* '''alignment''': {{DevFeature1.13|2}} change a unit's alignment
** '''set''': the new alignment (one of chaotic, lawful, neutral, liminal)
* '''new_advancement''': {{DevFeature1.13|2}} add new advancement choices to the unit
** '''replace''': whether to replace existing advancement choices; if this key is set to yes, existing advancement choices are cleared only if you're adding a choice of the same type. (That is, unit type advancements are cleared only if you're adding a new unit advancement choice, and AMLA choices are cleared only if you're adding new AMLA choices.)
** '''types''': a comma-separated list of additional unit types the unit can advance to. ('''Note:''' If using this, you probably want to include a filter to prevent the unit from being able to advance to this type once it has already done so.)
** '''[advancement]''': an advancement choice to add, see [[UnitTypeWML#After_max_level_advancement_(AMLA)|AMLAs]]; you can have several of these tags to add multiple advancement choices at the same time.
* '''remove_advancement''': {{DevFeature1.13|2}} remove existing advancement choices from the unit
** '''types''': a list of unit type advancements to remove as a possibility
** '''amlas''': a list of AMLA id attributes; any advancement possibility with the given id will be removed

=== Examples ===
== Effect: apply_to = new_animation ==
This is the only way to change animations of units after they have been placed on the map.
In this example, I add very simple idle animation (taken from Goblin Spearman) to the unit, which moves to hex (x=1, y=5). If you want something more complex, you need to check [[AnimationWML]] page.

[event]
name = moveto
[filter]
x,y = 1,5
[/filter]
[object]
[filter]
x,y = 1,5
[/filter]
[effect]
apply_to = new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/object]
[/event]

If you are going to use '''advanced WML''' and want to add animation to unit, stored in variable, then following example might help you. '''This way is not efficient if you have no additional logic like inventoriy, shops, advanced unit modifications in your add-on.''' Is is preferred to use first variant or define all needed animation in unit_type.
[event]
name = moveto
[filter]
x,y = 1,5
[/filter]
[store_unit]
[filter]
x,y=1,5
[/filter]
variable = stored_unit
[/store_unit]
[set_variables]
name = stored_unit.modifications.object
[value]
[effect]
apply_to = new_animation
[idle_anim]
{STANDARD_IDLE_FILTER}
start_time=0
[frame]
image="units/goblins/spearman-idle-[1~12].png:[150*3,300,150*8]"
[/frame]
[/idle_anim]
[/effect]
[/value]
[/set_variables]
[unstore_unit]
variable = stored_unit
[/unstore_unit]
[/event]

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

DirectActionsWML

2016-03-22T21:42:14Z

Zookeeper: Documented [on_undo] and [on_redo]

{{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 percentage (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 true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
* '''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] ===
Places a unit on the map. For syntax see [[SingleUnitWML]].
* {{Short Note:Predefined Macro|GENERIC_UNIT}}
* '''to_variable''': spawn directly into a variable instead of on the map.

=== [recall] ===
Recalls a unit taking into account any [http://wiki.wesnoth.org/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.
* '''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).

=== [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 position to teleport to. If that position is not empty, some other location will be chosen.
* '''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.

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 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.

=== [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. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
* '''variable''': the name of the variable.
* '''find_vacant''': 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''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".
* '''text''': (translatable) 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 to display the text in. 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.)
* '''advance''': (default=true) if true 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''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.
* '''animate''': (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.
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.
* '''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 add to the types the leader can recruit because of [side]recruit=.
* '''extra_recruit''': the types of units that the unit 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.
* '''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.
* '''extra_recruit''': the types of units that the side 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.
* '''recruit''': the types of units that the side can now recruit.
* '''side''': (default=1) the number of the side that is having its recruitment set. 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.

=== [set_extra_recruit] ===
Sets the units a leader can 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''.
* '''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.
* '''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 [http://wiki.wesnoth.org/AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag [modify_ai]] instead, which always works.
* '''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
* '''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.

=== [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 take any arguments.

=== [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''': if 'yes', displays the unit dying (fading away).
* '''fire_event''': 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. 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).

=== [move_unit] ===
works like the MOVE_UNIT macro.
* [[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.
* '''fire_event''' (optional, 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.
* '''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.

=== [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.
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the :inspect command. It can add [trait]s and [object]s without needing to wrap them inside a [modifications] tag, and their effects are applied immediately. Cannot remove things. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify.
example usage (see also the test scenario):
[modify_unit]
[filter]
x,y=38,6
[/filter]
hitpoints=10
{TRAIT_HEALTHY}
[/modify_unit]

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).

note: The syntax allowed is somehow vague. Just try things and possibly correct/add/modify this documentation. (a [http://forums.wesnoth.org/viewtopic.php?f=21&t=31676& forum thread] discusses some related issues).

=== [transform_unit] ===
Transforms every unit 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.
* [[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.
* '''id''': (Optional) when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per scenario. In a campaign objects with the same id can be assigned once per scenario. For filtering objects, custom key can be used, such as item_id.
* '''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 to work around a bug when adding ABILITY_TELEPORT via an [object] or when using [object][effect][filter]with a $this_unit (see http://gna.org/bugs/index.php?18893).
* '''[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 level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
**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' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* '''[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 is tried 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)
* '''[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 true, 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.
* '''no_write''': {{DevFeature1.13|1}} (bool, default false). If true, the contents of [effect] will be applied to the relevant unit, but the [object] tag will not be written to unit.modifications. This renders duration= irrelevant.

=== [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_view=yes).

=== [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, recruitment, 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.

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

=== [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. Note that if delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are '''not''' available.

=== [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.

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser 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.
* '''[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 true) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.
* '''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. Before 1.9 this is always "no".

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[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.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''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''
* [[TimeWML]]: the new schedule.
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. 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)
[time_area]
x=1-2,4-5
y=1-2,1-2
{UNDERGROUND}
[/time_area]

=== [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''': Content of a wesnoth map file. example:
map="{campaigns/Heir_To_The_Throne/maps/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.

=== [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). ([http://forums.wesnoth.org/viewtopic.php?f=21&t=14749&p=405667&hilit=tunnel#p405667 source])

* '''id''' identifier for the tunnel, to allow removing (optional).
* '''remove''': (boolean) yes/no value. If yes, removes all defined tunnels with the same ID (then only id= is necessary). (default: no)
* '''bidirectional''': (boolean) if yes, creates also a tunnel in the other direction. (default: yes)
* '''always_visible''': (boolean) if yes, the possible movement of enemies under fog can be seen. (default: no)
* '''[source]''': [[StandardLocationFilter]] the source hex(es) (required).
* '''[target]''': [[StandardLocationFilter]] the target hex(es) (required).
* '''[filter]''': [[StandardUnitFilter]] the units which can use the tunnel (required). Leave empty for "all units".

(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]

The tags corresponding to player actions generally use the same codepath as if a player had ordered it.

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 always be replay safe.

=== [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.

== 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 [http://www.wesnoth.org/macro-reference.xhtml 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]]

EventWML

2016-01-14T16:19:43Z

Zookeeper: Documented the 'unit placed' event

{{WML Tags}}
== The [event] Tag ==

This tag is a subtag of the [scenario], [unit_type] and [era] tags which is used to describe a set of [[ActionWML|actions]] which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit_type] tag, the event will occur in all scenarios in which a unit of that type appears in (only after such a unit appears during the scenario, however). When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the word "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

=== The 'name' Key (Mandatory) ===

Usage:
name=<value>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

name=attacker misses,defender misses

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

All predefined event types are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else.

Spaces in event names can be interchanged with ''underscores'' (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

==== Predefined Events Without Filters ====

These events do not take filter parameters (except [filter_condition] which works for all events).

===== preload =====

Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.

'''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

===== prestart =====

Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

===== start =====

Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.

'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

===== new turn =====

Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

===== turn end =====

Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

===== turn ''X'' end =====

Triggers at the end of turn ''X''.

===== side turn =====

Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

===== ai turn =====

Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.

'''Note:''' ''This event currently breaks replays since it is not explicitly saved in a replay and there is no AI involved in replays...''

===== turn refresh =====

Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.

Note that the turn refresh event does occur on turn 1, even though healing, income and unit refreshing do not.

===== turn ''X'' =====

Triggers at the start of turn ''X''. It's the first side initialization event.

Side initialization events go in the order of:

# '''turn ''X'''''
# '''new turn'''
# '''side turn'''
# '''side ''X'' turn'''
# '''side turn ''X'''''
# '''side ''X'' turn ''Y'''''
# '''turn refresh'''
# '''side ''X'' turn refresh'''
# '''turn ''X'' refresh'''
# '''side ''X'' turn ''Y'' refresh'''

===== side ''X'' turn ''Y'' =====

This event triggers at the start of turn ''Y'' of side X

===== side ''X'' turn =====

This event triggers at the start of any turn of side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side turn ''X'' =====

This event triggers at the start of any side on turn X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side X turn Y refresh =====

This event triggers at the turn refresh for side X on turn Y

===== side ''X'' turn refresh =====

This event triggers at the turn refresh for side X

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== turn ''X'' refresh =====

This event triggers for any side at the refresh of turn X.

'''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

===== side turn end =====

Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:

# '''side turn end'''
# '''side ''X'' turn end'''
# '''side turn ''X'' end'''
# '''side ''X'' turn ''Y'' end'''
# '''turn end'''
# '''turn ''X'' end'''

===== time over =====

Triggers on turn ''turns''. (''turns'' is specified in [scenario])

===== enemies defeated =====

Triggers when all sides that are not defeated are allied and if there is at least one human (or human networked) side among them. Especially this event triggers in a situaltion that would normaly cause a victory due to enemies defeated. (regardless of whether this was disabled with victory_when_enemies_defeated=no).

===== victory =====

In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]]). This event is not synchonized in networked mp or in replays. The reason is that it is possible to have diffrent results in a mp game (one player wins so a '''victory''' event is fired on that client, other player loses so a '''defeat''' event is fired on his client)

===== defeat =====

In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]]). Like '''victory''', this event is not synchonized in networked mp or in replays.

==== Predefined Events With Filters ====

Filters (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]. weapon and second_weapon variables are available inside attack, attacker_hits, defender_hits, die and last_breath events. See [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] for more information.

===== moveto =====

Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. If the unit moves to a village, the capture event will be fired before this event. <br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not undo other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' $x2 and $y2 refer to the hex the unit came from.

===== sighted =====

A '''sighted''' event is triggered by a unit becoming visible to a side (other than the unit's own side). This is mostly useful when the side seeing the unit uses [[fog of war]] or [[shroud]], but they still fire even when fog/shroud is not in use, and they do take into account the {{tag2|AbilitiesWML#The_.5Babilities.5D_tag|hides}} ability (for a moving unit and for ambushers). The ''primary unit'' is the unit that became visible, and the ''secondary unit'' belongs to the side that now sees the primary unit. In some cases, sighted events can be delayed from when they "should" occur. If that happens, the secondary unit will be filtered as if it was at the location where the event "should" have occurred, and ''x2,y2'' will store that location (not the current position of the secondary unit). To understand when sighted events fire, it is helpful to distinguish the times the acting unit sights other units from the times when the acting unit is sighted.

An acting unit can sight other units when it is recruited, recalled, leveled, or moved, and when fog or shroud is cleared from occupied hexes as a result. In these cases, the acting unit is always the ''secondary unit''. For the first three actions, there are two events associated with the action; clearing occurs between these events, but any sighted events are fired after the second event. (For example, when a unit is recruited, the ''prerecruit'' event fires, then fog is cleared, then the ''recruit'' event fires, then ''sighted'' events fire.) For movement, the sighted events fire between ''enter_hex'' and ''exit_hex'' events, but sometimes sighted events are postponed until the moving unit reaches a good place to stop (e.g. not in an occupied hex). As a major exception to the above, players have the option to delay shroud (and fog) updates. If the player delays shroud updates, sighted events are also delayed until the shroud is updated.

An acting unit can be sighted by other sides when it is recruited, recalled, leveled (in rare cases), or moved. In these cases, the acting unit is always the ''primary unit''. These events fire after sightings by the acting unit (unless the player delayed shroud updates). For the first two, the sighted event fires for all sides that can see the unit, other than the unit's own side (even if those sides use neither fog nor shroud). For leveling units, sides that could see the unit before it leveled are excluded. (This is why these events are rare – the leveling unit must have lost a [hides] ability as a result of leveling in order to be seen after, but not before, leveling.) For movement, a sighted event is fired for each side that could see the unit after movement, but not before. In particular, only the starting and ending hexes are considered; a unit that moves through seen hexes but ends movement in a fogged hex does not trigger a sighted event for itself. In all cases where the acting unit is sighted, a (single) ''secondary unit'' is chosen from the sighting team. This choice should be considered arbitrary, but units within their sight range of the acting unit are chosen in preference to units further away.

Sighted events are not triggered by a ''hides'' ability becoming inactive, unless it becomes inactive due to that unit's movement or to that unit ambushing another. (To detect a ''nightstalk'' ability becoming inactive due to time of day, use a ''new_turn'' event. Custom ''hides'' abilities might need similar handling.)

Sighted events have some special caveats for WML authors. First and foremost, {{tag|DirectActionsWML|allow_undo}} should generally be avoided in sighted events. It can be used if current unit positions have no bearing on the event, but otherwise it could cause a replay to go out of sync if a player delays shroud updates and undoes a move. This should not be an onerous restriction, though, as clearing fog will block the ability to undo, regardless of what happens within an event. Secondly, it is currently possible for WML to kill a unit involved in a sighted event before that event fires. If that happens, filters on the killed unit will not match anything and the event may seem to have not fired.

===== enter_hex =====

Triggers for each hex entered during movement, with $x1,$y1 identifying the hex entered and $x2,$y2 identifying the previous hex (just exited). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the entered hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

===== exit_hex =====

Triggers for each hex exited during movement, with $x1,$y1 identifying the hex exited and $x2,$y2 identifying the next hex (to be entered). If this event is handled without using {{tag|DirectActionsWML|allow_undo}}, then movement is interrupted, stopping the unit where it is.

'''Note:''' This event behaves a bit unusually if the hex is occupied (and the moving unit is simply passing through). When this happens, $x1,$y1 is still the hex where the event was triggered, but the moving unit (stored in $unit) will be located somewhere earlier in the route (the most recent unoccupied hex). That is, $x1,$y1 will not equal $unit.x,$unit.y (a condition that can be used to detect when the exited hex is occupied). The moving unit will have already spent its movement points to enter the event's hex even though it is has not actually moved from the most recent unoccupied hex.

===== attack =====

Triggers when the primary unit attacks the secondary unit.

===== attack end =====

Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

===== attacker hits =====

Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

===== attacker misses =====

Same as ''attacker hits'', but is triggered when the attacker misses.

===== defender hits =====

Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

===== defender misses =====

Same as ''defender hits'', but is triggered when the defender misses.

===== petrified =====
Triggers when the primary unit is hit by an attack with the 'petrifies' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'petrifies' ability).

===== last breath =====

Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

===== die =====

Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want to the primary unit to make a final [message], use name=last_breath, see above.

===== capture =====

Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture. This event will be fired before the moveto event. Villages becoming neutral (via [capture_village]) do not fire capture events. The variable $owner_side contains the previous owner side of the village. 0 means neutral.

===== recruit =====

Triggers when the primary unit is recruited (by the secondary unit). (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

===== prerecruit =====

Triggers when the primary unit is recruited (by the secondary unit) but before it is displayed.

===== recall =====

Triggers after the primary unit is recalled (by the secondary unit).

===== prerecall =====

Triggers when the primary unit is recalled (by the secondary unit) but before it is displayed.

===== advance =====

Triggers just before the primary unit is going to advance to another unit, or advance by AMLA. (This is after the player selects which advancement, if there is a choice). If this event removes the unit, changes the unit's type, or reduces the unit's experience below what it needs to advance, then the advancement is aborted. This also applies to advancement by AMLA.

===== pre advance =====

{{DevFeature1.13|0}} Triggers before the unit advancement dialog is shown. If this event removes the unit or reduces the unit's experience below what it needs to advance, then the advancement is aborted.

===== post advance =====

Triggers just after the primary unit has advanced to another unit, or advance by AMLA.

===== select =====

Triggers when the primary unit is selected. Prior to version 1.11, this also triggered when a move was interrupted, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

===== menu item ''X'' =====

Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

===== unit placed {{DevFeature1.13|3}}=====

Triggers when the primary unit is placed on the map, regardless of method. This includes but might not be limited to:
* Leaders and units placed in side definitions (fired once for every unit right before prestart events)
* Recruited and recalled units
* Units placed on the map with the [unit] tag ('''not''' units created directly onto a recall list or variable)
* Units placed by the wesnoth.put_unit() Lua function
* Units created via debug mode
* Units created by plague
* Every use of [unstore_unit]
This event is solely intended for special cases where no other event types suffice, for example if you must immediately apply a modification to every unit that ever appears. The event does '''not''' keep track of which units it has previously fired for, but can fire an unlimited number of times for the same unit as long the unit is "placed" several times and the event filter doesn't prevent it.

==== Custom events ====

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives. Also, custom events come very handy in [[Wml_optimisation]].

Example:
#The following is the definition of a custom event "unit recruited"
[event]
name=unit_recruited
first_time_only=no
[message]
speaker=unit
message=_ "Reporting for duty!"
[/message]
[/event]

#This is a standard recruit event that triggers whenever a unit is recruited by side 1
[event]
name=recruit
first_time_only=no
[filter]
[/filter]
[filter_second]
side=1
[/filter_second]

#And now a fire_event tag is used to trigger the previously defined event
[fire_event]
name=unit_recruited
[/fire_event]

#As a result, every time side 1 recruits a unit, this unit says "Reporting for duty!"
[/event]

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== id ====
: If an id is specified, then the event will not be added if another event with the same id already exists. An id will also allow the event to be removed, see below. Supplying a non-empty id= is mandatory in case of a [unit_type][event].

==== remove ====
: Whether to remove an event instead of adding a new one. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; if true, then the contents of the event are ignored and the event with the specified id is removed instead. {{DevFeature1.13|0}} May be a comma separated list.

[event]
id=id_of_event_to_remove
remove=yes
[/event]

<b>Note:</b> {{DevFeature1.13|0}} You can now use [[InternalActionsWML#.5Bremove_event.5D|[remove_event]]] instead (the [event] remove= syntax still works). It also accepts a comma separated list.

[remove_event]
id=id_of_event_to_remove
[/remove_event]

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria based on the weapon used by the primary unit. This is usable in the events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'', ''attack end'', ''last breath'', and ''die''. For more information and filter keys, see [[FilterWML#Filtering Weapons|Filtering Weapons]]. The most commonly used keys are the following.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the weapon used by the secondary unit.

==== [filter_condition] ====
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* [[ConditionalActionsWML#Condition_Tags|Condition Tags]]
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

==== [filter_side] ====
: The current side (usually the side $side_number) must match the passed [[StandardSideFilter]] for the event to fire.
:* SSF tags and keys as arguments as described in [[StandardSideFilter]].
: note: This tag makes most sense in side turn and turn refresh events. However, all wml events have a current side so one could also prevent e.g. a moveto event from firing if you put a [filter_side] tag there and the moving unit's side doesn't match.

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all [[ActionWML|action tags]] within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

More details in [[ActionWML]].

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* enter hex
* exit hex
* sighted
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* pre advance
* post advance
* attack
* attack end
* attacker hits
* attacker misses
* defender hits
* defender misses
* start
* prestart (prestart are synced but [message][option] & [unstore_unit] advancement choices will do a random decision because UI things don't work during prestart events.)
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh
* side turn end
* side X turn end
* side turn X end
* side X turn Y end
* turn end
* turn X end
* {{DevFeature1.13|0}} enemies defeated
* {{DevFeature1.13|0}} time over
The following are <b>not</b> synced:
* select
* preload
* victory
* defeat
* ai turn

If an event is not listed here, ask someone to be sure.

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

You need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

=== Event IDs ===

This problem can be avoided by setting an '''id''' on the event, i.e.:

#define DOUBLE
[event]
name=multiply_by_2
id=doubler_event
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

Events with the same ID will only be accepted once by the engine no matter how many times they are included, and will only be saved once to the scenario's savefile. Events with an ID can also be removed by using the '''remove''' key, i.e.:

[event]
id=doubler_event
remove=yes
[/event]

After that WML is encountered (at toplevel or after created from another event), the event with this ID is removed from the scenario wml, thus firing it has no effect. After an event is removed, it can still be re-added later.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

[event]
name=die
[message]
speaker='''second_unit'''
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker='''unit'''
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]

An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.

=== Delayed Variable Substitution Example ===

This code will display a message showing the turn number on which the nested ''moveto'' event happens.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

The following code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Finally, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $|turn_number"}
[/event]
[/event]

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.
[event]# parent
name=turn 2
#delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event]# child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event]# great-grandchild
name=turn 5
{DEBUG_MSG $turn_number}# output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Geography of Wesnoth

2015-12-07T21:07:26Z

Zookeeper: Removed weird details of Green Swamp's in- and outflow

{{Geography of Wesnoth/Translations}}
= Irdya =

The name of the world in which the kingdom of Wesnoth is situated is "Irdya". This term is , however, only rarely used in the era depicted by the main map. People normally just say "the world" or, poetically, "the wide green world".

== Wesnoth and Surrounding Lands ==

http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/data/core/images/maps/wesnoth.png

This map is current for approximately YW 450. Named cities were founded during the Golden Age of Wesnoth and have thus have existed for at least 200 years.

Place names in '''bold''' are marked on the main map.

* Major features:
** '''The Great Ocean''': Lies to the west of the continent and all rivers eventually flow to it.
** The '''Bay of Pearls''': The Elensefar Peninsula in the North and the '''Isle of Alduin''' in the southwest separate this from the Great Ocean. This is where human refugees from the Green Isle first landed in 1YW.
** '''Isle of Alduin''': Inhabited island off the west coast of the Great Continent. Home of the Great Academy of Magic and a traditional center of magecraft.
** '''The Three Sisters''': Group of three islands north-northwest of Alduin. The nearest is individually known as the Isle of the Damned and has an evil reputation.
** '''The Great River''': Runs east to west on the main map, unmarked.
** '''Ford of Abez''': Easternmost point at which the Great River can be crossed without ships. A traditional invasion route for armies crossing in either direction.
** '''River Weldyn''': Tributary running north from the '''Dulatus Hills''' to the '''Great River'''.
** River Aethen: River running from the '''Dulatus Hills''' to the '''Great Ocean''' through the '''Aethenwood'''.
** '''The Heart Mountains''': the major mountain range surrounding '''Lake Vrug'''.

=== Wesnoth ===
The Kingdom of Wesnoth is located in the north-central portion of the Great Continent. Most of the mainline campaigns revolve around it. It is bounded on the map by the '''Great River''' to the north, the shore of the '''Great Ocean''' to the west, the Aethenwood to the southwest, and the '''Bitter Swamp''' to the southeast (lower right corner of the main map).

Over the '''River Aethen''', south of '''Fort Tahn''', is a Wesnothian frontier region. It is bounded to the south (off-map) by dense woods of which the '''Aethenwood''' may be considered a northernmost extension.

* Notable cities:
** '''Weldyn''': The capital of Wesnoth.
** '''Aldril''': City lying on the Bay of Pearls.
** '''Blackwater Port''': City lying south of the Bay of Pearls.
** '''Carcyn''': Located between the Grey Woods and the Great River.
** '''Dan'Tonk''': Wesnoth's largest city, located in the center of the country, just west and north of Weldyn.
** '''Soradoc''': The northernmost border outpost of Wesnoth, controls the confluence of the Weldyn River and the Great River.
** '''Fort Tahn''': The southernmost border outpost, controls the north/south road crossing the River Aethen.
** '''Tath''': Important fort city north of Dan'Tonk, exerts control over the wilderness country around the east of the Brown Hills and north to the '''Ford of Abez'''.

* Notable land features:
** '''Gryphon Mountain''': Home of the fabled Gryphons
** '''Ford of Abez''': Shallow part of the Great River, it is usually controlled by Wesnothian forces
** '''Weldyn River''': It branches from the Great River and goes south
** Great Central Plain: Area bounded by Weldyn, Dan'Tonk, and Fort Tahn, this plain is Wesnoth's bread basket and home to most of its population
** '''Dulatus Hills''': These rolling hills bordering the Great Central Plain provide much of Wesnoth's livestock and agriculture
** Brown Hills: Wasteland surrounding Gryphon Mountain that is not well-populated and occasionally very dangerous.
** Horse Plains: Region of rolling plains just south of the '''Great River''', bounded by '''Glyn's Forest''' to the west and the '''River Weldyn''' to the east; the southern reach merges into the Central Plain. Home of the powerful Clans; the best horses in Wesnoth are bred here.
** '''Estmark Hills''': Largish range rising south of the Great River and east of the Weldyn River. The northernmost portion, nearest the '''River Weldyn''', has at various times been settled by Wesnothians, but the Kingdom's control is tenuous at best and banditry is common.
** '''Glyn's Forest''': Sometimes known as the Royal Forest, named for one of Haldric II's sons
** '''Gray Woods''': Large forest in the heart of the wilds of Wesnoth, located between Carcyn and Aldril and generally considered to be haunted
** Green Swamp: Large swamp in the heart of the wilds of Wesnoth, south of Aldril. (Not shown on the main map.)

=== Southwest Elven Lands ===
The Wood Elves are separate from those of the north, and have only intermittent relations with them and most other countries. Its borders are the Green Swamp to the northeast, the desert (not shown) to the south, and the Ocean to the west.
* Notable cities
** None known
* Notable land features:
** '''Aethen Forest''': The largest southern forest, it extends far to the southwest - much farther than is charted - and is home to elves

=== Elensefar ===
'''Elensefar''' is at times a province of Wesnoth, at times an independent country, and at times in a treaty federation with Wesnoth. Its borders are the Great River to the north, a loosely defined line with Wesnoth to the east, the Bay of Pearls to the south, and the ocean to the west. More information is found in the [[WesnothHistory|historical narrative]] of Wesnoth.

* Notable cities:
** '''Elensefar''': The capital, located on an island in the Great River delta
** '''Carcyn''': City on the Wesnoth-Elensefar border, disputed with Wesnoth
* Notable land features:
** '''Great River''': It is very wide at this point, and only ships can cross it.

=== Northlands ===

There is no government of the Northlands. Various groups of orcs, dwarves, barbarian men and even elves populate the region. The northern and eastern borders are not defined, the southern border is the '''Great River''', and the western border is the '''Great Ocean'''.

* Notable cities:
** '''Glamdrol''': An Orcish tribal capital
** '''Romyr''': Another Orcish tribal capital
** '''Wesmere''': The location of the Ka'lian - the Elvish Council
** Dwarven Doors: A mixed human/dwarven town in the region of Knalga in the southern Heart Mountains. A major trade center.
** Dallben and Delwyn: Human villages originally built by settlers who crossed the Great River during Wesnoth's Golden Age expansion. Now abandoned. The forested area northeast of '''Elensefar''', where these villages were located, was named the Annuvin province by men but was known by the elves as Wesmere.

* Notable land features:
** '''Heart Mountains''': A virtually impassable barrier between the river country and the Northern Plains.
** Heartfangs: the particularly forbidding stretch of high peaks southwest of '''Lake Vrug''' and north of the '''Forest of Wesmere'''. The most inhospitable and dangerous portion of the '''Heart Mountains'''; only hermits, madmen, and mages live there.
** '''Swamp of Dread''': a very large bog located between the '''Heart Mountains''' and the '''Great River'''. A notoriously dangerous place.
** '''Lake Vrug''': A large mountain lake whose river carves the only pathway through the Northern Mountains
** '''Arkan-thoria''': The river than comes out of Lake Vrug. This is the elvish name; among humans it is called Longlier.
** '''River Listra''': The south-running tributary of the Great River into which the '''Arkan-thoria''' empties.
** '''Lintanir Forest''': The southernmost portion of the Great Northern Forest, a gigantic wood whose eastern and northern boundaries are known only the elves. Their capitol, Elensiria, has only seldom been visited by humans.
** '''Great River''': The origin of this river is somewhere in the east of the northern lands

==== Wesmere====
The location of the Ka'lian - the Elvish Council in the Eastern part of the forest. The river Telfar flows through the forest. The Kal'ian is on an island in the Telfar. The River Telfar is crossed by the Northern Shallows, the Ford of Alyas, the Ford of Tifranur and the North Bridge. Villages surrounding the Ka'lian are named Telionath, Arthen, Arryn, Illissa, Viricon, Tireas, Essarn, Valcathra, Aelion, Elendor, Erethean. Other areas near the Ka'lian are Brightleaf Wood, Telfar Green (an opening in the forest), Dancer’s Green (an opening in the forest), Karmarth Hills, Westwind Wood (possibly the foothills of the Heart Mountains to the north east of Wesmere), Southwind Wood. East and outside are the forest are the villages of Dallben and Delwyn.

== Far North ==

http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/data/campaigns/Son_Of_The_Black_Eye/images/farnorth.png

Cold, harsh, and inaccessible, the Far North is the ancestral home of the Orcish Clannate. It lies north of the Heart Mountains, which the Orcs call the Haggid-Dargor and claim (without merit) as their own. To the east lie the Unaligned Tribes of the Wild Steppe, who fell out of the control of the Clannate, instead roaming with wild human barbarians and clashing with the High Elves of the North Plains (known as North Elves in human lands). The High Elves themselves reside further east, where it is rumored they rule a vast kingdom.

* Notable cities:
** Barag Gor, a city home to the Orcish Council
** Bitok
** Borstep
** Castelfrang
** Farzi
** Festog
** Grisbi
** Lmarig
** Melmog
** Prestim
** Tirigaz
* Notable land features:
** Swamp of Desolation
** Mountains of Dorth
** Mountains of Haag
** Green Forest
** Silent Forest
** Forest of Thelien
** River Oumph
** River Bork
** Wild Steppe

===Area around Tirigaz===
Featured in [http://wiki.wesnoth.org/Mainline_Campaigns#Dead_Water Dead Water].

http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/campaigns/Dead_Water/images/dead-water-map.png

* Notable cities:
** Tirigaz
** Jotha
**Agvorad
* Notable land features:
** Swamp of Desolation
** Mountains of Dorth
** Bilheld, a large island.
** A small island of coast of Bilheld

== The Southern Land ==
<tt>Where is this confirmed?</tt>

This is the land to the far south of wesnoth.
* Notable cities:
** Serrul: a peaceful city that excels at sea trade.
** Varrant: a prosperous trade city.
** Kesh: a powerful military city.
** Azen: capitol of the Azgar (a Expansionist clan with a strong military force)
* Notable land features:
** The Ashland Desert: a long and hot desert that leads to Wesnoth.

== The Green Isle ==
The geography features in [http://wiki.wesnoth.org/Mainline_Campaigns#The_Rise_of_Wesnoth The Rise of Wesnoth]. In this place names are placed over the map below as overlays.
http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/data/campaigns/The_Rise_Of_Wesnoth/images/story/the_green_isle.png
=== Wesfolk Land ===
This is where the Wesfolk live, with their Lich overlords. The boundary between it and the Islefolk land is the hilly area running south-west to north-east. The Wesfolk land is in the north-west. Little is known about what happened to the island after Haldric left.
* Notable cities:
** Jevyan's Haven: The capital of the Wesfolk, where Jevyan reigned; presumably where the gates to orcland were opened
* Notable land features
** None. (its not a very detailed map, is it? :) )

=== Islefolk Land ===
This is where the Islefolk (Haldric's folk) live. The boundary is the same as that of the Wesfolk; the islefolk land is to the southeast.
* Notable cities:
** Blackmore: {??}
** Clearwater Port: {??}
** Southbay: {??}
* Notable land features:
** None. (see Wesfolk land)

== Campaign References ==

This section collates specific facts about geography asserted in the the text of mainline campaigns, implied by map dots (track) or by features on a battle map (map). It aims to be complete as to locations on the main map and identifiably adjacent to it. Two groups of off-map locations are confined to single campaigns, the Green Isle in ''The Rise of Wesnoth'' and the Far North in ''Son of the Black Eye''; those locations are not listed here.

=== Heir To The Throne ===

Konrad was raised in the '''Aethenwood''' (track, ''The Elves Besieged''). He returns to the mainland very near the location where Haldric the Great first landed in 1YW. (map, ''Bay of Pearls''). The fight with Muff Malal takes place on the peninsula north of the '''Bay of Pearls''' (track, ''Bay of Pearls''). The city of '''Elensefar''' is actually located on a large island in the mouth of the '''Great River''' (map, ''The Siege of Elensefar''). The crossroads fight takes place where the roads from '''Carcyn''', '''Dan'Tonk''' and '''Fort Tahn''' meet (track, ''Crossroads''). Konrad meets Li'sar on the road between '''Dan'Tonk''' and '''Carcyn''' (track, ''The Princess of Wesnoth''). Konrad fights undead in the Brown Hills southeast of '''Gryphon Mountain''' (track, ''Valley of Death''). The track for ''Gryphon Mountain'' unsurprisingly lands on the '''Gryphon Mountain''' map feature; equally unsurprisingly, the track for ''Ford of Abez'' lands on the '''Ford of Abez''' map feature.

North of the '''Great River''' this campaign is our basic textual evidence for several important features. The country around the easternmost tip of the '''Swamp of Dread''' is described as "abundant pine forests nestled in rolling foothills" (track and text, ''Northern Winter'') and, at least during the Turmoil of Asheviere, is inhabited by orcs. Dwarven Doors and Knalga are located in the center of the southern arm of the Heart Mountains, south-southeast of Lake Vrug (''The Dwarven Doors''). Lionel, the Lost General, is found in an orcish warren at the northern edge of the southern '''Heart Mountains''', north-northeast of Knalga and adjacent to the valley of the Arkan-thoria (''The Lost General''). Konrad re-encounters Li'sar north across that valley in the foothills of the northern '''Heart Mountains''' (track, ''Hasty Alliance''). The Scepter of Fire is found in those same foothills a bit further east and south, just north of the southernmost bend of the '''Arkan-thoria''' (''Scepter of Fire'').

Konrad's party travels southeast through the caverns, under the '''Arkan-thoria''', to just south of a northward bend of the river (''A Choice Must Be Made''). Kalenz says that this river is called 'Longlier' by men and 'Arkan-thoria' by the Elves. He further says that the homeland of his people lies to the east and north. Kalenz identifies their location at the easternmost edge of the southern '''Heart Mountains''' (track, ''Snow Plains'') as "...once the home of my people. We left here centuries ago" (text). In the next scenario, the North Elves are contacted at the confluence of the '''Arkan-thoria''' and the '''Listra''' (track, ''Home of the North Elves''). Konrad's party take refuge in Emetria, an Elven castle located just within the border of the southern lobe '''Lintanir Forest'''. ''The Elven Council'' takes place in the elven capital of Elensiria, location not specified.

Konrad crosses the '''Great River''' into Wesnoth just north of '''Soradoc''' (''Return to Wesnoth''). The country between the Elven forests and the river is inhabited by, among other things, "hermit mages" (text). He then crosses the river into the '''Estmark Hills''' hills east of the '''Weldyn River''' (track, ''Test of the Clans'').

Neither the '''Estmark Hills''', nor the '''Heart Mountains''', nor the swamp between them and the '''Great River''' are named in this campaign, but one scenario title refers to the latter as ''Swamp of Dread''.

Continuity problems: the map for 'The Princess of Wesnoth' is difficult to reconcile with the track location; the lake to the south should be large enough to show on the main map and is difficult to fit in a valley in the Brown Hills.
Likewise, the map for ''Home of the North Elves'' shows only an east-west river probably too small to be the '''Arkan-thoria''', and not the '''Listra''' that it should flow into.

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:HttT#Labels map labels]

=== A Tale of Two Brothers ===

This campaign has a tracking map. In text, the village of Maghre is described as being in the "western reaches of Wesnoth" (''Rooting Out a Mage''). In ''The Chase'', the haunted forest is identified as the Gray Woods.

=== An Orcish Incursion ===

This campaign has a map and a journey track. No places are named other than '''Wesmere'''; the action takes place north and west of there. A pass that is bottleneck route through the northern mountains figures in the action.

=== The South Guard ===

This campaign takes place off the main map and has its own background map.

We know from it that the city of Westin is located southwest of '''Fort Tahn''' (track, ''Born To The Banner'') and is capital of the frontier province of Kerlath (text), also that the Aethenwood is to the west (text).

There is no map track after the second scenario. We learn that south of Westin , Kerlath is bounded by dense woods, "a bastion of the ancient heart forest of the Great Continent so dense and gloomy that even elves forbore from dwelling there."
(''Born to the Banner'') South of it an unspecified distance lies the elven Vale of Tears, and much further south of that the Black River, of which Etheliel says "No elf, still living, has crossed it."

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:TSG#Labels map labels]

=== Liberty ===

This campaign uses a modified version of the main Wesnoth map for tracking. The map shows the villages of Dallben and Delwyn, and some small patches of forest, between the forest of Wesmere and the ocean; also it labels the '''Gray Woods'''. Text (''The Raid'') identifies this as the province of Annuvin, a frontier area of Wesnoth. It is clear that '''Elensefar''' is the chief city of Annuvin.

Baldras and his party travel south to '''Elensefar''' (track, ''A Strategy of Hope''). From there they go upriver to '''Carcyn''' (track, ''Hide And Seek''), and south to the '''Gray Woods''' (track, ''The Gray Woods''), then south on the road to ''Aldril''. The campaign finishes at '''Halstead'''. In the Epilogue, there is a reference to villagers fleeing southwest to settle on the '''Three Sisters'''.

The scenario maps feature [http://wiki.wesnoth.org/CampaignDialogue:L#Labels map labels]

=== The Rise of Wesnoth ===

This campaign has its own tracking map for the Green Isle, which is our only actual source of information about the Green Isle's geography. The only Great Continent location of interest is the Ka'lian, which has the same location in the '''Forest of Wesmere''' that it does in other campaigns.

The lady Jessene uses the term "Old Continent" to describe the ancestral home of her people, and implies that it lies in "the far West".

=== The Legend of Wesmere ===
This campaign uses a [http://wiki.wesnoth.org/Geography_of_Wesnoth#LOW_Custom_Map modified version of the main Wesnoth map] for tracking. The map shows far fewer settlements with the notable addition of a castle settlement in the '''Swamp of Dread''', called '''Saurgrath''' (the location of ''The Saurian Treasury'').

The map track for ''Hostile Mountains'' shows Kalenz starting from the '''Lintanir Forest''' and moving across the easternmost '''Heart Mountains''' to a spot on the Arkan-thoria. They travel to '''Wesmere Forest''' (''The Ka'lian Under Attack''); the map tracking runs almost lengthwise through the '''Heart Mountains'''. The Ka'lian is near the northeast edge of '''Wesmere forest'''; the Elvish treasury is further west (track, ''The Elvish Treasury''). The Saurian treasury in the westernmost foothills of the '''Heart Mountains''' (track, ''The Saurian Treasury''); Kalenz and his men avoid the direct route from it back to Wesmere by going north from it and that they return via the eastern approaches to Wesmere. On the way, they re-encounter Olurf in the southeastern reaches of the '''Heart Mountains''' (''Acquaintance In Need''). They march back to the north edge of '''Wesmere Forest''' (track, ''Elves' Last Stand'').

In ''Council of Hard Choices'' we learn that the mage Crelanu lives in "the mountains of Thoria". The route north goes over the mountains to the "Arkan-thoria" (track: ''Bounty Hunters''), the name is confirmed in text. The mountains of Thoria themselves are just north of the valley of the '''Arkan-thoria''' (track, ''Cliffs of Thoria''). Crelanu's keep is well into the northern '''Heart Mountains''', right at the northern edge of the map (track, ''Battle of the Book'').

Kalenz and friends "return to the Ka'lian" (''News From The Front''); then to orcish forces are "encamped south of the '''Great River''', and have surrounded the fortified human settlement of Tath". The track for ''Breaking the Siege'' indicates that the killing of the Great Chief took place at the southeastern tip of the '''Heart Mountains''' and that ''Breaking the Siege'' takes place on the '''River Listra''', just north of the confluence with the '''Arkan-thoria'''.

The remaining scenarios convey no new information; the track points are all east of the '''River Listra''' between it and the '''Lintanir Forest'''.

Kalenz's home map has big water to the east. This has to be a lake off the NE corner of the main map, emptying into the main course of the Listra.

The campaign maps feature [http://wiki.wesnoth.org/CampaignDialogue:LOW#Labels map labels]
====LOW Custom Map====
http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/data/campaigns/Legend_of_Wesmere/images/legend-of-wesmere-map.png

=== Eastern Invasion ===

This campaign has its own map, with the River Guard outposts shown, and a tracking map. The intro describes the location of the River Guard posts on "the near bank of the Weldyn", alludes to trouble in the Estmarks, and refers to "raiders from the great desert", location unspecified.

One path from ''An Unexpected Appearance'' leads west, the other east (text). But the western path forces Gweddry and his men to travel north, into "known forest country just south of the Great River" (text). On the other branch, Mal-Ravanal's capitol is in the '''Bitter Swamp''' (''Mal-Ravanal's Capitol''); the party flees "west and north" until they find a "low pass in the Estmarks, and [are] greatly relieved to see the valley of the Weldyn open before them." (text). In ''Undead Crossing'', Gweddry's party crosses the '''Great River''' to the north (text). One of the following scenarios is named '''Lake Vrug'''. In ''Drowned Plains'' the party goes south to the '''Great River''', crosses it, and Owaec announces that they have entered the Horse Plains. '''Weldyn''' is on the map of the final scenario.

The Orc kings stronghold map has [http://wiki.wesnoth.org/CampaignDialogue:EI#King_Dra-Nak.27s_City_.28labels.29 map labels]

=== The Hammer of Thursagan ===

This campaign has a tracking map. It begins at Knalga, and the heroes travel generally eastwards. There are no other specific geographical references in it, except to "the High Pass" about halfway between Knalga and Kal Kartha.

=== Descent Into Darkness ===

This campaign has a journey track, and a map on which the the "northern border town of Parthyn" (''Saving Parthyn'') appears. An eartly fight (''Orc War'') takes place near the river Longlier (the '''Arkan-thoria'''). This is denoted by a [http://wiki.wesnoth.org/CampaignDialogue:DID#Places_.28labels.29 map label]. Later in the campaign (''Return To Parthyn'') it is specified that Malin follows a trail south across the '''Great River''' and west to Parthyn. Part of the action (''A Small Favor'' and three sequels) takes place in the city of '''Tath'''.

=== Scepter of Fire ===

This campaign has a tracking map.
The campaign begins in "the foothills of Knalga" (text, ''A Bargain Is Struck'') when Haldric II rides north from there from the '''Ford of Abez'''. Rugnur looks for Thursagan in "the northern wastelands", which is near the coast north-northeast of Rumyr (''Searching for the Runecrafter''). Much of the rest of the campaign takes place in the old eastern mines just north of the Arkan-thoria; this is where the Scepter will be found in ''Heir To The Throne''. Alanin's running battle with the outriders takes place just north of the '''Ford of Abez''' (track, ''Outriding the Outriders'').

(Note: earlier versions of SoF were set in a completely different location in the far western foothills of the Heart Mountains. This was an error by some hapless chronicler.)

=== Son Of The Black Eye ===

This campaign takes place off the northern edge of the main map and has its own tracking map (see "The Far North") above. There is no reference to anywhere on the main map other than Dwarven Doors, and that does not indicate either distance or direction.

=== Dead Water ===

This campaign has a tracking map. It takes place on and near the coast of the Far North; the port city of Tirigaz, mentioned in '''Son of the Black-Eye''', is a locale of one scenario. We learn that one of the small islands off the coast is called Bilheld and is inhabited by drakes.

=== Delfador's Memoirs ===

This campaign has a tracking map. Its scenario locations are in general well known from other campaigns. The campaing maps feature some [http://wiki.wesnoth.org/CampaignDialogue:DM#Places_.28labels.29 map labels]

=== Northern Rebirth ===

This campaign has a tracking map. It begins in Dwarven Doors. No distances or directions to places elsewhere in canon are indicated.

=== Under The Burning Suns ===

This campaign has no tracking map. It takes place long after the fall of Wesnoth and none of its locations can be clearly tied to anywhere in the main map.

== See Also ==

* [[WesnothHistory]]

[[Category:World of Wesnoth]]

TerrainGraphicsWML

2015-07-28T19:18:34Z

Zookeeper: Documented [variant] has_flag=

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''x''','''y''': constrains the rule to given absolute map coordinates. Primarily useful to place map-specific features.
* '''mod_x''','''mod_y''': {{DevFeature1.13|1}} constrains the rule to absolute map coordinates which are multiples of the given values. For example, mod_x=4 would only match locations with an x coordinate of 4, 8, 12, 16, etc.
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches.
** '''name''': for animated terrain this takes the form of a comma separated list of images with durations specified after ':'. A square bracket expansion can also be used as in AnimationWML (see in example below).
** '''set_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
**** '''has_flag''' {{DevFeature1.13|1}} comma-separated list of flags that the tile must have for this variant to apply.
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version.<br>For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne".<br>Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

To define an animated campfire at coordinates (4,5) with files "misc/fire-A01.png" to "misc/fire-A08.png" with an inter-frame transition time of 140, the following can be placed at the scenario top level (adapted from the CAMPFIRE macro):

[terrain_graphics]
x,y=4,5
[tile]
x=0
y=0
[image]
layer=0
name="misc/fire-A[01~08].png:140"
[/image]
[/tile]
[/terrain_graphics]

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

TerrainGraphicsWML

2015-07-28T19:14:43Z

Zookeeper: Documented [terrain_graphics] mod_x= and mod_y=

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''x''','''y''': constrains the rule to given absolute map coordinates. Primarily useful to place map-specific features.
* '''mod_x''','''mod_y''': {{DevFeature1.13|1}} constrains the rule to absolute map coordinates which are multiples of the given values. For example, mod_x=4 would only match locations with an x coordinate of 4, 8, 12, 16, etc.
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches.
** '''name''': for animated terrain this takes the form of a comma separated list of images with durations specified after ':'. A square bracket expansion can also be used as in AnimationWML (see in example below).
** '''set_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version.<br>For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne".<br>Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

To define an animated campfire at coordinates (4,5) with files "misc/fire-A01.png" to "misc/fire-A08.png" with an inter-frame transition time of 140, the following can be placed at the scenario top level (adapted from the CAMPFIRE macro):

[terrain_graphics]
x,y=4,5
[tile]
x=0
y=0
[image]
layer=0
name="misc/fire-A[01~08].png:140"
[/image]
[/tile]
[/terrain_graphics]

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

TerrainGraphicsWML

2015-07-28T19:13:15Z

Zookeeper: Documented [terrain_graphics] x= and y=

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''x''','''y''': constrains the rule to given absolute map coordinates. Primarily useful to place map-specific features.
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches.
** '''name''': for animated terrain this takes the form of a comma separated list of images with durations specified after ':'. A square bracket expansion can also be used as in AnimationWML (see in example below).
** '''set_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings or square bracket expansion as in AnimationWML. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): Tells engine to start animation at random point instead of at the beginning for every tile
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version.<br>For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne".<br>Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

To define an animated campfire at coordinates (4,5) with files "misc/fire-A01.png" to "misc/fire-A08.png" with an inter-frame transition time of 140, the following can be placed at the scenario top level (adapted from the CAMPFIRE macro):

[terrain_graphics]
x,y=4,5
[tile]
x=0
y=0
[image]
layer=0
name="misc/fire-A[01~08].png:140"
[/image]
[/tile]
[/terrain_graphics]

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

Creating Unit Art

2015-07-19T13:01:51Z

Zookeeper: Fixed color depth instruction from 24-bit to 32-bit

Here's the information needed to start doing units art for Wesnoth. Please update the wiki with links to examples and other tips and tricks realted to unit art. This page started from [http://www.wesnoth.org/forum/viewtopic.php?p=104809#104809 this forum thread].

== The Medium ==

The medium used to create unit art is known as 'pixel art'. If you do not understand what pixel art is, or if you have only a general understanding of what it is, I suggest reading [http://www.pixeljoint.com/forum/forum_posts.asp?TID=11299 The Pixel Art Tutorial] by Cure. It is a tutorial comprised of a series of sequential forum posts on the www.pixeljoint.com forum and gives an in-depth overview of pixel art, explaining in detail what pixel art is and what it is not. Using other mediums (such as brush art) to create unit art is fine if you are creating unit art for [[Glossary|UMC]] add-ons (although it is still strongly recommended that you use pixel art for the sake of consistency with mainline units), but only units drawn in pure pixel art will be accepted into mainline.

== Basic unit image specifications ==

Wesnoth can only use two kinds of graphic files: PNGs, or JPEGs. JPEGs aren't suitable for unit images, because they can't store transparency data (and are lossy). Because of this, we always use PNGs for unit images.
*Final format: transparent PNG
** Color depth should be 32-bit (8 bits per RGBA channel). This may be listed for example as "PNG-32" or "8-bit RGBA".
** Be aware that "Indexed color", "color map", or "PNG-8" is a different format. Although it might work in a buggy way, we strongly recommend you not use these.
* Canvas size is 72 x 72 pixels (it can actually be slightly wider, and can fit in the area of a hex and its immediately surrounding tiles, but try not to do this if at all possible, because it has performance and graphical glitch issues).
*All but exceptionally large units should be contained in the hex if possible - the white in the template shown at right: http://forums.wesnoth.org/download/file.php?id=4334&type=.png
*Compare the size of your unit to the size of similar existing core units.
*<div style="float:right; padding:1ex; margin:1ex; border: thin dotted; font-size:80%;">http://forums.wesnoth.org/download/file.php?id=60404&type=.png</div>For oversize units, there are limitations with respect to the terrain system and asthetics. Sprites that are much bigger than the hex tend to end up getting partially obscured by terrain in inconvenient places and look bad. If you want everything to be always visible or believably covered then the black area in the picture is safe. You can usually exceed this to the left and right without much trouble, but going down is problematic with the great tree and stands out. The gold hex represents the hex the unit is actually in. Also, making units too large will hide those behind it, so even though the appearance will be correct in the entire black area, you will want to leave more than half of each of the hexes outside the gold one visible so as not to make other units vanish. [http://forums.wesnoth.org/viewtopic.php?f=23&t=38203&p=546367#p546331]
*Light comes from the artist's (''not'' the unit's!) upper right (for shading and highlights)
*Unit must look in the lower right (again, the artist's lower right, not the unit's) direction
*Units are centered horizontally
*Unit's feet are positioned around 55 pixel down from the top edge of the canvas, lower for taller units if necessary
*Shadows at 60 opacity, using a specific dark blue color (see [[Creating_Shadows_Under_Units|Creating Shadows Under Units]]).
*Outlines should be used, made with a darker, but similar color to what they're surrounding, this makes the unit feel bigger then the amount of pixels you'd use for the same with a black outline. Note that pure black (RGB #000000) should ''never'' be used to outline a sprite.
*Use consistent names for your files, beginning with the unit name, so that they are kept together when browsing the files. Try to imitate the naming scheme used for mainline units.

== Unit animation specifications ==

You can have as many frames for animations as you like, and in fact, for any given cue, you can have more than one animation, which will be randomly chosen by the game. Images and animations must be done for:
*base frame (1 frame)
*attack for each type (at least 4 frames, about 6 frames is optimal depending on the type of attack and the weapon(s) involved)
*directional attacks (generally are desired for any attack that's a straight motion, rather than a slash. I.e. spears and thundersticks)
*defense (usually 2 frames long not including the base frame, separate animations may be drawn for ranged and melee defense animations)

== Additional Notes ==

*Test early with different backgrounds. Go to your game terrain files, pick, say, 3 terrains, preferably with different colors, and have a look what they look like against the background, because that way if you have used alpha channels, it may look better in game than as the average standard sprite.

*Test your unit early in the game. Replacing an existing unit graphic with yours is the fastest way (be sure to make a copy of the originals so you don't lose them.)

*Test your unit next to mainline units in-game. This will help you ensure that your unit matches the style and proportions of the mainline units as closely as possible.

== See Also ==
* [[BuildingUnits]]
* [[Create]]
* [[Create Art and Music]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]

MapLocalization

2014-06-21T11:13:24Z

Zookeeper: Removed note of both black and yellow labels being required

'''This page is a work in progress'''

Like the old maps, the new-style maps can be localized, but the intended method for doing so is quite different.

=== Overview ===

However, the workflow for localizing a map is simple: you create an image which contains the localized labels on a transparent background as simple text, no post-processing effects needed. In GIMP, you then add that image to a corresponding .xcf file as a new layer, and run a script. The script creates an overlay image which covers up the english labels, adds your localized labels and applies a bunch of post-processing effects to them in order to make them look identical to the english labels. All you need to do is to check the output and save.

=== Step-by-step instructions ===

==== Preparations ====

1. If you don't have GIMP, install it.

2. Download the [https://github.com/wesnoth/resources/tree/master/image-localization/maps/wesnoth-map-localization.scm wesnoth-map-localization.scm script] and place it into a script directory recognized by GIMP. You can view and configure the script directories in GIMP's preferences (Preferences -> Folders -> Scripts). If you already have GIMP running, you need to use '''Filters -> Script-Fu -> Refresh Scripts''' to make it recognize the newly added script. In the Filters menu, you should now see a filter category called "Wesnoth", and inside it "Map Localization". However, we don't need it yet.

3. Download the [https://github.com/wesnoth/resources/tree/master/image-localization/maps/ localization.xcf for the map you're localizing].

Now you're all set to begin.

==== Localization ====

# Open the localization.xcf you've downloaded. It contains a bunch of layers needed by the localization script, but at this point all you need is the layer called "label placement guide". It's a version of the map without any perspective or displacement effects added, and it is the one onto which you need to place the localized layers.
# Create a new layer which includes the localized labels, positioning them using the aforementioned layer as a guide. The positions or orientation or curving of the labels does not need to match the english labels in any way. Place them in a way which you think looks good.<br>The requirements for the labels are simple: black text should be pure black, whereas yellow labels on forests should have the RGB value 185,155,85. The script gives you a little bit of leeway so you don't have to stress over very small color deviations, but don't do it intentionally. Background should be transparent.<br>''Note that you can use whatever graphics application you want in creating your labels, as long as you can import the result into GIMP so that it meets the above requirements.''<br>
# Add the layer containing your localized text into the same localization.xcf file and name it "labels". Don't mess with the other layers.
# If ''labels'' and ''label placement guide'' are layer groups, merge them down to single layers. Notice as well that the expected layer names are case-sensitive, so for example ''Labels'' will not work.
# Run the script by choosing Filters -> Wesnoth -> Map Localization. The script will create a new image, and produce the output there. This will take a moment, perhaps as much as a minute or more on a slow computer, and for a few seconds it might seem like nothing is happening.
# You should now have a new image with a single layer called "localized overlay". Inspect that everything's ok by adding the original english map as a new layer underneath the overlay; the english labels should be covered up, the localized labels in place and there should be no glitches anywhere. Export the image to PNG (just remember to hide/delete the english map layer first!) and you're done. In the PNG export dialog, uncheck the option "Save color values from transparent pixels" to get the file of expected size (~100-300 KiB; if the option is not unchecked, it is over 2 MiB).

===== Final notes =====

If there are labels which you don't need to localize, then first of all, don't bother including them among your localized labels. Then, once you've generated the final overlay, simply erase the parts which cover up the original english label.

===== Text sizing =====

These are the text sizing rules that have been used on the english maps. Depending on your language, you may want to break some of them.

Major geographical features or other large areas which extend beyond the map edges (including forests): 28px small caps, tracking ~200.
''Note that these are font sizes for Photoshop. GIMP has slightly different text tools and does not have small caps effect. Small caps effect can be reproduced by using caps with 30px for the first letter and 20px bold for the remaining letters. You might also need to make all text bold in Gimp so it will be legible. The corresponding font tracking in GIMP is 5.0.''

Large geographical features: 22px normal or small caps.

Minor geographical features: 18px normal.

Major rivers: 20px, tracking ~200.

Small rivers: 18px, tracking ~200. For names like "R. Weldyn", note that periods are very small in Monotype Corsiva and get very close to the preceding R; I suggest giving the . a size of 24-30px and removing the following space. Other solutions can work too.

Capital cities: 24px normal.

Other major cities: 20px normal.

Small cities: 16px normal. You might need to increase this to 18px for legibility.

Large forests: 24px normal.

Small forests: 18px normal.

===== Text orientation and curving =====

In the english maps, names of large geographical areas and rivers are often curved. River names usually follow the shape of the river, and names of large features such as "Heart Mountains" are curved to roughly match the shape of said feature.

All of the above is optional. You do not need to match the english labels in shape and location. If for some reason you need to, you can even omit some labels or add completely new ones.

===== Title screen map =====

The title screen map is identical with the ''Heir to the Throne'' campaign map. Localize the map for ''Heir to the Throne'', create a copy of the overlay and rename it to 'titlescreen--overlay.png', then place it in ''\data\core\images\maps\l10n\<language iso code>'' and you're done.

[[Category:Translations]]

Designing weapons and armour

2014-04-30T13:26:34Z

Zookeeper: Updated link url

by Zookeeper

Often one sees that someone draws these things looking all silly. Slight exaggeration of weaponry and such is of course fine in a fantasy setting, but it's not uncommon at all to go over the board and draw something that couldn't function in reality at all. This mostly applies to portraits and other realistic imagery, not really unit graphics as such.

Now, my point is simply: you can make weapons and armour be flashy and cool while keeping them very realistic, and a real-world reference also helps you to get things functional without having to think what kind of sword handle would work and what wouldn't, for example (and, no offense to artists drawing fantasy stuff, but that usually goes a bit awry), and that there are plenty of references available. So even if you don't feel the need for the weapons you draw to look realistic, having some references still helps to actually make it look good (in the same way as having a reference when drawing a person makes it much easier to get it look right and good).

For this purpose, I thought I'd go through some related sites I know of and post some links here. These are armouries, general information/review sites, etc, which contain good pictures of historical arms and armour. Mostly (if not all) are only european stuff though (which sort of fits with at least the mainline Wesnoth setting), but that's all I had available right now.

* http://www.armouronline.com/ - the full body armour section is good, weapons are generally crappy here.
* http://www.myarmoury.com/ - hard to navigate, but contains a lot of good pictures, if you take the time to find them. The "reviews" page is a good place to start from.
* http://www.lutel.eu - quite a number of all sorts of weapons in the catalog (especially the polearms and such look nice).
* http://www.darksword-armory.com/ - a collection of often historically accurate weaponry
* http://www.by-the-sword.com/ - various things
* http://www.siue.edu/COSTUMES/history.html - a site with lot of pictures of clothing from different eras and areas, from 19 century engravings. The scans could be of higher quality, but you can find plenty of stuff for reference/inspiration for fantasy clothing. Many of the same pictures can also be found in a book ''A Pictorial History of Costume'' (Pepin Press, no author).

Feel free to post your additions (especially to the type of items not covered on these sites), too, since we don't have much here yet.

[[Category: Art Tutorials]]

BinaryPathWML

2014-03-11T19:02:57Z

Zookeeper: Added an example

{{WML Tags}}
== the toplevel [binary_path] tag ==

This tag is used to recognize more than one directory as containing images, music, and sound. It only has one key:
* '''path''': a directory. When an image is not found it the normal ''images'' directory, it will be looked for in '''''path'''/images''. Similarly, music will be looked for in '''''path'''/music'', and sound in '''''path'''/sound''.
Notice that '''''path''''' is still relative to the main Wesnoth directory.

[binary_path] should only be used where necessary. For example a multiplayer era should have its [binary_path] inside an #ifdef MULTIPLAYER instead of outside it in order to avoid possible clashes with single-player content.

== Example ==

To enable the game to find images, sounds and music in the add-on MyAddOn:

[binary_path]
path=data/add-ons/MyAddOn
[/binary_path]

When the game looks for an image '''''units/humans/footman.png''''', it'll now be able to find and use the file '''''MyAddOn/images/units/humans/footman.png'''''.

== See Also ==

* [[ReferenceWML]]

[[Category: WML Reference]]

SoC People to bug on IRC

2014-02-07T17:16:35Z

Zookeeper: Moved many people to a separate "inactive" list and updated my own entry

{{SoC2014}}

== People to bug on IRC ==
We have prepared a list of people with their "area of competence". This is to give you an idea on which areas those people can be of help for you. Of course you should always just ask in the IRC chan, but those are the most likely ones to answer questions in the respective area. And here is the list:

=== boucman ===
As our "patch monkey" he accustomed to critiquing patches of every kind. Beside this, he knows many areas of the game due to working on applying patches. He is particularly used to answering question from new coders, and doesn't mind explaining trivial stuff. He was the one who started the "two patches, you're in" policy and the ReferenceWML part of the project.

=== Crab_ ===
iurii chernyi (Crab) has joined the team in 2009. He restructured Wesnoth AI as part of GSoC-2009, and is an expert on all aspects of current Wesnoth AI codebase. So, he's the person to ask about anything in '''src/ai'''. He also knows much about campaign units/leaders persistence.

=== Gabriel Morin (gabba) ===

gabba joined the team in 2010 where he participated in GSoC, and is the conceptor and maintainer of Wesnoth's planning system, codenamed "Whiteboard".

=== happygrue/Wintermute ===

Has been involved with multiplayer balance and testing for a number of years. Currently working on balancing the default+khalifate era, but interested in, and often available for, testing various aspects game play or mechanics. A good person to bug about getting feedback from the multiplayer community about any relevant issue.

=== ilor ===
2008 GSoC student, worked on and maintains the new map editor in Wesnoth 1.5/1.6/1.7. Has some fairly recent experience with getting "in" the Wesnoth codebase.

=== Karol Nowak (grzywacz) ===
Two years he participated at GSoC as a student, so he will understand the situation of GSoC students. Beside this he is our top expert on Wesnoth for embedded devices as he worked on the gp2x support.

=== loonycyborg ===
Maintainer of Wesnoth's SCons build system and windows packager. Might also help out with other buildsystems.

=== Mordante ===
Many of the possible projects involve the code for which he is an area expert. Also, many of the possible projects currently listed on the ideas page require GUI parts to work. Mordante is currently busy rewriting the old gui engine, he will be our expert there as well as already being our area expert for the terrain engine. He also has limited experience with boost asio.

=== Nils Kneuper (Ivanovic) ===
He is doing nothing special, he just does some "administrative work" like packaging fresh tarballs when it is time for them and works on setting up any kind of deadlines and timetables related to releasing. He has administrative powers in most areas, no matter if website, forum or IRC. Beside this he uploads translation updates, tries to communicate with the translation teams when it is required and translates a little bit himself every now and then. But in general he is not a real expert in anything, just has a look at things that come up and redirects people to the correct contacts.

=== Noy ===
Noy is an oddity among developers; he's got no coding skills whatsoever and possesses a limited understanding of computers, which is illustrated by his difficulty operating a Mac. Instead, Noy makes his contribution in gameplay and multiplayer design, drawing upon his background in social sciences research, military strategy and playing games online, to understand the effects of development on the playing community behavior. Along with Soliton, Noy is a useful conduit to discuss any issues in this area.

=== shadowm ===
He has been around since late 2007, and has worked in many areas of the game, including WML event commands handling, image path functions, and the add-ons client code. As an add-on content developer, he also knows a lot about the WML language itself (preprocessor, syntax) and the functionality available in single-player campaigns.

=== Soliton ===
He knows our MP server setup best. Beside this he has already done a lot of work on the MP server himself. So he probably has most knowledge about it and, being one of our MP-developers, might provide important help from the perspective of the MP player community and what is needed there.

=== zookeeper ===
Has been around for a long time and has at least a passing familiarity with most things outside the engine code, music and Lua. Maintains a large part of the mainline campaigns and knows the WML language well. Can be contacted when it comes to anything related to WML, gameplay and scenario design, or the mainline content in general.

== Inactive people ==

These people are currently not actively participating in development and are likely not available to help. You can always try, of course. They may also not be entirely up-to-date regarding their areas of expertise anymore.

=== Dave alias Sirp ===
Sirp started Wesnoth and is our lead developer. He is currently our C++ expert and is also the one that is working on the new Formula AI. Any questions regarding the formula AI should be directed to him.

=== Dragonking ===

He is one of our best Wesnoth players, and understands the various strategies well. He has also programmed much of the Wesnoth Formula AI system and understands it well.

=== Eric S. Raymond (ESR) ===
ESR is our project toolsmith; he has written several tools that semi-automate various aspects of WML maintenance. While most of our developers/designers concentrate on either the C++ core or WML but not both, he has a balanced understanding of both levels and may be helpful in helping students develop a grasp of the overall architecture. Finally, he did the last overhaul of the Wesnoth UI and understands UI design principles; he is well-equipped to guide students working in that area.

=== Sapient ===
This developer started working on the GUI and widgets, but recently he focused more on improving the internal mechanics of the WML engine such as variable look-ups and filtering. Sapient is not as active anymore but he does come one IRC in the evenings (U.S.A.). He has touched-up many areas of the code in small ways over time, thus he has a good general knowledge of the C++ code and also has worked a little on some python maintenance scripts.

=== YogiHH ===
Since he is the developer who know most about building under Windows, he will probably be really helpful. Either if the student comes from the Windows side, or to help test resulting work to make sure that it does work on Windows and, for the case that it does not, to show them where problems are.
YogiHH also knows quite a bit about the game engine and everything that has to do with replays and savegames.

=== Mythological or Rhuvaen ===
As our leading WML experts those are to be contacted when it comes to anything related WML problems since they know this stuff best. They do maintain most of the campaigns and improve them whenever they have a good idea for changes.

MediaWiki:Deletereason-dropdown

2013-03-24T13:25:45Z

Zookeeper: Reverted previous edit since it didn't do anything after all

*Common delete reasons
** Author request
** Copyright violation
** Vandalism

MediaWiki:Deletereason-dropdown

2013-03-24T09:23:41Z

Zookeeper: Added spam as a drop-down delete reason

*Common delete reasons
** Author request
** Copyright violation
** Vandalism
** Spam

MapLocalization

2013-02-20T20:34:36Z

Zookeeper: Fixed broken link markup

'''This page is a work in progress'''

Like the old maps, the new-style maps can be localized, but the intended method for doing so is quite different.

=== Overview ===

However, the workflow for localizing a map is simple: you create an image which contains the localized labels on a transparent background as simple text, no post-processing effects needed. In GIMP, you then add that image to a corresponding .xcf file as a new layer, and run a script. The script creates an overlay image which covers up the english labels, adds your localized labels and applies a bunch of post-processing effects to them in order to make them look identical to the english labels. All you need to do is to check the output and save.

=== Step-by-step instructions ===

==== Preparations ====

1. If you don't have GIMP, install it.

2. Download the [http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/ wesnoth-map-localization.scm script] and place it into a script directory recognized by GIMP. You can view and configure the script directories in GIMP's preferences (Preferences -> Folders -> Scripts). If you already have GIMP running, you need to use '''Filters -> Script-Fu -> Refresh Scripts''' to make it recognize the newly added script. In the Filters menu, you should now see a filter category called "Wesnoth", and inside it "Map Localization". However, we don't need it yet.

3. Download the [http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/maps/ localization.xcf for the map you're localizing].

Now you're all set to begin.

==== Localization ====

1. Open the localization.xcf you've downloaded. It contains a bunch of layers needed by the localization script, but at this point all you need is the layer called "label placement guide". It's a version of the map without any perspective or displacement effects added, and it is the one onto which you need to place the localized layers.

2. Create a new layer which includes the localized labels, positioning them using the aforementioned layer as a guide. The positions or orientation or curving of the labels does not need to match the english labels in any way. Place them in a way which you think looks good.

The requirements for the labels are simple: black text should be pure black, whereas yellow labels on forests should have the RGB value 185,155,85. The script gives you a little bit of leeway so you don't have to stress over very small color deviations, but don't do it intentionally. Background should be transparent.

''Note that you can use whatever graphics application you want in creating your labels, as long as you can import the result into GIMP so that it meets the above requirements.''

3. Add the layer containing your localized text into the same localization.xcf file and name it "labels". Don't mess with the other layers.

4. Run the script by choosing Filters -> Wesnoth -> Map Localization. The script will create a new image, and produce the output there. This will take a moment, perhaps as much as a minute or more on a slow computer, and for a few seconds it might seem like nothing is happening.

5. You should now have a new image with a single layer called "localized overlay". Inspect that everything's ok by adding the original english map as a new layer underneath the overlay; the english labels should be covered up, the localized labels in place and there should be no glitches anywhere. Save the image (just remember to hide/delete the english map layer first!) and you're done.

Final notes:

If there are labels which you don't need to localize, then first of all, don't bother including them among your localized labels. Then, once you've generated the final overlay, simply erase the parts which cover up the original english label.

Text sizing:

These are the text sizing rules that have been used on the english maps. Depending on your language, you may want to break some of them.

Major geographical features or other large areas which extend beyond the map edges (including forests): 28px small caps, tracking ~200.

Large geographical features: 22px normal or small caps.

Minor geographical features: 18px normal.

Major rivers: 20px, tracking ~200.

Small rivers: 18px, tracking ~200. For names like "R. Weldyn", note that periods are very small in Monotype Corsiva and get very close to the preceding R; I suggest giving the . a size of 24-30px and removing the following space. Other solutions can work too.

Capital cities: 24px normal.

Other major cities: 20px normal.

Small cities: 16px normal.

Large forests: 24px normal.

Small forests: 18px normal.

Text orientation and curving:

In the english maps, names of large geographical areas and rivers are often curved. River names usually follow the shape of the river, and names of large features such as "Heart Mountains" are curved to roughly match the shape of said feature.

All of the above is optional. You do not need to match the english labels in shape and location. If for some reason you need to, you can even omit some labels or add completely new ones.

MapLocalization

2013-02-20T20:31:31Z

Zookeeper: WIP version of the page

'''This page is a work in progress'''

Like the old maps, the new-style maps can be localized, but the intended method for doing so is quite different.

=== Overview ===

However, the workflow for localizing a map is simple: you create an image which contains the localized labels on a transparent background as simple text, no post-processing effects needed. In GIMP, you then add that image to a corresponding .xcf file as a new layer, and run a script. The script creates an overlay image which covers up the english labels, adds your localized labels and applies a bunch of post-processing effects to them in order to make them look identical to the english labels. All you need to do is to check the output and save.

=== Step-by-step instructions ===

==== Preparations ====

1. If you don't have GIMP, install it.

2. Download the [[http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/] wesnoth-map-localization.scm script] and place it into a script directory recognized by GIMP. You can view and configure the script directories in GIMP's preferences (Preferences -> Folders -> Scripts). If you already have GIMP running, you need to use '''Filters -> Script-Fu -> Refresh Scripts''' to make it recognize the newly added script. In the Filters menu, you should now see a filter category called "Wesnoth", and inside it "Map Localization". However, we don't need it yet.

3. Download the [[localization.xcf for the map you're localizing] http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/maps/].

Now you're all set to begin.

==== Localization ====

1. Open the localization.xcf you've downloaded. It contains a bunch of layers needed by the localization script, but at this point all you need is the layer called "label placement guide". It's a version of the map without any perspective or displacement effects added, and it is the one onto which you need to place the localized layers.

2. Create a new layer which includes the localized labels, positioning them using the aforementioned layer as a guide. The positions or orientation or curving of the labels does not need to match the english labels in any way. Place them in a way which you think looks good.

The requirements for the labels are simple: black text should be pure black, whereas yellow labels on forests should have the RGB value 185,155,85. The script gives you a little bit of leeway so you don't have to stress over very small color deviations, but don't do it intentionally. Background should be transparent.

''Note that you can use whatever graphics application you want in creating your labels, as long as you can import the result into GIMP so that it meets the above requirements.''

3. Add the layer containing your localized text into the same localization.xcf file and name it "labels". Don't mess with the other layers.

4. Run the script by choosing Filters -> Wesnoth -> Map Localization. The script will create a new image, and produce the output there. This will take a moment, perhaps as much as a minute or more on a slow computer, and for a few seconds it might seem like nothing is happening.

5. You should now have a new image with a single layer called "localized overlay". Inspect that everything's ok by adding the original english map as a new layer underneath the overlay; the english labels should be covered up, the localized labels in place and there should be no glitches anywhere. Save the image (just remember to hide/delete the english map layer first!) and you're done.

Final notes:

If there are labels which you don't need to localize, then first of all, don't bother including them among your localized labels. Then, once you've generated the final overlay, simply erase the parts which cover up the original english label.

Text sizing:

These are the text sizing rules that have been used on the english maps. Depending on your language, you may want to break some of them.

Major geographical features or other large areas which extend beyond the map edges (including forests): 28px small caps, tracking ~200.

Large geographical features: 22px normal or small caps.

Minor geographical features: 18px normal.

Major rivers: 20px, tracking ~200.

Small rivers: 18px, tracking ~200. For names like "R. Weldyn", note that periods are very small in Monotype Corsiva and get very close to the preceding R; I suggest giving the . a size of 24-30px and removing the following space. Other solutions can work too.

Capital cities: 24px normal.

Other major cities: 20px normal.

Small cities: 16px normal.

Large forests: 24px normal.

Small forests: 18px normal.

Text orientation and curving:

In the english maps, names of large geographical areas and rivers are often curved. River names usually follow the shape of the river, and names of large features such as "Heart Mountains" are curved to roughly match the shape of said feature.

All of the above is optional. You do not need to match the english labels in shape and location. If for some reason you need to, you can even omit some labels or add completely new ones.

AssetLocalization

2013-02-20T14:38:12Z

Zookeeper: DevFeature -> DevFeature1.11

Being a game, Wesnoth's graphics data carries higher significance than it would in utilitarian software. An image containing English text in an otherwise native language environment, may bite at user's immersion. For example, a mismatch between geographical names in translated text and on maps (like "Blackwater Port", "Ford of Abez", etc.) will certainly not improve user's feeling of completeness of localization effort.

To offset this, a willing translator can also localize images into the world of Wesnoth.

== How Does It Work? ==

Quite not unlike with text. Most text appearing in Wesnoth is up for translation, but given language's translators may leave some untranslated -- either deliberately (i.e. just copying English original), or because they didn't get to it yet. Likewise with the images: any can be localized, but none needs be; if there is no localized version of a given image, the user is presented with the original one. The only difference between text and images is that, unlike text, very few images possibly need to be localized -- presently, about 30 in total.

Once the localized image is made, putting it to work is simple. If the path of the original image in the source tree is:

foo/bar/baz/image.png

then the localized image should be put in:

foo/bar/baz/l10n/ll/image.png

where <tt>ll</tt> is the given language's code, like that used for names of PO files (e.g. <tt>de</tt>, <tt>pt_BR</tt>, etc.) That's it.

Before trying to test any localized images at runtime, it is also necessary that the following message in <tt>wesnoth-lib</tt> catalog is properly translated:

#. TRANSLATORS: This is the language code [...]
#: src/image.cpp:342
msgctxt "language code for localized resources"
msgid "en_US"
msgstr ""

The translation should basically be the same language code as used in paths of localized images (<tt>ll</tt> from the example above), but read the longer explanation in comments of this message for other possibilities.

A tracker script is run periodically on the repository to indicate that localized images need updating when the original image has been changed or moved. There is a file named <tt>l10n-track</tt> in the root of the source tree, which tracks the state for every localized image, grouped by language:

# ll
ok ¦foo/bar/baz/l10n/ll/image.png¦ ea9d6...563ad 30544
...

In each non-comment line, the first field is the state of the localized image, the second the path, third the checksum of the original image, and fourth the revision ID of the original image. When the original image has been modified, the corresponding localized image's state will change to <tt>fuzzy</tt>:

# ll
fuzzy ¦foo/bar/baz/l10n/ll/image.png¦ ea9d6...563ad 30544

If the original image is removed or renamed, the localized one will be marked as <tt>obsolete</tt>:

# ll
obsolete ¦foo/bar/baz/l10n/ll/image.png¦ ea9d6...563ad 30544

Translators should regularly check the <tt>l10n-track</tt> file, making the needed modifications to fuzzied images and submitting new versions (<tt>obsolete</tt> state will probably never be seen, as translation coordination team will see to it that localized images are moved and removed following the original). See below for a quick guide at dealing with fuzzy images. A fuzzy localized image will not be used at runtime, so that users will see the original image -- just like with fuzzy messages in PO files.

Translators can send new and updated localized images to Chusslove Illich <caslav.ilic@gmx.net> or to Espreon <Majora700_at_gmail_dot_com> for committing to the repository. They can also send in any source material used to create the final images, like Gimp XCF files, so that they are easily available for future editing. Source images for given language are located in the <tt>branches/resources/image-localization/ll</tt> directory in the repository.

The technicalities are thus rather simple, the main challenge instead is how to create the localized out of the original images in the first place. This depends on the type of the image: from trivial screenshots, to the more complex Wesnoth logo. Most of the rest of this article will deal with this.

=== Overlay Images ===

A special kind of localized image is an ''overlay'' image -- one which does not simply replace the original, but is combined with it at runtime, overlaying the original content. Of course, the overlay image should have some transparent regions, through which the original content will show up. The overlay image is indicated by adding <tt>--overlay</tt> suffix to its original name:

foo/bar/baz/l10n/ll/image--overlay.png

Overlay images are used purely to avoid needlesly growing the size of Wesnoth packages, in cases when the full image is rather large and only small parts of it need localization. This is typical of maps.

=== Resolving Fuzzy Images ===

When a localized image got fuzzy due to changes to the original, it is necessary to ascertain what is it exactly that had been changed, between the point when the localized image was made and current state. To do this, enter the root directory of appropriate branch in the repository, and observe the fuzzy entry in <tt>l10n-track</tt>:

fuzzy ¦foo/bar/baz/l10n/ll/image.png¦ ea9d6...563ad 30544

The final piece of data here is the revision ID of the original image at the time when the localized image was made. Recover this revision of the original, and copy it with a suffix to current working directory (note omission of <tt>/l10n/ll</tt> from the path):

$ svn up -r 30544 foo/bar/baz/image.png
U foo/bar/baz/image.png
Updated to revision 30544.
$ cp foo/bar/baz/image.png image-30544.png

Now do the same with the current original image (no revision ID necessary in <tt>svn</tt> command line):

$ svn up foo/bar/baz/image.png
U foo/bar/baz/image.png
Updated to revision 39066.
$ cp foo/bar/baz/image.png image-39066.png

After this, current working directory will contain the old and new original, named <tt>image-30544.png</tt> and <tt>image-39066.png</tt>. Now they can be quickly switched between in an image viewer, and the eye will easily capture the differences. There are also tools which can, given two images, produce a graphical diff of some sort.

After the differences have been observed, the localized image can be updated accordingly and submitted again.

== List of Images for Localization ==

An up-to-date list of images ''possibly'' needing localization is given here, and updated as people spot any new such image. Here, "possible" means judged such by at least one translator. Those are typically images containing some English text, but depending on the particular text, many languages may also like to keep it as in English (e.g. "Weldyn").

* In-game images:

images/misc/logo.png
data/core/images/misc/logo.png
-- The BfW logo, visible in the main menu, loading screens,
and elsewhere (both files are same)

data/core/images/maps/wesnoth.png
-- Wesnoth's main map, in the background of the main menu
and as the main map in some campaigns

data/core/images/help/hpxp.png
data/core/images/help/recruit.png
data/core/images/help/tooltip.png
-- screenshots in the help sections

data/campaigns/An_Orcish_Incursion/images/an-orcish-incursion-map.png
data/campaigns/Dead_Water/images/dead-water-map.png
data/campaigns/Descent_Into_Darkness/images/misc/descent-into-darkness.png
data/campaigns/Eastern_Invasion/images/eastern-invasion-map.png
data/campaigns/Legend_of_Wesmere/images/legend-of-wesmere-map.png
data/campaigns/Liberty/images/maps/liberty-map.png
data/campaigns/Son_Of_The_Black_Eye/images/farnorth.png
-- main maps of respective campaigns

data/campaigns/The_Rise_Of_Wesnoth/images/story/trow-logo.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/east.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/west.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-blackmore.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-clearwater.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-jevyan.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-southbay.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-stormvale.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-thegreenisle.png
-- text overlays in the TRoW campaign

data/core/images/lobby/sort-az.png
data/core/images/lobby/sort-az-off.png
-- sorting icons in multiplayer lobby (with "A-Z" on them)

* Images in the manual:

doc/manual/images/game-screen.jpg
doc/manual/images/main-menu.jpg
doc/manual/images/multiplayer.jpg
doc/manual/images/recruit.jpg
doc/manual/images/right_pane.jpg
doc/manual/images/top_pane.jpg

If you come across an image eligible for localization and not listed here, please add it.

== Creating Localized Images ==

This section gives brief, but hopefully sufficient instructions on how to produce localized images, by each distinct type. Note that there is a balance between simplicity of instructions and quality of final images -- whenever you can do better than describe here, do not hesitate.

Most of the time it will be necessary to edit an image template using a general image manipulation app, and the instructions here will be presented with [http://www.gimp.org/ Gimp], a popular and free tool for this purpose. There is also a [[#Gimp For Translators|section of this article]] describing some of the Gimp's features frequently used in present context.

=== Screenshots ===

Screenshots in the game are found on the help pages. Instead of full game screens, they are usually only smaller portions of screens. Making localized versions of these images is naturally easy, one just needs to grab some screenshots from the localized version of the game. Just a few points:

* Screenshots should be captured from the game running at 1024×768 resolution.

* To grab a screenshot, it's probably easiest to run the game in window instead of full screen, and use whatever screenshot capture utility available. (Gimp too can be used, menu '''File→Create→Screenshot'''.)

* The screenshot should be saved in PNG format (the capture utility will probably provide various formats).

* If the capture utility didn't provide option to select part of the screen to capture, to reduce the screenshot to the required small portion of the screen Gimp's cropping tool can be used ('''Tools→Transform Tools→Crop''').

* It is not necessary for the dimensions of localized screenshot to be exactly the same as the original screenshot, but should be near.

((to be done: screenshots in the manual; describe the explicit <tt>image-x.y.z.jpg</tt> versioning system))

=== BfW Logo ===

The sworded shield logo with "The Battle for Wesnoth" text is shown on loading screens and at the head of the main menu, thus being the foremost target for localization (for languages which have translated the game's name, of course). Here are the steps to create the localized logo with Gimp. Note in order to make sure the logo fits properly in the title screen it shall not be larger as 550x250.

Fetch the template logo from here:

http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/templates/bfw-logo/bfw-logo.xcf

There is just one layer in the file, <tt>shield</tt>, with the sworded shield on transparent background and without any text. Rename the file to e.g. <tt>bfw-logo-LANG.xcf</tt>, to work on it and keep it as "source" of your localized logo.

Pick a font in which you would like to write the logo text. The English logo uses "Celtic Garamond the 2nd" font, easily found by Google for free download, as the starting point. This font, however, contains only English letters (not even Western European), so some creativity may be needed to make use it. One could, for example, manually add any diacritics (copied over from suitable letters of another font). Another option is to simply use another font, which both has the glyphs of required characters, and is somewhat fantasy-looking.

The hardest part of localizing the logo is that of producing a single-color version of the text of translated game name. This may seem surprising at first -- why not just use the text tool to write out the text in proper size, and be done with it? The problem with this is that, as a rule rather than exception, the letters will not be mutualy spaced in visualy pleasing manner. For each font size, the spacing between any two paired letters needs to be manualy adjusted, a process which is called ''kerning''. Only high quality fonts have kerning instructions built in, and then usually only for small font sizes. Therefore we have to perform kerning manually.

Create a layer named <tt>text-temporary</tt> with transparent background (menu '''Layer→New Layer...''', type the name, and make sure '''Transparency''' is selected as '''Layer Fill Type'''). Switch to this layer, select text tool ('''Tools→Text'''), make sure that options '''Hinting''', '''Force auto-hinter''', and '''Antialiasing''' are all selected, and set color to black and font size to 42 (this size is appropriate for Celtic Garamond font mentioned above, may be different for another font). Write out the text with ''a space between each two letters'', i.e. like "B a t t l e ...". At this point, do not bother about text being centered over the shield; in fact, it is best to make the shield layer invisible (visibility of layers is controlled through the leftmost column in layer view).

If the name starts with a definite article (''The'', ''La'', etc.), put the article above the main text, as in the English logo -- of course, only if such splitting is permitted by title style in your language. This means once more applying the text tool to write out the article, also with a space between each two letters, and with font size 32.

Text written out with the text tool will appear as another, special layer. Convert it to ordinary layer using '''Layer→Discard Text Information'''. Make sure this new layer is positioned just above <tt>text-temporary</tt> (layer order is shown in the layer view, and can be changed with up/down arrows at the bottom), that the new layer is selected, and execute '''Layer→Merge Down'''. The new layer will dissapear and the text will become part of <tt>text-temporary</tt> layer. (In case there was another piece of text for the definite article, repeat the same procedure for it.) If Celtic Garamond font was used, to finally get to letter size quite near to English logo, resize <tt>text-temporary</tt> layer ('''Layer→Scale Layer...''') to 80% by horizontal and 120% by vertical.

At this point, for example, the image with translated name "Boj za Vesnot" will look like this:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/text-temporary.jpg</center>

(The <tt>shield</tt> layer has been dimmed by setting it's opacity to 50%, using the top slider in layer view. This is useful whenever a layer is not the focus of current operations, but may be needed for orientation.)

In preparation for kerning, each letter needs to be put on its own layer. To do this for a given letter, make <tt>text-temporary</tt> current layer, use rectangle selection tool ('''Tools→Selection Tools→Rectangle Select''', or just press '''R''' on keyboard), select the letter with generous empty space around it (this should be easy, since letters are widely spaced), and cut and paste the selection; this will create a floating selection layer, which can be turned into a normal layer by double-clicking on its name in layer view and renaming it to the letter itself (possibly with a suffix like <tt>-2</tt> for letters appearing more than once). Repeat this until all letters are on their own layers. It is best to start from the last letter in the name and go backwards, because then the letter layers are going to end up nicely ordered in the layer view (but they can always be ordered manually afterwards). When doing cut and paste step, it is critical that all the pasted letters appear at the same vertical position on the image (for this, fix the rectangle height on the preferences and position each rectangle at a fixed chosen vertical position before cutting). <tt>text-temporary</tt> layer becomes empty after all letters have been processed, so delete it ('''Layer→Delete Layer''').

Letters should now be horizontally moved to obtain visually pleasing spacing. Since each letter is on its own layer, moving single letters is easy. To move more than one letter together, you can link the corresponding layers (by clicking in the second left-most column in layer view, next to visibility column, producing chain-like icon). Layer is moved by the general move tool ('''Tools→Transform Tools→Move''', '''M''' on the keyboard), and to be sure that you are moving it exactly horizontally, observe the offset coordinates in the status bar; also, keeping '''Ctrl''' key pressed will constrain a move to one of eight radial directions, which starts being helpful for moves longer than a few pixels.

Here lays the toughest part: what does it mean "visualy pleasing"? How do you know when the letters and words are spaced "just right"? One way in which you ''cannot'' know this, is by measuring distances on pixel level -- an objective measure here is of no use, as the goal is to achieve perceptual balance for the observer's eye. So, unfortunatelly, you must simply follow your feeling. (See the note at the end of this section for how you should confirm that you have done this, as well as the logo overally, acceptably well.)

When the letters have been positioned, turn on the <tt>shield</tt> layer, link all letter layers, and move them such as to be centered over the shield. For proper vertical centering, follow the English logo.

Outer portions of the image should now be cut off such that the image is only as wide as the centered text, plus about one to two letter widths of empty space on each side. This is done by executing ''''Image→Canvas Size...''. In the dialog, make sure '''Width:''' and '''Height:''' are not linked (break chain icon to the left), and enter the appropriate new width. Click on '''Center''' button to make all layers centered with respect to new image width. In '''Resize layers:''' listbox, select '''Image-sized layers'''. Click '''Resize''' to exit the dialog and resize the image. If you left too much or too little empty space on the sides, you can undo and repeat the operation using a corrected guess for the width.

After the blank text has been created and positioned, the remaining steps to create the final logo are rather automatic.

The only layers in the image should now be letter layers and <tt>shield</tt>. Make <tt>shield</tt> layer invisible and all letter layers visible, and execute '''Layer→New from Visible'''. This will create a new layer containing all the letters; rename it to <tt>text-base</tt>. Do not delete letter layers, as they may be needed later for corrections in spacing, but make them all invisible. Here is how the image should look at this point:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/text-base-final.jpg</center>

As an example of why manual kerning is necessary, observe how the first word above, "Boj", looks like. If instead you try to write it out directly by the text tool, in Celtic Garamond font, you will see that the letter "o" is stuck to "B" while "j" is visibly separated from "o", resulting in quite ungainly word as whole.

Duplicate the <tt>text-base</tt> layer four times ('''Layer→Duplicate Layer'''), and name the copies as follows, going upwards from <tt>text-base</tt>: <tt>text-map</tt>, <tt>text-outline</tt>, <tt>text-shadow</tt>, <tt>text-final</tt>. Now we'll play a bit with these four layers. Note that for the following steps it is easier to always have only the currently selected text layer visible, while other layers should be hidden.

Switch to <tt>text-map</tt> layer and start Gaussian blur filter ('''Filters→Blur→Gaussian Blur...'''). In there, set both horizontal and vertical blur radius to 5 pixels. The preview pane should show how that the text got quite blurry; click '''Ok''' to apply the blur. Repeat this exact same filter for <tt>text-outline</tt> and <tt>text-shadow</tt> layers (you can just switch to each of them and use '''Filter→Repeat Last''').

Some layers should now get color different from black. Change to <tt>text-final</tt> (the topmost layer, which didn't get blurred), and start '''Colors→Colorize...'''. In the dialog, set hue to 50, saturation to 40, and lightness to 60. As you do this, the text in the image should reflect the modifications, and in the end it should be pale sand-like color. Click '''Ok''' to apply colorization. Change to <tt>text-map</tt> layer (one of the blurred layers), also use '''Colors→Colorize...''', but this time only set lightness to 100. This should make the blurred text white.

Switch to <tt>text-final</tt> and start '''Filters→Map→Bump Map...'''. From the '''Bump map:''' dropdown list in top right corner of the dialog, select the <tt>text-map</tt> layer (the layer name may be somewhat strange and possibly shrinked, so look the small icon to the left for the whitey pattern produced by white text on that layer). Check '''Compensate for darkening''' (should be so by default), and then set the sliders: azimuth 135, elevation 40, depth 10 (rest should be all zero). In the preview pane to the left you should now see the final bevelled text:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/text-bump-map.png</center>

(By this point, the colors may look not sufficiently near to the original, due to differences between Gimp releases. E.g. in a 2.4.x release the colors were reported too dark, and that additionally executing '''Colors→Brightness-Contrast''', with values 90 and 70 respectively, yielded better result.)

To complete the composition, make sure only the following layers are visible: <tt>shield</tt> (put its opacity back to 100% if it was dimmed), <tt>text-outline</tt>, <tt>text-shadow</tt>, <tt>text-final</tt>. Layers <tt>text-outline</tt> and <tt>text-shadow</tt> provide some dark shade behind the letters, to make them stand out better on the shield. Move both of these layers by single pixel downward; when moving, check '''Move the active layer''' in the move tool options, as otherwise it will be hard to grab the desired layer. The final result should look like this (note the ordering and visibility of layers):

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/shield-w-text-final.jpg</center>

The logo should now be exported as PNG image, named <tt>logo.png</tt>, using '''File→Save a Copy...''' (choose '''Merge Visible Layers''' when asked, default PNG export options will do). But do keep around the original Gimp XCF image, in case some changes are to be made in the future.

'''Note: Having a well done localized logo is very important for the first impression of the game. Therefore, you must post it to the Art Contributions forum for others to inspect and critique.

=== TRoW Logo ===

The logo with the "The Rise of Wesnoth" text is displayed on one of the story screens of the first scenario of ''The Rise of Wesnoth''. It is only seen once and is fairly easy to make.

First, fetch the logo from the Subversion repository:

http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/templates/trow-logo/trow-logo.xcf

As with the main logo, the TRoW logo uses "Celtic Garamond the 2nd".

As with the process of creating the main logo, switch to the text tool and enable the following options: '''hinting''', '''force-autohinting''', and '''antialiasing'''. Set the font size to seventy.

As the font size is so large, the text tool should get the spacing right, unlike the smaller text for the logos, so just write out the text one two or three lines (you should only use three lines if the text uses things such as prepositions).

If the text tool did not get the spacing right, then cut up the the letters into different layers and move as necessary.

After writing out the text, align the letters against the letters in <tt>original</tt>, then center the text against the image... like the text in <tt>original</tt>.

After you properly aligned and centered the text, merge all of the layers with the translated text (if there is more than one) and name the layer with all of the translated text <tt>text-base</tt>.

Duplicate <tt>text-base</tt> four times. The order (in ascending order) and names of the layers (including <tt>text-base</tt>) should be like this: <tt>text-base</tt> <tt>text-map</tt>, <tt>text-outline</tt>, <tt>text-shadow</tt>, <tt>text-final</tt>.

Switch to <tt>text-map</tt>; use the '''Colorize''' tool to make the layer all white (set the lighting to one hundred in the colorize dialog).

Now, apply an eight-radius Gaussian blur to <tt>text-map</tt>. Afterwards, apply a five-radius Gaussian blur to <tt>text-outline</tt> and <tt>text-shadow</tt>.

Switch to <tt>text-final</tt>; summon the '''Colorize''' tool; set hue to fifty, saturation to forty, and lightness to sixty; apply the effect. Afterwards, duplicate <tt>text-final</tt>; put this duplicate above <tt>text-final</tt> and call it <tt>text-final lighting</tt>.

Switch to <tt>text-final lighting</tt>; summon the '''Hue-Saturation''' tool; set hue to −165; apply the effect. Afterwards, set the layer mode of <tt>text-final lighting</tt> to "Lighten Only" and set its opacity to thirty percent.

Switch to <tt>text-final</tt>; summon the '''Bump Map''' dialog. Set the map to be bumped (Bump map) to <tt>text-map</tt>; set azimuth to 135, elevation to forty, depth to twenty, and the rest to zero. Make sure that "Compensate for darkening" is checked. Afterwards, apply the effect.

Switch to <tt>text-final lighting</tt>; summon the bump map dialog; keep the same settings we used last time, but check "Invert bumpmap"; apply the effect.

Drag down <tt>text-outline</tt> and <tt>text-shadow</tt> by one pixel.

Now, make sure that only the following layers are visible: <tt>text-outline</tt>, <tt>text-shadow</tt>, <tt>text-final</tt>, and <tt>text-final lighting</tt>.

After doing so, you should have a beautiful logo.

'''Note: Like for the main logo, TRoW logo has to be cleared by the community (see the ending note in main logo section).'''

=== Maps ===

As of {{DevFeature1.11}}, the maps and the localization process for them have changed. See [[MapLocalization]] for the new localization instructions.

Each campaign comes with a map, where locations of events are highlighted as the scenarios progress. Since these locations are frequently mentioned in narration and character conversations, it may be more than merely a "nice touch" to match the map labels to in-game texts. In particular, the main map of Wesnoth, which is used by several campaigns, also figures as the background of the main menu.

Luckily, most maps derive from the single source within the main repository:

http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/cartography-tools/great-continent.xcf

This Gimp source contains all topography features, as well as, most importantly, textual labels as separate layers. The procedure of localizing a map is thus this: export a PNG image with all the topography of required map, but without any text label, and then add translated labels to it. Here we'll work on the main menu map (<tt>data/core/images/maps/wesnoth.png</tt>) as the example.

The main menu map is assembled out of the following layers, not taking labels into account: <tt>Wesnoth topography</tt>, <tt>Wesnoth Marsh</tt>, <tt>Wesnoth Forests</tt>, <tt>Wesnoth Roads</tt>, <tt>Wesnoth Towns</tt>, <tt>Border</tt>, <tt>Border BG</tt>. Make ''only'' these layers visible, then export them as PNG using '''File→Save a Copy...''' (choose '''Merge Visible Layers''' when asked, default PNG export options will do); name this PNG file <tt>wesnoth-topo.png</tt>. Then, make the topography layer invisible, and make ''only'' the label layers visible: <tt>Wesnoth Human Names</tt>, <tt>Wesnoth early labels</tt>, <tt>Wesnoth late labels</tt>, and export them too as <tt>wesnoth-labels.png</tt>.

Open the previously exported <tt>wesnoth-topo.png</tt>, and immediately save it as ('''File→Save As...''') <tt>wesnoth-LANG.xcf</tt>, where <tt>LANG</tt> is your language code. Note the <tt>.xcf</tt> extension, which means this is now no longer a plain PNG bitmap, but a Gimp XCF image. This will be the source of your localized map, to which you will be able to return to at any later moment (e.g. if a label needs to be changed to reflect updated translation). Change the name of the only layer, <tt>Background</tt>, to <tt>topography</tt>.

Open the previously exported PNG of original labes as a layer with the current image ('''File→Open As Layers...'''). Tha labels will appear over the topography, visually resulting in composition just like the full map in the game. Change the name of the new layer to <tt>original-labels</tt>. This layer serves only as guide to position the translated labels, so set its opacity to 25%-50% (slider at the top of layer view), such that it becomes unobtrusive, yet discernable enough to indicate label positions.

The result so far should look like this:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/topo-w-orig-labels.jpg</center>

Now we are ready to start placing translated labels. For all labels, keep in mind to place them such that they are approximately covering the original label, as indicated by the dimmed <tt>>original-labels</tt> layer.

As for the font, original labels are written using Monotype Corsiva, which is easy to find for free download. If it does not contain all the glyphs needed for your language, another similar font to try is URW Chancery, which may already be installed by your distribution. If neither works, as usual try to find one that does and has a fantasy look to it.

There are three distinct types of labels on the main map, so let's cover them from easiest to hardest to make.

'''Plain Labels'''

Plain text labels are the most numerous. They are merely properly colored horizontal text, written down directly on the map. Therefore, to make one such label, just use text tool ('''Tools→Text'''), choose font size (13pt is the size for most of the original labels), check all of '''Hinting''', '''Force auto-hinter''', and '''Antialiasing''', click on the place on the map where the label should be, and write out the translated name.

You don't have to hit the desired position for the label exactly at the moment of writing. The label will become a special text layer, named by the text itself, which you can move around using the move tool ('''Tools→Transform Tools→Move'''). Note that you should ''not''' merge this text layer to any other layer, after you have finished positioning it. That way you will always be able to change the text at a later point (by double-clicking on the layer icon in layer view), rather than recreating it anew.

The only slightly tricky bit here is choosing the color for the text. Original labels are not all of same color, but depend on the darkness and tone of the map below it (e.g. whether it is sea or land). To pick a proper color for each label, the easiest is to load the original PNG image (<tt>data/core/images/maps/wesnoth.png</tt>) and use color picker ('''Tools→Color Picker''') to collect colors from each original label in turn. Since letters are antialiased, always pick the darkest color in the label.

Here's a view of one label made like this:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/map-label-plain.jpg</center>

Note the special text layer "''Glinova šuma''" ("Glyn's Forest") on the right, and how the transparent original label from the <tt>original-labels</tt> layer is showing below the translated one. To have a clear view of the new text, you can switch <tt>original-labels</tt> on and off by cliking on in the left column in layer list.

'''Rotated Plain Labels'''

Some of the plain labels are rotated to match the topographical feature, e.g. a river direction. To make such a label, first make the plain horizontal label as usual. This label now needs to be rotated.

Unfortunately, Gimp cannot currently rotate text layers, so you first need to convert the text to ordinary layer ('''Layer→Discard Text Information'''). Then, to rotate the layer, open '''Layer→Transform→Arbitrary Rotation...''' dialog. Make sure that '''Interpolation:''' field in the tool view (outside of the dialog) is set to '''Cubic'''. In the dialog, move the slider around and observe the image, until the rotation is approximately the same as that of the transparent original label beneath, and click '''Rotate'''. To finally properly position the label, just move its layer to match the original label.

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/map-label-plainrot.jpg</center>

The image above shows the translated "Bay of Pearls" ("''Biserni zaliv''") label, where the rotated label layer is seen to be an ordinary layer, instead of special text layer (with editable text) such as the one for plain labels.

'''Parchment Labels'''

Labels covering forests, mountains, and other features with uneven background, are put on what appears to be a rectangular piece of parchment. Fortunatelly, the source Gimp image for original maps (the one you used to export initial topography), also contains assortment of various labeling parchments, on the <tt>Label Workshop</tt> layer:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/map-parchments.jpg</center>

The idea then is to copy the appropriate parchment from this layer to the localized image, and then put a plain label above it. The difficulty is that copied parchments cannot be used as-is, but should be cut to the length of text.

First create two layers ('''Layer→New Layer...''') which will contain all the parchments, named <tt>label-parchments</tt> and <tt>label-parchments-woods</tt>, and make them transparent. Place these layers just above the <tt>original-labels</tt> layer, below all text label layers. You will then always copy parchments from the <tt>Label Workshop</tt> layer of the original image, to one of these two layers in the localized image. If a parchment is fully or partly over woods terrain, it is placed on <tt>label-parchments-woods</tt>, and otherwise to <tt>label-parchments</tt>. Set opacity of <tt>label-parchments</tt> to 75% and of <tt>label-parchments-woods</tt> to 90%, to have slightly transparent parchments as in the original.

To produce a parchment label, first write out a plain label over the map feature which should get the parchment background. This will serve to know how to position the parchment, and, more importantly, how to cut the parchment to the appropriate length. A parchment may need to be either extended or shrinked by cutting.

To extend a parchment, cut away right portion of it, and paste it such as to nicely fit around the right end of the text. Then cut the remaining left portion and paste it to fit around left end of the text. There will now be a gap in the parchment, which you should fill out by copying and pasting a mid-portion of the same parchment from the <tt>Label Workshop</tt> layer of the original image. To shrink a parchment, do the similar, only there will be no gap to fill after parts are cut and pasted. To decide where exactly to cut the parchment, check that when image is zoomed to 100%, there are no obvious joining artifacts (no repeating patterns, which brain easily notices).

Here is the translated version of "Grey Woods" label ("''Sivošumlje''"), with one text layer like for a plain label, and the length-cut parchment on the newly created <tt>label-parchments-woods</tt> layer:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/map-label-parchment.jpg</center>

Once all labels have been translated, make <tt>original-labels</tt> layer invisible, and all other layers visible. Export the final PNG image using '''File→Save a Copy...'''. The name should be the same as the original PNG image, which is <tt>wesnoth.png</tt> for the main map.

=== Overlay Cuts ===

The original image may have quite a heavy file size, while only small portions of it need to be translated. The main menu map is the prime example, with its 1.800 kB file size; if, say, ten languages would localize it and submit as full image, this map alone would make the distributed package grow by 18 megabytes. On the other hand, an image consisting of only the translated labels (with some portion of the map below them), and otherwise mostly transparent, would have about 180 kB. As mentioned [[#Overlay Images|earlier]], the game can overlay such transparent cuts over the original image at runtime, to produce the final localized image.

We'll use the main menu map as the example for producing an overlay cut. Open the localized XCF image of the map, and add one more layer to it, <tt>overlay-mask</tt>, also transparent. Place this layer on the top, and reduce its opacity to 50%. On it, we will draw a plain white rectangle over each translated label, such that it encompasses both the translated label ''and'' the original label (which is visible through semi-transparent <tt>original-labels</tt> layer). To draw a rectangle, use rectangle selection tool ('''Tools→Selection Tools→Rectangle Selection'''), just like when about to copy-paste stuff. But, instead of copying/cutting anything, fill the selection with foreground color (which you should have set to white), using '''Edit→Fill with FG Color'''. This is the result:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/overlay-mask.jpg</center>

Note that the selection rectangle has enveloped both the original label, "The Great Ocean", and the translated label, ''Veliki okean''. This is necessary in order that when the translated label is smaller than the original, such as in this case, outer sections of the original label do not show through when the localized overlay is composed with the original image.

You can of course use any of the Gimp's drawing tools to create white areas above labels. E.g. rectangle will cover more space than necessary for rotated labels, so there you may want to draw properly aligned lines using the pencil ('''Tools→Paint Tools→Pencil''') with a very thick round brush.

Once you create masks over all translated labels, load the previously exported PNG of the localized map. Copy the <tt>overlay-mask</tt> layer from the XCF to the PNG image, by dragging it from the layer view of the XCF to the image area of the PNG. ''Do not'' save the PNG image at that point, nor during any of the following steps; it should remain the ordinary, full localized image.

Select the <tt>overlay-mask</tt> layer just copied into the PNG (in fact, it will be named <tt>overlay-mask copy</tt>, and the only other layer should be <tt>Background</tt>) and execute '''Layer→Transparency→Alpha to Selection'''. This will create a selection out of the overlay layer:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/overlay-layer-to-mask.jpg</center>

What remains to be done is straightforward. Without removing the selection, make <tt>overlay-mask</tt> layer invisible, switch to the <tt>Background</tt> layer, execute '''Select→Invert''', execute '''Edit→Delete''', and the overlay cut is complete:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/overlay-final.jpg</center>

Save it as <tt>wesnoth--overlay.png</tt>, where <tt>--overlay</tt> ending is needed for the game to recognize that the image is not standalone, but an overlay. Remember to uncheck "Save color values from transparent pixels" option when exporting PNG, in order to create smaller overlay map.

You should save the XCF image with <tt>overlay-mask</tt> layer, rather than discarding it, so that at a later point you can modify the mask and repeat the few steps above to create the overlay cut (e.g. when translation of a label is changed).

== Gimp For Translators ==

Being a general-purpose bitmap-editing tool, beginners' tutorials on Gimp usually assume that the reader wants to go from the basics towards becoming a proficient Gimp user one day. This, however, provides too much breadth for the limited scope of retouching images for localization, as we are doing in this article. Of course, if you indeed would like to learn about bitmap editing in general, by all means do go through such tutorials (there are books too) in detail, and then return to this article to apply the obtained knowledge.

If, on the other hand, you'd rather "just get the job done" (such as, for the most part, the initial author of this article), the following subsections shortly explain some crucial elements of Gimp needed to follow the instructions on [[#Creating Localized Images|creating localized images]]. You can also consider them a guideline to what to pay special attention to, if the next thing you do is look for a more in-depth tutorial text.

=== Orientation ===

Here is a downscaled screenshot of what ''may'' pop up when Gimp 2.6 is started (Gimp's layout is highly configurable, so you may see something somewhat different), with most important areas marked with numbered red dots:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/gimp-windows.png</center>

Gimp uses ''single-document interface'', giving its elements as separate windows, such that they can be manipulated by the mechanisms of the desktop environment on which Gimp is run. For example, under typical Unix desktop environments (KDE, Gnome, etc.), user may want to work with Gimp on a virtual desktop dedicated to it.

Number (1) marks the window which will contain the image, once opened or created a new (it's empty on the screenshot). There will be as many of these windows as there are images opened. (2) is the "toolbox", the collection of icons representing Gimp's basic drawing, selection, transformation, etc. tools. All of them can also be activated from the '''Tools''' menu, and more importantly, by keyboard shortcuts. The two black/white overlapping rectangles at the bottom show the current foreground and background colors. You can select other colors by clicking on them. (3) is the tool options view, where the behavior of currently selected tool can be adjusted. (4) is the ''layer'' view, currently empty as no image is opened (more on layers later). These are just some of many elements of Gimp workspace, those most important to our present needs. If some is missing when you start Gimp on your machine, try turning it on through the '''Windows→Dockable Dialogs''' menu.

Let's now create an image, with ''transparent'' background. Go to '''File→New...''', set width and height to something smaller (e.g. 320×256 pixels), expand '''Advanced Options''', and under '''Fill with:''' select '''Transparency'''. In the image window you should now see a light-dark gray checkerboard pattern, and the layer view should list the <tt>Background</tt> layer.

To paint something on the empty image, select the pencil tool (click on pencil icon in toolbox, select '''Tools→Paint Tools→Pencil''' from the menu, or simply press N on keyboard). In tool options, click right of '''Brush:''' and select a bigger circle from the different brushes. Now simply start painting over the image, by holding left mouse button. Change the foreground color (by clicking on its rectangle in toolbox) to something else, then paint some more. Here's a possible result of this highly precise action we just undertook:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/gimp-nibblets.png</center>

Of note are the options to the pencil tool on the lower left (e.g. "Circle (19)" selected as brush), and the layers view which shows the single <tt>Background</tt> layer. What's this with layers, anyway?

=== Layers ===

Layers are one of fundamental concepts when working with just about any kind of images and drawings, bitmap or otherwise. Rather then theorizing about it, let us immediately create another layer. Either select '''Layer→New Layer...''' from the menu, click on the blank sheet icon in lower left corner of layer view, or press Ctrl+Shift+N. In the dialog that pops up, set layer name to <tt>Doodle</tt>, make sure '''Transparency''' is selected, and click '''Ok'''. In the layer view you will now see the <tt>Doodle</tt> layer, which will be highlighted and above the <tt>Background</tt> layer.

Repeat fooling around with pencil tool, while making sure that <tt>Doodle</tt> layer is highlighted in the layer view:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/gimp-nibblets-twolay.png</center>

Note the icons left of layer names in layer view: they reflect the layer content, and it appears that the black and blue lines are on <tt>Background</tt>, while red and white are on <tt>Doodle</tt> layer. This is precisely what had happened, because <tt>Background</tt> layer was the active one (highlighted in layer view) while painting the first time, and the <tt>Doodle</tt> layer while painting the second time.

Yet further left of layer names are "eye" icons, which show that layers are visible. Clicking on them will make layers visible or invisible; observe how the content of respective layer disappears and appears on the image together with switching the visibility. A layer can also be made semi-transparent, rather than completely invisible. Try playing with the '''Opacity:''' slider at the top of layer view while the <tt>Doodle</tt> layer is selected.

You may immediately realize some uses of layers. For example, a text label on a drawing can be added as a separate layer, without irreparably changing the basic drawing, such that it is easy to change the text later on. Layers can also be duplicated with all the content, in order to slightly change one and try which of the two versions better fits with the complete image. And so on. Any realistic image worked on with Gimp will contain at least several layers, and there may easily be tens of them.

Always keep in mind that, same as it happened above with the pencil tool, almost all painting, transforming, colorizing and other operations influence only the currently selected layer (the one highlighted in layer view). An easy oversight to make when there are many layers is to select the wrong layer, or forget to select the desired one, prior to performing an operation. Of course, there's always '''Undo'''.

=== Selection ===

Time to start copying and pasting things around. Same as with text, a portion of image needs to be first ''selected'', to be copied or cut, and then pasted. Unlike as with text, there are many ways in which the selection can be made: just take a look in '''Tools→Selection Tools'''. The basic of those is probably the rectangle selection; to activate it, click on dotted rectangle icon in toolbox, select '''Tools→Selection Tools→Rectangle Select''' from the menu, or press R on keyboard. Before doing anything, make sure <tt>Background</tt> layer is selected.

Left click somewhere on the image and drag the pointer. A translucent rectangle frame will spread from the point of click as you drag the pointer. After releasing the mouse button, the rectangle will become white-black dashed, with dashes moving around (the "marching ants" pattern). By this, you have made a selection (there will also be four smaller rectangles in its corners, which you can use to further adjust the selection sweep). To cancel the selection, without doing anything, just click somewhere outside of it.

Now copy the selection to clipboard, by pressing the usual Ctrl+C, or selecting '''Edit→Copy''' from the menu. Copying itself will not yield any visual effect. The important bits start to occur when you paste the copied selection, by Ctrl+V or '''Edit→Paste'''. Pasted selection will appear at the same place where the original was. There are several things to observe now:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/gimp-selection-copy-paste.png</center>

* The selection contour will be slightly changed to show exactly what was copied, omitting any transparent regions in the original selection.

* A new layer, named <tt>Floating Selection (Pasted Layer)</tt> has appeared. This is a ''temporary'' layer, which may either be made a permanent layer by selecting '''Layer→New Layer...''', or may be merged into the previously selected layer by canceling the selection (e.g. clicking outside of it). You can move the pasted layer around by left clicking and dragging within it.

* Because you have hit copy when <tt>Background</tt> layer was selected, only the content within selection and on that layer got copied and pasted. You can even make selection while one layer is active, then switch to another, and hit copy to grab the portion of that other layer. Also, while pasting action puts copy on its own temporary layer, canceling the selection will merge it into previously selected layer.

If you turn temporary pasted layer into a permanent layer, you will notice the motionless yellow-black dashed contour. It is also visible in the screenshot above, at sections not covered with moving white-black pattern. This contour shows the layer boundaries, that is, every layer can have its own size independent of the image size. The boundary size of a layer can be adjusted using '''Layer→Layer Boundary Size...'''. Instead of changing boundaries, layer can be resized with all its content using '''Layer→Scale Layer...'''.

You can now explore other ways of making selections (remember, clicking out of selection area while selection tool is active will cancel the current selection). E.g. if you choose '''Tools→Selection Tools→Fuzzy Select''', make <tt>Background</tt> layer active, and click somewhere on the thick blue line in the screenshot above, exactly this entire line will be selected. Every selection tool has some options in the tool view, which may be tweaked to affect exactly what is selected. For the fuzzy selection, for example, one can adjust the color sensitivity ('''Threshold:''' slider) to affect how much big a color difference is used to determine boundaries of selection.

Same as most modification operations affect only the currently selected layer, in presence of selection they also usually affect only the selected area. To test, make a rectangle selection, then switch to pencil tool and try to draw on the image. The pencil will leave trace only within the area of the selection, and on the currently active layer.

=== Text ===

Of the many painting tools, a particularly important one for localizing images will be, naturally, the text tool. It is activated by pressing the big A icon in the toolbox, '''Tools→Text''' menu item, or T on keyboard. Activate the text tool, and click somewhere on the image (to unclutter the view, make the <tt>Background</tt> and <tt>Doodle</tt> layers invisible). Click somewhere on the image, and a text input dialog will pop up. After typing something, we may obtain:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/gimp-text-tool.png</center>

Almost every part of this screenshots presents some important points.

On the left, the tool options for the text tools are shown. Here you can select the basics (font, size, and color), but also some other important options. The three checkboxes affect how the font is rendered: antialiasing makes letters non-jagged against the transparent background, and the two hinting options improve the shape of letters. You will almost always want to have all these checked. The justification buttons allow you to left-align, center, etc. the text. The three spinboxes bellow are used to tweak the spacing between letters (you can shrink the text that looks to wide, or shrink the distance between two lines of text).

In the center you can see the rendered text in top left corner of the image, and superimposed text input dialog over the image window. There you can also load some text from file, in case of longer texts.

On the right, in layer view, notice that the entered text got its own layer (named by the text itself), similar to what happens when selection is pasted. Unlike the temporary pasted layer, the text layer is permanent, but also special in that double-clicking its icon will allow you to edit the text at a later point (that's why its icon is a generic text-like icon, instead of showing layer content). Text layers can be changed into an ordinary layers by executing '''Layer→Discard Text Information''', but you will want to do this only if you need to do some arbitrary transformations on the text. The boundary of text layer is only as wide and high as the text, so you can move the text layer around.

=== Saving Images ===

Always save images first and formost in Gimp's native format, XCF. This will keep all the information, such as layers and selections, so that you can pick up editing the image just where you left. Consider the XCF format as your "source", on which you work and from which you "build" the final ordinary (or "flat") bitmap images.

When the image is ready for delivery, when you have made all necessary layers visible and helper or test layers invisible, you can save the image in one of flat bitmap formats. Two typical are PNG and JPEG, with the following very important difference between them. PNG is a "lossless" format, which means that every pixel in shown to the user just as it was in the source, XCF image, when the PNG was saved. JPEG is a "lossy" format, which compresses the image such that it's rather near to original, but not exactly and possibly with some ungainly visual artifacts, at the benefit of frequently considerably reducing the image size. PNG is what you will need for allmost all in-game localized images, as the originals are PNG images too. This is natural for game graphics, since it needs to be crisp, without any compression artifacts. JPEG is typically used for photographs, which would be huge if left uncompressed, and instructive screenshots which do not need crisp looks (e.g. for images in the manual).

To make a PNG image, you may as a matter of habit reach for '''File→Save As...''', and there select PNG as output format and save; then, to get back to the XCF source, you will close the PNG, and open the XCF again. To avoid this usual routine, there is the '''File→Save a Copy...''' action, which unlike '''Save As...''' will not switch to the newly saved PNG image, but let you continue working on the original XCF after saving.

[[Category:Translations]]

AssetLocalization

2013-02-20T14:37:09Z

Zookeeper: Added link to upcoming new MapLocalization page

Being a game, Wesnoth's graphics data carries higher significance than it would in utilitarian software. An image containing English text in an otherwise native language environment, may bite at user's immersion. For example, a mismatch between geographical names in translated text and on maps (like "Blackwater Port", "Ford of Abez", etc.) will certainly not improve user's feeling of completeness of localization effort.

To offset this, a willing translator can also localize images into the world of Wesnoth.

== How Does It Work? ==

Quite not unlike with text. Most text appearing in Wesnoth is up for translation, but given language's translators may leave some untranslated -- either deliberately (i.e. just copying English original), or because they didn't get to it yet. Likewise with the images: any can be localized, but none needs be; if there is no localized version of a given image, the user is presented with the original one. The only difference between text and images is that, unlike text, very few images possibly need to be localized -- presently, about 30 in total.

Once the localized image is made, putting it to work is simple. If the path of the original image in the source tree is:

foo/bar/baz/image.png

then the localized image should be put in:

foo/bar/baz/l10n/ll/image.png

where <tt>ll</tt> is the given language's code, like that used for names of PO files (e.g. <tt>de</tt>, <tt>pt_BR</tt>, etc.) That's it.

Before trying to test any localized images at runtime, it is also necessary that the following message in <tt>wesnoth-lib</tt> catalog is properly translated:

#. TRANSLATORS: This is the language code [...]
#: src/image.cpp:342
msgctxt "language code for localized resources"
msgid "en_US"
msgstr ""

The translation should basically be the same language code as used in paths of localized images (<tt>ll</tt> from the example above), but read the longer explanation in comments of this message for other possibilities.

A tracker script is run periodically on the repository to indicate that localized images need updating when the original image has been changed or moved. There is a file named <tt>l10n-track</tt> in the root of the source tree, which tracks the state for every localized image, grouped by language:

# ll
ok ¦foo/bar/baz/l10n/ll/image.png¦ ea9d6...563ad 30544
...

In each non-comment line, the first field is the state of the localized image, the second the path, third the checksum of the original image, and fourth the revision ID of the original image. When the original image has been modified, the corresponding localized image's state will change to <tt>fuzzy</tt>:

# ll
fuzzy ¦foo/bar/baz/l10n/ll/image.png¦ ea9d6...563ad 30544

If the original image is removed or renamed, the localized one will be marked as <tt>obsolete</tt>:

# ll
obsolete ¦foo/bar/baz/l10n/ll/image.png¦ ea9d6...563ad 30544

Translators should regularly check the <tt>l10n-track</tt> file, making the needed modifications to fuzzied images and submitting new versions (<tt>obsolete</tt> state will probably never be seen, as translation coordination team will see to it that localized images are moved and removed following the original). See below for a quick guide at dealing with fuzzy images. A fuzzy localized image will not be used at runtime, so that users will see the original image -- just like with fuzzy messages in PO files.

Translators can send new and updated localized images to Chusslove Illich <caslav.ilic@gmx.net> or to Espreon <Majora700_at_gmail_dot_com> for committing to the repository. They can also send in any source material used to create the final images, like Gimp XCF files, so that they are easily available for future editing. Source images for given language are located in the <tt>branches/resources/image-localization/ll</tt> directory in the repository.

The technicalities are thus rather simple, the main challenge instead is how to create the localized out of the original images in the first place. This depends on the type of the image: from trivial screenshots, to the more complex Wesnoth logo. Most of the rest of this article will deal with this.

=== Overlay Images ===

A special kind of localized image is an ''overlay'' image -- one which does not simply replace the original, but is combined with it at runtime, overlaying the original content. Of course, the overlay image should have some transparent regions, through which the original content will show up. The overlay image is indicated by adding <tt>--overlay</tt> suffix to its original name:

foo/bar/baz/l10n/ll/image--overlay.png

Overlay images are used purely to avoid needlesly growing the size of Wesnoth packages, in cases when the full image is rather large and only small parts of it need localization. This is typical of maps.

=== Resolving Fuzzy Images ===

When a localized image got fuzzy due to changes to the original, it is necessary to ascertain what is it exactly that had been changed, between the point when the localized image was made and current state. To do this, enter the root directory of appropriate branch in the repository, and observe the fuzzy entry in <tt>l10n-track</tt>:

fuzzy ¦foo/bar/baz/l10n/ll/image.png¦ ea9d6...563ad 30544

The final piece of data here is the revision ID of the original image at the time when the localized image was made. Recover this revision of the original, and copy it with a suffix to current working directory (note omission of <tt>/l10n/ll</tt> from the path):

$ svn up -r 30544 foo/bar/baz/image.png
U foo/bar/baz/image.png
Updated to revision 30544.
$ cp foo/bar/baz/image.png image-30544.png

Now do the same with the current original image (no revision ID necessary in <tt>svn</tt> command line):

$ svn up foo/bar/baz/image.png
U foo/bar/baz/image.png
Updated to revision 39066.
$ cp foo/bar/baz/image.png image-39066.png

After this, current working directory will contain the old and new original, named <tt>image-30544.png</tt> and <tt>image-39066.png</tt>. Now they can be quickly switched between in an image viewer, and the eye will easily capture the differences. There are also tools which can, given two images, produce a graphical diff of some sort.

After the differences have been observed, the localized image can be updated accordingly and submitted again.

== List of Images for Localization ==

An up-to-date list of images ''possibly'' needing localization is given here, and updated as people spot any new such image. Here, "possible" means judged such by at least one translator. Those are typically images containing some English text, but depending on the particular text, many languages may also like to keep it as in English (e.g. "Weldyn").

* In-game images:

images/misc/logo.png
data/core/images/misc/logo.png
-- The BfW logo, visible in the main menu, loading screens,
and elsewhere (both files are same)

data/core/images/maps/wesnoth.png
-- Wesnoth's main map, in the background of the main menu
and as the main map in some campaigns

data/core/images/help/hpxp.png
data/core/images/help/recruit.png
data/core/images/help/tooltip.png
-- screenshots in the help sections

data/campaigns/An_Orcish_Incursion/images/an-orcish-incursion-map.png
data/campaigns/Dead_Water/images/dead-water-map.png
data/campaigns/Descent_Into_Darkness/images/misc/descent-into-darkness.png
data/campaigns/Eastern_Invasion/images/eastern-invasion-map.png
data/campaigns/Legend_of_Wesmere/images/legend-of-wesmere-map.png
data/campaigns/Liberty/images/maps/liberty-map.png
data/campaigns/Son_Of_The_Black_Eye/images/farnorth.png
-- main maps of respective campaigns

data/campaigns/The_Rise_Of_Wesnoth/images/story/trow-logo.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/east.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/west.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-blackmore.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-clearwater.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-jevyan.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-southbay.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-stormvale.png
data/campaigns/The_Rise_Of_Wesnoth/images/story/tgi-thegreenisle.png
-- text overlays in the TRoW campaign

data/core/images/lobby/sort-az.png
data/core/images/lobby/sort-az-off.png
-- sorting icons in multiplayer lobby (with "A-Z" on them)

* Images in the manual:

doc/manual/images/game-screen.jpg
doc/manual/images/main-menu.jpg
doc/manual/images/multiplayer.jpg
doc/manual/images/recruit.jpg
doc/manual/images/right_pane.jpg
doc/manual/images/top_pane.jpg

If you come across an image eligible for localization and not listed here, please add it.

== Creating Localized Images ==

This section gives brief, but hopefully sufficient instructions on how to produce localized images, by each distinct type. Note that there is a balance between simplicity of instructions and quality of final images -- whenever you can do better than describe here, do not hesitate.

Most of the time it will be necessary to edit an image template using a general image manipulation app, and the instructions here will be presented with [http://www.gimp.org/ Gimp], a popular and free tool for this purpose. There is also a [[#Gimp For Translators|section of this article]] describing some of the Gimp's features frequently used in present context.

=== Screenshots ===

Screenshots in the game are found on the help pages. Instead of full game screens, they are usually only smaller portions of screens. Making localized versions of these images is naturally easy, one just needs to grab some screenshots from the localized version of the game. Just a few points:

* Screenshots should be captured from the game running at 1024×768 resolution.

* To grab a screenshot, it's probably easiest to run the game in window instead of full screen, and use whatever screenshot capture utility available. (Gimp too can be used, menu '''File→Create→Screenshot'''.)

* The screenshot should be saved in PNG format (the capture utility will probably provide various formats).

* If the capture utility didn't provide option to select part of the screen to capture, to reduce the screenshot to the required small portion of the screen Gimp's cropping tool can be used ('''Tools→Transform Tools→Crop''').

* It is not necessary for the dimensions of localized screenshot to be exactly the same as the original screenshot, but should be near.

((to be done: screenshots in the manual; describe the explicit <tt>image-x.y.z.jpg</tt> versioning system))

=== BfW Logo ===

The sworded shield logo with "The Battle for Wesnoth" text is shown on loading screens and at the head of the main menu, thus being the foremost target for localization (for languages which have translated the game's name, of course). Here are the steps to create the localized logo with Gimp. Note in order to make sure the logo fits properly in the title screen it shall not be larger as 550x250.

Fetch the template logo from here:

http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/templates/bfw-logo/bfw-logo.xcf

There is just one layer in the file, <tt>shield</tt>, with the sworded shield on transparent background and without any text. Rename the file to e.g. <tt>bfw-logo-LANG.xcf</tt>, to work on it and keep it as "source" of your localized logo.

Pick a font in which you would like to write the logo text. The English logo uses "Celtic Garamond the 2nd" font, easily found by Google for free download, as the starting point. This font, however, contains only English letters (not even Western European), so some creativity may be needed to make use it. One could, for example, manually add any diacritics (copied over from suitable letters of another font). Another option is to simply use another font, which both has the glyphs of required characters, and is somewhat fantasy-looking.

The hardest part of localizing the logo is that of producing a single-color version of the text of translated game name. This may seem surprising at first -- why not just use the text tool to write out the text in proper size, and be done with it? The problem with this is that, as a rule rather than exception, the letters will not be mutualy spaced in visualy pleasing manner. For each font size, the spacing between any two paired letters needs to be manualy adjusted, a process which is called ''kerning''. Only high quality fonts have kerning instructions built in, and then usually only for small font sizes. Therefore we have to perform kerning manually.

Create a layer named <tt>text-temporary</tt> with transparent background (menu '''Layer→New Layer...''', type the name, and make sure '''Transparency''' is selected as '''Layer Fill Type'''). Switch to this layer, select text tool ('''Tools→Text'''), make sure that options '''Hinting''', '''Force auto-hinter''', and '''Antialiasing''' are all selected, and set color to black and font size to 42 (this size is appropriate for Celtic Garamond font mentioned above, may be different for another font). Write out the text with ''a space between each two letters'', i.e. like "B a t t l e ...". At this point, do not bother about text being centered over the shield; in fact, it is best to make the shield layer invisible (visibility of layers is controlled through the leftmost column in layer view).

If the name starts with a definite article (''The'', ''La'', etc.), put the article above the main text, as in the English logo -- of course, only if such splitting is permitted by title style in your language. This means once more applying the text tool to write out the article, also with a space between each two letters, and with font size 32.

Text written out with the text tool will appear as another, special layer. Convert it to ordinary layer using '''Layer→Discard Text Information'''. Make sure this new layer is positioned just above <tt>text-temporary</tt> (layer order is shown in the layer view, and can be changed with up/down arrows at the bottom), that the new layer is selected, and execute '''Layer→Merge Down'''. The new layer will dissapear and the text will become part of <tt>text-temporary</tt> layer. (In case there was another piece of text for the definite article, repeat the same procedure for it.) If Celtic Garamond font was used, to finally get to letter size quite near to English logo, resize <tt>text-temporary</tt> layer ('''Layer→Scale Layer...''') to 80% by horizontal and 120% by vertical.

At this point, for example, the image with translated name "Boj za Vesnot" will look like this:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/text-temporary.jpg</center>

(The <tt>shield</tt> layer has been dimmed by setting it's opacity to 50%, using the top slider in layer view. This is useful whenever a layer is not the focus of current operations, but may be needed for orientation.)

In preparation for kerning, each letter needs to be put on its own layer. To do this for a given letter, make <tt>text-temporary</tt> current layer, use rectangle selection tool ('''Tools→Selection Tools→Rectangle Select''', or just press '''R''' on keyboard), select the letter with generous empty space around it (this should be easy, since letters are widely spaced), and cut and paste the selection; this will create a floating selection layer, which can be turned into a normal layer by double-clicking on its name in layer view and renaming it to the letter itself (possibly with a suffix like <tt>-2</tt> for letters appearing more than once). Repeat this until all letters are on their own layers. It is best to start from the last letter in the name and go backwards, because then the letter layers are going to end up nicely ordered in the layer view (but they can always be ordered manually afterwards). When doing cut and paste step, it is critical that all the pasted letters appear at the same vertical position on the image (for this, fix the rectangle height on the preferences and position each rectangle at a fixed chosen vertical position before cutting). <tt>text-temporary</tt> layer becomes empty after all letters have been processed, so delete it ('''Layer→Delete Layer''').

Letters should now be horizontally moved to obtain visually pleasing spacing. Since each letter is on its own layer, moving single letters is easy. To move more than one letter together, you can link the corresponding layers (by clicking in the second left-most column in layer view, next to visibility column, producing chain-like icon). Layer is moved by the general move tool ('''Tools→Transform Tools→Move''', '''M''' on the keyboard), and to be sure that you are moving it exactly horizontally, observe the offset coordinates in the status bar; also, keeping '''Ctrl''' key pressed will constrain a move to one of eight radial directions, which starts being helpful for moves longer than a few pixels.

Here lays the toughest part: what does it mean "visualy pleasing"? How do you know when the letters and words are spaced "just right"? One way in which you ''cannot'' know this, is by measuring distances on pixel level -- an objective measure here is of no use, as the goal is to achieve perceptual balance for the observer's eye. So, unfortunatelly, you must simply follow your feeling. (See the note at the end of this section for how you should confirm that you have done this, as well as the logo overally, acceptably well.)

When the letters have been positioned, turn on the <tt>shield</tt> layer, link all letter layers, and move them such as to be centered over the shield. For proper vertical centering, follow the English logo.

Outer portions of the image should now be cut off such that the image is only as wide as the centered text, plus about one to two letter widths of empty space on each side. This is done by executing ''''Image→Canvas Size...''. In the dialog, make sure '''Width:''' and '''Height:''' are not linked (break chain icon to the left), and enter the appropriate new width. Click on '''Center''' button to make all layers centered with respect to new image width. In '''Resize layers:''' listbox, select '''Image-sized layers'''. Click '''Resize''' to exit the dialog and resize the image. If you left too much or too little empty space on the sides, you can undo and repeat the operation using a corrected guess for the width.

After the blank text has been created and positioned, the remaining steps to create the final logo are rather automatic.

The only layers in the image should now be letter layers and <tt>shield</tt>. Make <tt>shield</tt> layer invisible and all letter layers visible, and execute '''Layer→New from Visible'''. This will create a new layer containing all the letters; rename it to <tt>text-base</tt>. Do not delete letter layers, as they may be needed later for corrections in spacing, but make them all invisible. Here is how the image should look at this point:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/text-base-final.jpg</center>

As an example of why manual kerning is necessary, observe how the first word above, "Boj", looks like. If instead you try to write it out directly by the text tool, in Celtic Garamond font, you will see that the letter "o" is stuck to "B" while "j" is visibly separated from "o", resulting in quite ungainly word as whole.

Duplicate the <tt>text-base</tt> layer four times ('''Layer→Duplicate Layer'''), and name the copies as follows, going upwards from <tt>text-base</tt>: <tt>text-map</tt>, <tt>text-outline</tt>, <tt>text-shadow</tt>, <tt>text-final</tt>. Now we'll play a bit with these four layers. Note that for the following steps it is easier to always have only the currently selected text layer visible, while other layers should be hidden.

Switch to <tt>text-map</tt> layer and start Gaussian blur filter ('''Filters→Blur→Gaussian Blur...'''). In there, set both horizontal and vertical blur radius to 5 pixels. The preview pane should show how that the text got quite blurry; click '''Ok''' to apply the blur. Repeat this exact same filter for <tt>text-outline</tt> and <tt>text-shadow</tt> layers (you can just switch to each of them and use '''Filter→Repeat Last''').

Some layers should now get color different from black. Change to <tt>text-final</tt> (the topmost layer, which didn't get blurred), and start '''Colors→Colorize...'''. In the dialog, set hue to 50, saturation to 40, and lightness to 60. As you do this, the text in the image should reflect the modifications, and in the end it should be pale sand-like color. Click '''Ok''' to apply colorization. Change to <tt>text-map</tt> layer (one of the blurred layers), also use '''Colors→Colorize...''', but this time only set lightness to 100. This should make the blurred text white.

Switch to <tt>text-final</tt> and start '''Filters→Map→Bump Map...'''. From the '''Bump map:''' dropdown list in top right corner of the dialog, select the <tt>text-map</tt> layer (the layer name may be somewhat strange and possibly shrinked, so look the small icon to the left for the whitey pattern produced by white text on that layer). Check '''Compensate for darkening''' (should be so by default), and then set the sliders: azimuth 135, elevation 40, depth 10 (rest should be all zero). In the preview pane to the left you should now see the final bevelled text:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/text-bump-map.png</center>

(By this point, the colors may look not sufficiently near to the original, due to differences between Gimp releases. E.g. in a 2.4.x release the colors were reported too dark, and that additionally executing '''Colors→Brightness-Contrast''', with values 90 and 70 respectively, yielded better result.)

To complete the composition, make sure only the following layers are visible: <tt>shield</tt> (put its opacity back to 100% if it was dimmed), <tt>text-outline</tt>, <tt>text-shadow</tt>, <tt>text-final</tt>. Layers <tt>text-outline</tt> and <tt>text-shadow</tt> provide some dark shade behind the letters, to make them stand out better on the shield. Move both of these layers by single pixel downward; when moving, check '''Move the active layer''' in the move tool options, as otherwise it will be hard to grab the desired layer. The final result should look like this (note the ordering and visibility of layers):

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/shield-w-text-final.jpg</center>

The logo should now be exported as PNG image, named <tt>logo.png</tt>, using '''File→Save a Copy...''' (choose '''Merge Visible Layers''' when asked, default PNG export options will do). But do keep around the original Gimp XCF image, in case some changes are to be made in the future.

'''Note: Having a well done localized logo is very important for the first impression of the game. Therefore, you must post it to the Art Contributions forum for others to inspect and critique.

=== TRoW Logo ===

The logo with the "The Rise of Wesnoth" text is displayed on one of the story screens of the first scenario of ''The Rise of Wesnoth''. It is only seen once and is fairly easy to make.

First, fetch the logo from the Subversion repository:

http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/templates/trow-logo/trow-logo.xcf

As with the main logo, the TRoW logo uses "Celtic Garamond the 2nd".

As with the process of creating the main logo, switch to the text tool and enable the following options: '''hinting''', '''force-autohinting''', and '''antialiasing'''. Set the font size to seventy.

As the font size is so large, the text tool should get the spacing right, unlike the smaller text for the logos, so just write out the text one two or three lines (you should only use three lines if the text uses things such as prepositions).

If the text tool did not get the spacing right, then cut up the the letters into different layers and move as necessary.

After writing out the text, align the letters against the letters in <tt>original</tt>, then center the text against the image... like the text in <tt>original</tt>.

After you properly aligned and centered the text, merge all of the layers with the translated text (if there is more than one) and name the layer with all of the translated text <tt>text-base</tt>.

Duplicate <tt>text-base</tt> four times. The order (in ascending order) and names of the layers (including <tt>text-base</tt>) should be like this: <tt>text-base</tt> <tt>text-map</tt>, <tt>text-outline</tt>, <tt>text-shadow</tt>, <tt>text-final</tt>.

Switch to <tt>text-map</tt>; use the '''Colorize''' tool to make the layer all white (set the lighting to one hundred in the colorize dialog).

Now, apply an eight-radius Gaussian blur to <tt>text-map</tt>. Afterwards, apply a five-radius Gaussian blur to <tt>text-outline</tt> and <tt>text-shadow</tt>.

Switch to <tt>text-final</tt>; summon the '''Colorize''' tool; set hue to fifty, saturation to forty, and lightness to sixty; apply the effect. Afterwards, duplicate <tt>text-final</tt>; put this duplicate above <tt>text-final</tt> and call it <tt>text-final lighting</tt>.

Switch to <tt>text-final lighting</tt>; summon the '''Hue-Saturation''' tool; set hue to −165; apply the effect. Afterwards, set the layer mode of <tt>text-final lighting</tt> to "Lighten Only" and set its opacity to thirty percent.

Switch to <tt>text-final</tt>; summon the '''Bump Map''' dialog. Set the map to be bumped (Bump map) to <tt>text-map</tt>; set azimuth to 135, elevation to forty, depth to twenty, and the rest to zero. Make sure that "Compensate for darkening" is checked. Afterwards, apply the effect.

Switch to <tt>text-final lighting</tt>; summon the bump map dialog; keep the same settings we used last time, but check "Invert bumpmap"; apply the effect.

Drag down <tt>text-outline</tt> and <tt>text-shadow</tt> by one pixel.

Now, make sure that only the following layers are visible: <tt>text-outline</tt>, <tt>text-shadow</tt>, <tt>text-final</tt>, and <tt>text-final lighting</tt>.

After doing so, you should have a beautiful logo.

'''Note: Like for the main logo, TRoW logo has to be cleared by the community (see the ending note in main logo section).'''

=== Maps ===

As of {{DevFeature}}, the maps and the localization process for them have changed. See [[MapLocalization]] for the new localization instructions.

Each campaign comes with a map, where locations of events are highlighted as the scenarios progress. Since these locations are frequently mentioned in narration and character conversations, it may be more than merely a "nice touch" to match the map labels to in-game texts. In particular, the main map of Wesnoth, which is used by several campaigns, also figures as the background of the main menu.

Luckily, most maps derive from the single source within the main repository:

http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/cartography-tools/great-continent.xcf

This Gimp source contains all topography features, as well as, most importantly, textual labels as separate layers. The procedure of localizing a map is thus this: export a PNG image with all the topography of required map, but without any text label, and then add translated labels to it. Here we'll work on the main menu map (<tt>data/core/images/maps/wesnoth.png</tt>) as the example.

The main menu map is assembled out of the following layers, not taking labels into account: <tt>Wesnoth topography</tt>, <tt>Wesnoth Marsh</tt>, <tt>Wesnoth Forests</tt>, <tt>Wesnoth Roads</tt>, <tt>Wesnoth Towns</tt>, <tt>Border</tt>, <tt>Border BG</tt>. Make ''only'' these layers visible, then export them as PNG using '''File→Save a Copy...''' (choose '''Merge Visible Layers''' when asked, default PNG export options will do); name this PNG file <tt>wesnoth-topo.png</tt>. Then, make the topography layer invisible, and make ''only'' the label layers visible: <tt>Wesnoth Human Names</tt>, <tt>Wesnoth early labels</tt>, <tt>Wesnoth late labels</tt>, and export them too as <tt>wesnoth-labels.png</tt>.

Open the previously exported <tt>wesnoth-topo.png</tt>, and immediately save it as ('''File→Save As...''') <tt>wesnoth-LANG.xcf</tt>, where <tt>LANG</tt> is your language code. Note the <tt>.xcf</tt> extension, which means this is now no longer a plain PNG bitmap, but a Gimp XCF image. This will be the source of your localized map, to which you will be able to return to at any later moment (e.g. if a label needs to be changed to reflect updated translation). Change the name of the only layer, <tt>Background</tt>, to <tt>topography</tt>.

Open the previously exported PNG of original labes as a layer with the current image ('''File→Open As Layers...'''). Tha labels will appear over the topography, visually resulting in composition just like the full map in the game. Change the name of the new layer to <tt>original-labels</tt>. This layer serves only as guide to position the translated labels, so set its opacity to 25%-50% (slider at the top of layer view), such that it becomes unobtrusive, yet discernable enough to indicate label positions.

The result so far should look like this:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/topo-w-orig-labels.jpg</center>

Now we are ready to start placing translated labels. For all labels, keep in mind to place them such that they are approximately covering the original label, as indicated by the dimmed <tt>>original-labels</tt> layer.

As for the font, original labels are written using Monotype Corsiva, which is easy to find for free download. If it does not contain all the glyphs needed for your language, another similar font to try is URW Chancery, which may already be installed by your distribution. If neither works, as usual try to find one that does and has a fantasy look to it.

There are three distinct types of labels on the main map, so let's cover them from easiest to hardest to make.

'''Plain Labels'''

Plain text labels are the most numerous. They are merely properly colored horizontal text, written down directly on the map. Therefore, to make one such label, just use text tool ('''Tools→Text'''), choose font size (13pt is the size for most of the original labels), check all of '''Hinting''', '''Force auto-hinter''', and '''Antialiasing''', click on the place on the map where the label should be, and write out the translated name.

You don't have to hit the desired position for the label exactly at the moment of writing. The label will become a special text layer, named by the text itself, which you can move around using the move tool ('''Tools→Transform Tools→Move'''). Note that you should ''not''' merge this text layer to any other layer, after you have finished positioning it. That way you will always be able to change the text at a later point (by double-clicking on the layer icon in layer view), rather than recreating it anew.

The only slightly tricky bit here is choosing the color for the text. Original labels are not all of same color, but depend on the darkness and tone of the map below it (e.g. whether it is sea or land). To pick a proper color for each label, the easiest is to load the original PNG image (<tt>data/core/images/maps/wesnoth.png</tt>) and use color picker ('''Tools→Color Picker''') to collect colors from each original label in turn. Since letters are antialiased, always pick the darkest color in the label.

Here's a view of one label made like this:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/map-label-plain.jpg</center>

Note the special text layer "''Glinova šuma''" ("Glyn's Forest") on the right, and how the transparent original label from the <tt>original-labels</tt> layer is showing below the translated one. To have a clear view of the new text, you can switch <tt>original-labels</tt> on and off by cliking on in the left column in layer list.

'''Rotated Plain Labels'''

Some of the plain labels are rotated to match the topographical feature, e.g. a river direction. To make such a label, first make the plain horizontal label as usual. This label now needs to be rotated.

Unfortunately, Gimp cannot currently rotate text layers, so you first need to convert the text to ordinary layer ('''Layer→Discard Text Information'''). Then, to rotate the layer, open '''Layer→Transform→Arbitrary Rotation...''' dialog. Make sure that '''Interpolation:''' field in the tool view (outside of the dialog) is set to '''Cubic'''. In the dialog, move the slider around and observe the image, until the rotation is approximately the same as that of the transparent original label beneath, and click '''Rotate'''. To finally properly position the label, just move its layer to match the original label.

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/map-label-plainrot.jpg</center>

The image above shows the translated "Bay of Pearls" ("''Biserni zaliv''") label, where the rotated label layer is seen to be an ordinary layer, instead of special text layer (with editable text) such as the one for plain labels.

'''Parchment Labels'''

Labels covering forests, mountains, and other features with uneven background, are put on what appears to be a rectangular piece of parchment. Fortunatelly, the source Gimp image for original maps (the one you used to export initial topography), also contains assortment of various labeling parchments, on the <tt>Label Workshop</tt> layer:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/map-parchments.jpg</center>

The idea then is to copy the appropriate parchment from this layer to the localized image, and then put a plain label above it. The difficulty is that copied parchments cannot be used as-is, but should be cut to the length of text.

First create two layers ('''Layer→New Layer...''') which will contain all the parchments, named <tt>label-parchments</tt> and <tt>label-parchments-woods</tt>, and make them transparent. Place these layers just above the <tt>original-labels</tt> layer, below all text label layers. You will then always copy parchments from the <tt>Label Workshop</tt> layer of the original image, to one of these two layers in the localized image. If a parchment is fully or partly over woods terrain, it is placed on <tt>label-parchments-woods</tt>, and otherwise to <tt>label-parchments</tt>. Set opacity of <tt>label-parchments</tt> to 75% and of <tt>label-parchments-woods</tt> to 90%, to have slightly transparent parchments as in the original.

To produce a parchment label, first write out a plain label over the map feature which should get the parchment background. This will serve to know how to position the parchment, and, more importantly, how to cut the parchment to the appropriate length. A parchment may need to be either extended or shrinked by cutting.

To extend a parchment, cut away right portion of it, and paste it such as to nicely fit around the right end of the text. Then cut the remaining left portion and paste it to fit around left end of the text. There will now be a gap in the parchment, which you should fill out by copying and pasting a mid-portion of the same parchment from the <tt>Label Workshop</tt> layer of the original image. To shrink a parchment, do the similar, only there will be no gap to fill after parts are cut and pasted. To decide where exactly to cut the parchment, check that when image is zoomed to 100%, there are no obvious joining artifacts (no repeating patterns, which brain easily notices).

Here is the translated version of "Grey Woods" label ("''Sivošumlje''"), with one text layer like for a plain label, and the length-cut parchment on the newly created <tt>label-parchments-woods</tt> layer:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/map-label-parchment.jpg</center>

Once all labels have been translated, make <tt>original-labels</tt> layer invisible, and all other layers visible. Export the final PNG image using '''File→Save a Copy...'''. The name should be the same as the original PNG image, which is <tt>wesnoth.png</tt> for the main map.

=== Overlay Cuts ===

The original image may have quite a heavy file size, while only small portions of it need to be translated. The main menu map is the prime example, with its 1.800 kB file size; if, say, ten languages would localize it and submit as full image, this map alone would make the distributed package grow by 18 megabytes. On the other hand, an image consisting of only the translated labels (with some portion of the map below them), and otherwise mostly transparent, would have about 180 kB. As mentioned [[#Overlay Images|earlier]], the game can overlay such transparent cuts over the original image at runtime, to produce the final localized image.

We'll use the main menu map as the example for producing an overlay cut. Open the localized XCF image of the map, and add one more layer to it, <tt>overlay-mask</tt>, also transparent. Place this layer on the top, and reduce its opacity to 50%. On it, we will draw a plain white rectangle over each translated label, such that it encompasses both the translated label ''and'' the original label (which is visible through semi-transparent <tt>original-labels</tt> layer). To draw a rectangle, use rectangle selection tool ('''Tools→Selection Tools→Rectangle Selection'''), just like when about to copy-paste stuff. But, instead of copying/cutting anything, fill the selection with foreground color (which you should have set to white), using '''Edit→Fill with FG Color'''. This is the result:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/overlay-mask.jpg</center>

Note that the selection rectangle has enveloped both the original label, "The Great Ocean", and the translated label, ''Veliki okean''. This is necessary in order that when the translated label is smaller than the original, such as in this case, outer sections of the original label do not show through when the localized overlay is composed with the original image.

You can of course use any of the Gimp's drawing tools to create white areas above labels. E.g. rectangle will cover more space than necessary for rotated labels, so there you may want to draw properly aligned lines using the pencil ('''Tools→Paint Tools→Pencil''') with a very thick round brush.

Once you create masks over all translated labels, load the previously exported PNG of the localized map. Copy the <tt>overlay-mask</tt> layer from the XCF to the PNG image, by dragging it from the layer view of the XCF to the image area of the PNG. ''Do not'' save the PNG image at that point, nor during any of the following steps; it should remain the ordinary, full localized image.

Select the <tt>overlay-mask</tt> layer just copied into the PNG (in fact, it will be named <tt>overlay-mask copy</tt>, and the only other layer should be <tt>Background</tt>) and execute '''Layer→Transparency→Alpha to Selection'''. This will create a selection out of the overlay layer:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/overlay-layer-to-mask.jpg</center>

What remains to be done is straightforward. Without removing the selection, make <tt>overlay-mask</tt> layer invisible, switch to the <tt>Background</tt> layer, execute '''Select→Invert''', execute '''Edit→Delete''', and the overlay cut is complete:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/overlay-final.jpg</center>

Save it as <tt>wesnoth--overlay.png</tt>, where <tt>--overlay</tt> ending is needed for the game to recognize that the image is not standalone, but an overlay. Remember to uncheck "Save color values from transparent pixels" option when exporting PNG, in order to create smaller overlay map.

You should save the XCF image with <tt>overlay-mask</tt> layer, rather than discarding it, so that at a later point you can modify the mask and repeat the few steps above to create the overlay cut (e.g. when translation of a label is changed).

== Gimp For Translators ==

Being a general-purpose bitmap-editing tool, beginners' tutorials on Gimp usually assume that the reader wants to go from the basics towards becoming a proficient Gimp user one day. This, however, provides too much breadth for the limited scope of retouching images for localization, as we are doing in this article. Of course, if you indeed would like to learn about bitmap editing in general, by all means do go through such tutorials (there are books too) in detail, and then return to this article to apply the obtained knowledge.

If, on the other hand, you'd rather "just get the job done" (such as, for the most part, the initial author of this article), the following subsections shortly explain some crucial elements of Gimp needed to follow the instructions on [[#Creating Localized Images|creating localized images]]. You can also consider them a guideline to what to pay special attention to, if the next thing you do is look for a more in-depth tutorial text.

=== Orientation ===

Here is a downscaled screenshot of what ''may'' pop up when Gimp 2.6 is started (Gimp's layout is highly configurable, so you may see something somewhat different), with most important areas marked with numbered red dots:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/gimp-windows.png</center>

Gimp uses ''single-document interface'', giving its elements as separate windows, such that they can be manipulated by the mechanisms of the desktop environment on which Gimp is run. For example, under typical Unix desktop environments (KDE, Gnome, etc.), user may want to work with Gimp on a virtual desktop dedicated to it.

Number (1) marks the window which will contain the image, once opened or created a new (it's empty on the screenshot). There will be as many of these windows as there are images opened. (2) is the "toolbox", the collection of icons representing Gimp's basic drawing, selection, transformation, etc. tools. All of them can also be activated from the '''Tools''' menu, and more importantly, by keyboard shortcuts. The two black/white overlapping rectangles at the bottom show the current foreground and background colors. You can select other colors by clicking on them. (3) is the tool options view, where the behavior of currently selected tool can be adjusted. (4) is the ''layer'' view, currently empty as no image is opened (more on layers later). These are just some of many elements of Gimp workspace, those most important to our present needs. If some is missing when you start Gimp on your machine, try turning it on through the '''Windows→Dockable Dialogs''' menu.

Let's now create an image, with ''transparent'' background. Go to '''File→New...''', set width and height to something smaller (e.g. 320×256 pixels), expand '''Advanced Options''', and under '''Fill with:''' select '''Transparency'''. In the image window you should now see a light-dark gray checkerboard pattern, and the layer view should list the <tt>Background</tt> layer.

To paint something on the empty image, select the pencil tool (click on pencil icon in toolbox, select '''Tools→Paint Tools→Pencil''' from the menu, or simply press N on keyboard). In tool options, click right of '''Brush:''' and select a bigger circle from the different brushes. Now simply start painting over the image, by holding left mouse button. Change the foreground color (by clicking on its rectangle in toolbox) to something else, then paint some more. Here's a possible result of this highly precise action we just undertook:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/gimp-nibblets.png</center>

Of note are the options to the pencil tool on the lower left (e.g. "Circle (19)" selected as brush), and the layers view which shows the single <tt>Background</tt> layer. What's this with layers, anyway?

=== Layers ===

Layers are one of fundamental concepts when working with just about any kind of images and drawings, bitmap or otherwise. Rather then theorizing about it, let us immediately create another layer. Either select '''Layer→New Layer...''' from the menu, click on the blank sheet icon in lower left corner of layer view, or press Ctrl+Shift+N. In the dialog that pops up, set layer name to <tt>Doodle</tt>, make sure '''Transparency''' is selected, and click '''Ok'''. In the layer view you will now see the <tt>Doodle</tt> layer, which will be highlighted and above the <tt>Background</tt> layer.

Repeat fooling around with pencil tool, while making sure that <tt>Doodle</tt> layer is highlighted in the layer view:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/gimp-nibblets-twolay.png</center>

Note the icons left of layer names in layer view: they reflect the layer content, and it appears that the black and blue lines are on <tt>Background</tt>, while red and white are on <tt>Doodle</tt> layer. This is precisely what had happened, because <tt>Background</tt> layer was the active one (highlighted in layer view) while painting the first time, and the <tt>Doodle</tt> layer while painting the second time.

Yet further left of layer names are "eye" icons, which show that layers are visible. Clicking on them will make layers visible or invisible; observe how the content of respective layer disappears and appears on the image together with switching the visibility. A layer can also be made semi-transparent, rather than completely invisible. Try playing with the '''Opacity:''' slider at the top of layer view while the <tt>Doodle</tt> layer is selected.

You may immediately realize some uses of layers. For example, a text label on a drawing can be added as a separate layer, without irreparably changing the basic drawing, such that it is easy to change the text later on. Layers can also be duplicated with all the content, in order to slightly change one and try which of the two versions better fits with the complete image. And so on. Any realistic image worked on with Gimp will contain at least several layers, and there may easily be tens of them.

Always keep in mind that, same as it happened above with the pencil tool, almost all painting, transforming, colorizing and other operations influence only the currently selected layer (the one highlighted in layer view). An easy oversight to make when there are many layers is to select the wrong layer, or forget to select the desired one, prior to performing an operation. Of course, there's always '''Undo'''.

=== Selection ===

Time to start copying and pasting things around. Same as with text, a portion of image needs to be first ''selected'', to be copied or cut, and then pasted. Unlike as with text, there are many ways in which the selection can be made: just take a look in '''Tools→Selection Tools'''. The basic of those is probably the rectangle selection; to activate it, click on dotted rectangle icon in toolbox, select '''Tools→Selection Tools→Rectangle Select''' from the menu, or press R on keyboard. Before doing anything, make sure <tt>Background</tt> layer is selected.

Left click somewhere on the image and drag the pointer. A translucent rectangle frame will spread from the point of click as you drag the pointer. After releasing the mouse button, the rectangle will become white-black dashed, with dashes moving around (the "marching ants" pattern). By this, you have made a selection (there will also be four smaller rectangles in its corners, which you can use to further adjust the selection sweep). To cancel the selection, without doing anything, just click somewhere outside of it.

Now copy the selection to clipboard, by pressing the usual Ctrl+C, or selecting '''Edit→Copy''' from the menu. Copying itself will not yield any visual effect. The important bits start to occur when you paste the copied selection, by Ctrl+V or '''Edit→Paste'''. Pasted selection will appear at the same place where the original was. There are several things to observe now:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/gimp-selection-copy-paste.png</center>

* The selection contour will be slightly changed to show exactly what was copied, omitting any transparent regions in the original selection.

* A new layer, named <tt>Floating Selection (Pasted Layer)</tt> has appeared. This is a ''temporary'' layer, which may either be made a permanent layer by selecting '''Layer→New Layer...''', or may be merged into the previously selected layer by canceling the selection (e.g. clicking outside of it). You can move the pasted layer around by left clicking and dragging within it.

* Because you have hit copy when <tt>Background</tt> layer was selected, only the content within selection and on that layer got copied and pasted. You can even make selection while one layer is active, then switch to another, and hit copy to grab the portion of that other layer. Also, while pasting action puts copy on its own temporary layer, canceling the selection will merge it into previously selected layer.

If you turn temporary pasted layer into a permanent layer, you will notice the motionless yellow-black dashed contour. It is also visible in the screenshot above, at sections not covered with moving white-black pattern. This contour shows the layer boundaries, that is, every layer can have its own size independent of the image size. The boundary size of a layer can be adjusted using '''Layer→Layer Boundary Size...'''. Instead of changing boundaries, layer can be resized with all its content using '''Layer→Scale Layer...'''.

You can now explore other ways of making selections (remember, clicking out of selection area while selection tool is active will cancel the current selection). E.g. if you choose '''Tools→Selection Tools→Fuzzy Select''', make <tt>Background</tt> layer active, and click somewhere on the thick blue line in the screenshot above, exactly this entire line will be selected. Every selection tool has some options in the tool view, which may be tweaked to affect exactly what is selected. For the fuzzy selection, for example, one can adjust the color sensitivity ('''Threshold:''' slider) to affect how much big a color difference is used to determine boundaries of selection.

Same as most modification operations affect only the currently selected layer, in presence of selection they also usually affect only the selected area. To test, make a rectangle selection, then switch to pencil tool and try to draw on the image. The pencil will leave trace only within the area of the selection, and on the currently active layer.

=== Text ===

Of the many painting tools, a particularly important one for localizing images will be, naturally, the text tool. It is activated by pressing the big A icon in the toolbox, '''Tools→Text''' menu item, or T on keyboard. Activate the text tool, and click somewhere on the image (to unclutter the view, make the <tt>Background</tt> and <tt>Doodle</tt> layers invisible). Click somewhere on the image, and a text input dialog will pop up. After typing something, we may obtain:

<center>http://svn.gna.org/viewcvs/*checkout*/wesnoth/branches/resources/image-localization/tutorial/gimp-text-tool.png</center>

Almost every part of this screenshots presents some important points.

On the left, the tool options for the text tools are shown. Here you can select the basics (font, size, and color), but also some other important options. The three checkboxes affect how the font is rendered: antialiasing makes letters non-jagged against the transparent background, and the two hinting options improve the shape of letters. You will almost always want to have all these checked. The justification buttons allow you to left-align, center, etc. the text. The three spinboxes bellow are used to tweak the spacing between letters (you can shrink the text that looks to wide, or shrink the distance between two lines of text).

In the center you can see the rendered text in top left corner of the image, and superimposed text input dialog over the image window. There you can also load some text from file, in case of longer texts.

On the right, in layer view, notice that the entered text got its own layer (named by the text itself), similar to what happens when selection is pasted. Unlike the temporary pasted layer, the text layer is permanent, but also special in that double-clicking its icon will allow you to edit the text at a later point (that's why its icon is a generic text-like icon, instead of showing layer content). Text layers can be changed into an ordinary layers by executing '''Layer→Discard Text Information''', but you will want to do this only if you need to do some arbitrary transformations on the text. The boundary of text layer is only as wide and high as the text, so you can move the text layer around.

=== Saving Images ===

Always save images first and formost in Gimp's native format, XCF. This will keep all the information, such as layers and selections, so that you can pick up editing the image just where you left. Consider the XCF format as your "source", on which you work and from which you "build" the final ordinary (or "flat") bitmap images.

When the image is ready for delivery, when you have made all necessary layers visible and helper or test layers invisible, you can save the image in one of flat bitmap formats. Two typical are PNG and JPEG, with the following very important difference between them. PNG is a "lossless" format, which means that every pixel in shown to the user just as it was in the source, XCF image, when the PNG was saved. JPEG is a "lossy" format, which compresses the image such that it's rather near to original, but not exactly and possibly with some ungainly visual artifacts, at the benefit of frequently considerably reducing the image size. PNG is what you will need for allmost all in-game localized images, as the originals are PNG images too. This is natural for game graphics, since it needs to be crisp, without any compression artifacts. JPEG is typically used for photographs, which would be huge if left uncompressed, and instructive screenshots which do not need crisp looks (e.g. for images in the manual).

To make a PNG image, you may as a matter of habit reach for '''File→Save As...''', and there select PNG as output format and save; then, to get back to the XCF source, you will close the PNG, and open the XCF again. To avoid this usual routine, there is the '''File→Save a Copy...''' action, which unlike '''Save As...''' will not switch to the newly saved PNG image, but let you continue working on the original XCF after saving.

[[Category:Translations]]

DirectActionsWML

2011-11-25T17:52:16Z

Zookeeper: Reverted edits by Zookeeper (Talk) to last revision by Gambit

DirectActionsWML

2011-11-25T16:51:31Z

Zookeeper: Noted that [object] duration= does not work

EventWML

2011-08-20T08:29:02Z

Zookeeper: Documented event remove as an optional key

{{WML Tags}}
== The [event] Tag ==

This tag is a subtag of the [scenario], [unit_type] and [era] tags which is used to describe a set of [[ActionWML|actions]] which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit_type] tag, the event will occur in all scenarios in which a unit of that type appears in (only after such a unit appears during the scenario, however). When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the word "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

=== The 'name' Key (Mandatory) ===

Usage:
name=<value>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

name=attacker misses,defender misses

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

==== Predefined 'name' Key Values ====

All predefined event types are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else. Spaces in event names can be interchanged with underscores (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

; preload
: Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.
: '''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

; prestart
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.
: '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

; start
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.
: '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

; new turn
: Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

; turn end {{DevFeature1.9}}
: Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

; turn ''X'' end {{DevFeature1.9}}
: Triggers at the end of turn ''X''.

; side turn
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

; ai turn
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.
: '''Note:''' ''This event currently breaks replays since it is not explicitly saved in a replay and there is no AI involved in replays...''

; turn refresh
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.

; turn ''X''
: Triggers at the start of turn ''X''. It's the first side initialization event.
:Side initialization events go in the order of:
: 1) '''turn ''X'''''
:2) '''new turn'''
:3) '''side turn'''
:4) '''side ''X'' turn'''
:5) '''side turn ''X'''''
:6) '''side ''X'' turn ''Y'''''
:7) '''turn refresh'''
:8) '''side ''X'' turn refresh'''
:9) '''turn ''X'' refresh'''
:10) '''side ''X'' turn ''Y'' refresh'''

; side ''X'' turn ''Y''
: This event triggers at the start of turn ''Y'' of side X {{DevFeature}}

; side ''X'' turn
: This event triggers at the start of any turn of side X {{DevFeature}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side turn ''X''
: This event triggers at the start of any side on turn X {{DevFeature1.9}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side X turn Y refresh
: This event triggers at the turn refresh for side X on turn Y {{DevFeature1.9}}

; side ''X'' turn refresh
: This event triggers at the turn refresh for side X {{DevFeature1.9}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; turn ''X'' refresh
: This event triggers for any side at the refresh of turn X. {{DevFeature1.9}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side turn end {{DevFeature1.9}}
: Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:
:1) '''side turn end'''
:2) '''side ''X'' turn end'''
:3) '''side turn ''X'' end'''
:4) '''side ''X'' turn ''Y'' end'''
:5) '''turn end'''
:6) '''turn ''X'' end'''

; time over
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])

; enemies defeated
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.

; victory
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])

; defeat
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])

Filters (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]

; moveto
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. If the unit moves to a village, the capture event will be fired before this event. <br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not undo other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' {{DevFeature}} $x2 and $y2 refer to the hex the unit came from.

; sighted
: '''important: "sighted" events are very buggy in general, especially if "delay shroud updates" is set to "yes". Avoid using them despite of them being (still) used a lot in mainline.''' {{DevFeature1.9}}: It is currently tested whether the introduction of the "whiteboard" feature is accepted, making it possible to remove the "delay shroud updates" option which could in return make this event stable again.
: A '''sighted''' event is triggered when a fog or shroud is lifted from the primary ''unit''. This can happen when a ''second_unit'' moves to a nearby location and discovers the primary ''unit''. Alternatively, the ''second_unit'' might emerge "out of the mist" and be discovered simultaneously by all members of the enemy side: in this case, the ''second_unit'' is not set. (This is part of the sighted event's bugs.)

: '''Note:''' The sighted event is ''only'' triggered when a unit moves from one location to another. When the player moves to attack an enemy unit and, in the process, removes the fog/shroud over an enemy unit, the sighted event does ''not'' fire. This makes the sighted event unreliable: It may or may not fire, depending on the user actions. (This may be part of the sighted event's bugs.)

: '''Alternatives:''' It is sometimes possible to replace a sighted event by a moveto event with a [[StandardLocationFilter|location filter]] matching a nearby location. A [[FilterWML#Filtering_Vision|filter_vision]] filter may be useful in some cases.

; attack
: Triggers when the primary unit attacks the secondary unit.

; attack end
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

; attacker hits
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

; attacker misses
: Same as ''attacker hits'', but is triggered when the attacker misses.

; defender hits
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

; defender misses
: Same as ''defender hits'', but is triggered when the defender misses.

; stone
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability). In {{DevFeature}}, this event name is changed to "petrified".

; last breath
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

; die
: Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want to the primary unit to make a final [message], use name=last_breath, see above.

; capture
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture. This event will be fired before the moveto event.

; recruit
: Triggers when the primary unit is recruited. (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

; prerecruit
: Triggers when the primary unit is recruited but before it is displayed.

; recall
: Triggers after a unit is recalled.

; prerecall
: Triggers when a unit is recalled but before it is displayed.

; advance
: Triggers just before the primary unit is going to advance to another unit.

; post advance
: Triggers just after the primary unit has advanced to another unit.

; select
: Triggers when the primary unit is selected. Also triggers when ending a move, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

; menu item ''X''
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

==== Custom events ====

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives.

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== id ====
: If an id is specified, then the event will not be added if another event with the same id already exists. An id will also allow the event to be removed, see below.

==== remove ====
: Whether to remove an event instead of adding a new one. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; if true, then the contents of the event are ignored and the event with the specified id is removed instead. for example:
[event]
id=id_of_event_to_remove
remove=yes
[/event]

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'' and ''attack end''. For more information and other filter keys, see [[FilterWML]].
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the secondary unit.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_condition] ====
: {{DevFeature1.9}}
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* True Condition Tags and Meta Condition Tags as described in [[ConditionalActionsWML]].
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

==== [filter_side] ====
: {{DevFeature1.9}}
: The current side (usually the side $side_number) must match the passed [[StandardSideFilter]] for the event to fire.
:* SSF tags and keys as arguments as described in [[StandardSideFilter]].
: note: This tag makes most sense in side turn and turn refresh events. However, all wml events have a current side so one could also prevent e.g. a moveto event from firing if you put a [filter_side] tag there and the moving unit's side doesn't match.

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all [[ActionWML|action tags]] within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

More details in [[ActionWML]].

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* sighted
* attack
* attack_end
* attacker hits
* attacker misses
* defender hits
* defender misses
* stone
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* post_advance
getting message options (etc) from the following events is not synchronized, except in the development version (1.9+svn):
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

You need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

=== Event IDs ===

{{DevFeature1.9}}

This problem can be avoided by setting an '''id''' on the event, i.e.:

#define DOUBLE
[event]
name=multiply_by_2
id=doubler_event
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

Events with an ID will only be run once each time the event is fired, no matter how many times they are included. Events with an ID can also be removed by using the '''remove''' key, i.e.:

[event]
id=doubler_event
remove=yes
[/event]

After that WML is run, if the ''multiply_by_2'' event is fired again, the doubler_event won't be run at all. After an event is removed, it can still be re-added later.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

[event]
name=die
[message]
speaker='''second_unit'''
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker='''unit'''
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]

An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.

=== Delayed Variable Substitution Example ===

This code will display a message showing the turn number on which the nested ''moveto'' event happens.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

The following code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Finally, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $|turn_number"}
[/event]
[/event]

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.
[event]# parent
name=turn 2
#delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event]# child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event]# great-grandchild
name=turn 5
{DEBUG_MSG $turn_number}# output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EventWML

2011-08-20T08:13:50Z

Zookeeper: Documented event id as an optional key

{{WML Tags}}
== The [event] Tag ==

This tag is a subtag of the [scenario], [unit_type] and [era] tags which is used to describe a set of [[ActionWML|actions]] which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit_type] tag, the event will occur in all scenarios in which a unit of that type appears in (only after such a unit appears during the scenario, however). When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

'''Lexicon side note:''' ''The word "event" in the [event] tag itself may be considered an abbreviation of the word "event handler" because it is technically not a game "event" but an event '''handler''' for the game events fired with the given 'name'. However, this distinction is usually unimportant in most discussions and the event handlers are therefore simply referred to as "events" in this documentation.''

=== The 'name' Key (Mandatory) ===

Usage:
name=<value>

This key defines which game event or trigger your [event] tag will be handling. This 'name' key should not be confused with a descriptive comment; it is rather a precise value which must match the predefined game event's name to be valid.

'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

name=attacker misses,defender misses

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

==== Predefined 'name' Key Values ====

All predefined event types are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else. Spaces in event names can be interchanged with underscores (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

; preload
: Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.
: '''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

; prestart
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.
: '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

; start
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.
: '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

; new turn
: Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

; turn end {{DevFeature1.9}}
: Triggers at the end of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. The WML variable '''side_number''' will contain the side that ended their turn.

; turn ''X'' end {{DevFeature1.9}}
: Triggers at the end of turn ''X''.

; side turn
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

; ai turn
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.
: '''Note:''' ''This event currently breaks replays since it is not explicitly saved in a replay and there is no AI involved in replays...''

; turn refresh
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.

; turn ''X''
: Triggers at the start of turn ''X''. It's the first side initialization event.
:Side initialization events go in the order of:
: 1) '''turn ''X'''''
:2) '''new turn'''
:3) '''side turn'''
:4) '''side ''X'' turn'''
:5) '''side turn ''X'''''
:6) '''side ''X'' turn ''Y'''''
:7) '''turn refresh'''
:8) '''side ''X'' turn refresh'''
:9) '''turn ''X'' refresh'''
:10) '''side ''X'' turn ''Y'' refresh'''

; side ''X'' turn ''Y''
: This event triggers at the start of turn ''Y'' of side X {{DevFeature}}

; side ''X'' turn
: This event triggers at the start of any turn of side X {{DevFeature}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side turn ''X''
: This event triggers at the start of any side on turn X {{DevFeature1.9}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side X turn Y refresh
: This event triggers at the turn refresh for side X on turn Y {{DevFeature1.9}}

; side ''X'' turn refresh
: This event triggers at the turn refresh for side X {{DevFeature1.9}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; turn ''X'' refresh
: This event triggers for any side at the refresh of turn X. {{DevFeature1.9}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side turn end {{DevFeature1.9}}
: Triggers after a side ends its turn. Like side turn, there are also some variations for specific combinations of side number and turn number. Here is the order in which the turn end events trigger:
:1) '''side turn end'''
:2) '''side ''X'' turn end'''
:3) '''side turn ''X'' end'''
:4) '''side ''X'' turn ''Y'' end'''
:5) '''turn end'''
:6) '''turn ''X'' end'''

; time over
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])

; enemies defeated
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.

; victory
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])

; defeat
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])

Filters (except [filter_condition] which is for all sorts of events) can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]

; moveto
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on. If the unit moves to a village, the capture event will be fired before this event. <br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not undo other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' {{DevFeature}} $x2 and $y2 refer to the hex the unit came from.

; sighted
: '''important: "sighted" events are very buggy in general, especially if "delay shroud updates" is set to "yes". Avoid using them despite of them being (still) used a lot in mainline.''' {{DevFeature1.9}}: It is currently tested whether the introduction of the "whiteboard" feature is accepted, making it possible to remove the "delay shroud updates" option which could in return make this event stable again.
: A '''sighted''' event is triggered when a fog or shroud is lifted from the primary ''unit''. This can happen when a ''second_unit'' moves to a nearby location and discovers the primary ''unit''. Alternatively, the ''second_unit'' might emerge "out of the mist" and be discovered simultaneously by all members of the enemy side: in this case, the ''second_unit'' is not set. (This is part of the sighted event's bugs.)

: '''Note:''' The sighted event is ''only'' triggered when a unit moves from one location to another. When the player moves to attack an enemy unit and, in the process, removes the fog/shroud over an enemy unit, the sighted event does ''not'' fire. This makes the sighted event unreliable: It may or may not fire, depending on the user actions. (This may be part of the sighted event's bugs.)

: '''Alternatives:''' It is sometimes possible to replace a sighted event by a moveto event with a [[StandardLocationFilter|location filter]] matching a nearby location. A [[FilterWML#Filtering_Vision|filter_vision]] filter may be useful in some cases.

; attack
: Triggers when the primary unit attacks the secondary unit.

; attack end
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

; attacker hits
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

; attacker misses
: Same as ''attacker hits'', but is triggered when the attacker misses.

; defender hits
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

; defender misses
: Same as ''defender hits'', but is triggered when the defender misses.

; stone
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability). In {{DevFeature}}, this event name is changed to "petrified".

; last breath
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered. Use this instead of name=die when you want the primary unit to make a final [message].

; die
: Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.'' If you want to the primary unit to make a final [message], use name=last_breath, see above.

; capture
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture. This event will be fired before the moveto event.

; recruit
: Triggers when the primary unit is recruited. (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

; prerecruit
: Triggers when the primary unit is recruited but before it is displayed.

; recall
: Triggers after a unit is recalled.

; prerecall
: Triggers when a unit is recalled but before it is displayed.

; advance
: Triggers just before the primary unit is going to advance to another unit.

; post advance
: Triggers just after the primary unit has advanced to another unit.

; select
: Triggers when the primary unit is selected. Also triggers when ending a move, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

; menu item ''X''
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

==== Custom events ====

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives.

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== id ====
: If an id is specified, then the event will not be added if another event with the same id already exists. An id will also allow the event to be removed, see [[InternalActionsWML]].

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'' and ''attack end''. For more information and other filter keys, see [[FilterWML]].
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the secondary unit.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_condition] ====
: {{DevFeature1.9}}
: This tag makes sense inside any sort of event - even those that don't have units, or custom events,... The event will only trigger if this condition evaluates to true.
:* True Condition Tags and Meta Condition Tags as described in [[ConditionalActionsWML]].
: note: This tag is meant to be used when the firing of an event shall be based on variables/conditions which cannot be retrieved from the filtered units.

==== [filter_side] ====
: {{DevFeature1.9}}
: The current side (usually the side $side_number) must match the passed [[StandardSideFilter]] for the event to fire.
:* SSF tags and keys as arguments as described in [[StandardSideFilter]].
: note: This tag makes most sense in side turn and turn refresh events. However, all wml events have a current side so one could also prevent e.g. a moveto event from firing if you put a [filter_side] tag there and the moving unit's side doesn't match.

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all [[ActionWML|action tags]] within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

More details in [[ActionWML]].

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* sighted
* attack
* attack_end
* attacker hits
* attacker misses
* defender hits
* defender misses
* stone
* last breath
* menu item X
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* post_advance
getting message options (etc) from the following events is not synchronized, except in the development version (1.9+svn):
* new turn
* side turn
* turn X
* side X turn
* side X turn Y
* turn refresh

There is also the possibility of events that are normally synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

You need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

=== Event IDs ===

{{DevFeature1.9}}

This problem can be avoided by setting an '''id''' on the event, i.e.:

#define DOUBLE
[event]
name=multiply_by_2
id=doubler_event
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

Events with an ID will only be run once each time the event is fired, no matter how many times they are included. Events with an ID can also be removed by using the '''remove''' key, i.e.:

[event]
id=doubler_event
remove=yes
[/event]

After that WML is run, if the ''multiply_by_2'' event is fired again, the doubler_event won't be run at all. After an event is removed, it can still be re-added later.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

[event]
name=die
[message]
speaker='''second_unit'''
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker='''unit'''
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]

An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.

=== Delayed Variable Substitution Example ===

This code will display a message showing the turn number on which the nested ''moveto'' event happens.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

The following code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Finally, the following example is identical to the first two in that it will display a message showing the turn number on which the nested ''moveto'' event happens, despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $|turn_number"}
[/event]
[/event]

=== Multiple Nested Events ===

Every delayed_variable_substitution=no causes a variable substitution run on the subevent where it occurs at the spawn time of this event and on all following subevents. For any specific event, variable substitution happens at least one time when the event is executed. For each delayed=no key appearing in itself or in an event of an "older" generation, which is not the toplevel event, an additional variable substitution run is made.
[event]# parent
name=turn 2
#delayed_variable_substitution=no # In the parent event, delayed= has no effect.

[event]# child
name=turn 3
delayed_variable_substitution=no # Causes variable substitution in the child, grandchild and great-grandchild event
# at execution time of the parent event = spawn time of the child event.

[event]# grandchild
name=turn 4
delayed_variable_substitution=yes # no variable substitution in the grandchild and great-grandchild event
# at execution time of the child event = spawn time of the grandchild event

[event]# great-grandchild
name=turn 5
{DEBUG_MSG $turn_number}# output: 2 - value from the variable substitution at execution time of the parent event,
# caused by delayed=no in the child event

{DEBUG_MSG $||turn_number}# output: "$turn_number"
# Each variable substitution transforms a "$|" to a "$" (except when no | left).

{DEBUG_MSG $|turn_number}# output: 5 - from the variable substitution at execution time
# of the great-grandchild event
[/event]
[/event]
[/event]
[/event]

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EffectWML

2011-05-30T16:02:17Z

Zookeeper: Grouped [filter] with the other keys/tags instead of only mentioning it in the summary.

{{WML Tags}}
== the [effect] tag ==

The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification. Modifications are permanent changes to a unit; currently there is no way of removing a modification.

The following keys and subtags are always recognized:
* '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details.
* '''unit_type''': only apply this effect if the affected unit's type name matches the value. (can be a list)
* '''unit_gender''': only apply this effect if the affected unit's gender name matches the value. (can be a list)
* '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level.
* '''apply_to''': describes what the effect actually affects.
[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* '''new_attack''': will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML]].
* '''remove_attacks''': remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* '''attack''': find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''[set_specials]''': change the attack's specials. The specials to add are given exactly as in the [specials] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
** '''remove_specials''': remove the listed specials. The value of this key is the coma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML]] for explanations about defense_weight.
* '''hitpoints''': modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* '''movement''': modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
* '''max_experience''': affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
* '''loyal''': no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* '''movement_costs''': speed through specific terrain is modified
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[movement_costs]''': a subtag that describes the new movement costs just like in [[UnitTypeWML]] for describing a unit type
* '''defense''': Sets unit chance to be hit in specific terrain (100 - defense value)
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[defense]''': a subtag that describes the new defense just like in [[UnitTypeWML]] for describing a unit type
* '''resistance''': Sets percent damage taken from combat
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[resistance]''': a subtag that describes the new resistance just like in [[UnitTypeWML]] for describing a unit type
* '''variation''': switches the unit into one of its variations.
** '''name''': the id of the variation to invoke.
* '''type''': transforms the unit into a new unit_type.
** '''name''': the id of the unit_type to invoke.
* '''status''': modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* '''zoc''': toggle the zone of control.
** '''value''': new value for zoc (0=disable, other=enable).
* '''profile''': customize the profile of the unit. See [[UnitTypeWML]].
** '''portrait''': new image to display when the unit speaks.
** '''small_portrait''': {{DevFeature1.9}} new image to display in unit reports.
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane.
* '''new_ability''': Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag.
* '''new_animation''': contain animations that will be added to the unit, it can contain multiple animation blocks, {{DevFeature1.9}} and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster.
* '''image_mod''': modify the image path function([[ImagePathFunctionWML]]) of all the unit's frames.
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
* '''ellipse''': Change the image used for the unit's ellipse.
**'''ellipse''' : the new image to use.

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

Create

2011-01-20T17:37:35Z

Zookeeper: Undo revision 39474 by Trevor75 (Talk)

{| style="float:right"
|
__TOC__
|}

Interested in creating your own scenarios and campaigns? One of Wesnoth's best features is its extensibility. Players can create new maps, units, races, scenarios, art, music, and even entire campaigns. Access to the "guts" of the game is both simple and difficult; if you have an ASCII text editor you have everything you need to build your own world. However, learning the Wesnoth Markup Language (WML) takes some effort. This section will guide you through the process of creating and distributing your own content.

It should also be noted that '''we need a lot of help creating artwork for the core of the game.''' The current projects we are working on are [http://www.wesnoth.org/forum/viewtopic.php?t=2014&start=0&postdays=0&postorder=asc&highlight= listed here]. We'll happily help you out, if you take a swing at them.

== Read this first! ==
Before you modify or add anything, it is important to understand how the game stores and organizes its data. This article will explain the game's directory structure and introduce the ''userdata'' directory.
* [[EditingWesnoth]]

== What can I create, and how? ==

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.4-4.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.4-4-175.jpg]
<div class="thumbcaption">Battle for Wesnoth map editor</div></div>
</div>

* [[BuildingMaps|Maps]] - the layout of terrain tiles

* [[BuildingScenarios|Scenarios]] - a scenario makes things happen on a map, making it playable '''(outdated)'''
* [[BuildingCampaigns|Campaigns]] - how to put it all together into a campaign '''(outdated)'''
* [[BuildingMultiplayer|Multiplayer Maps and Scenarios]] - a specialized look at maps and scenarios '''(outdated)'''
* [[MultiplayerCampaigns|Multiplayer Campaigns]] - making a campaign accessible in multiplayer '''(outdated)'''
* [[BuildingUnits|Units]] '''(outdated)'''
* [[BuildingFactions|Multiplayer factions and eras]] '''(outdated)'''

* [[Create Art|Art]] - complete with '''tutorials!'''
* [[Create Music|Music]]
* [[Create Writing|Writing]]
* [[WesnothTranslations|Translations]] - work on translating Wesnoth

* [[Distributing content]] - all about the campaign server
* [[Authoring tools]] - tools for helping you write campaign WML
* [[Maintenance tools]] - tools for helping you sanity-check and maintain campaigns.
* [[Clueless Guides]] - half-baked guides that wait for improvement.

== What have others done? ==

There are a multitude of multiplayer maps and discussion of the campaigns on the [http://www.wesnoth.org/forum Wesnoth forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario and campaign development forum]
* [[Faction|Complete faction list]]

If you want to be creative without having to invent an entire new campaign,
see this thread on [http://www.wesnoth.org/forum/viewtopic.php?t=17171 abandoned campaigns]. You should be able to pick one of these up and complete it with much less effort than doing an all-new one.

== The world of Wesnoth ==
Not all campaigns take place in Wesnoth, but many do. There is definitely a certain flavor to campaigns that are intended to take place somewhere in the world of Wesnoth. Stake out a time period or a map locale and tell a story.
* [[History of Wesnoth|The history of Wesnoth]]
* [[Geography of Wesnoth|The geography of Wesnoth]]
* [[Races|The races of creatures in Wesnoth]]
* [[Poetry of Wesnoth|Wesnothian poetry]]
* [[Fan fiction]]

== Miscellaneous ==
* [[ExternalUtilities| External Utilities]] - some extra tools for easier creating stuff
* [[ReferenceWML|WML Reference]] - a quicklink
* [[FAQ#Maps.2C_Scenarios_and_Campaigns|FAQ]] - if you have a question, post it
* Addon server [http://addons.wesnoth.org web interface] - An alternate way to download user made content

<div style="border:1px solid #5599FF; margin-top: 10px; margin-bottom: 5px; padding: 5px;">
- [[Create|English]] - [[Créer vf|Français]] - [[Створити|Українська]]
</div>

[[Category:Create|*]]

Create

2011-01-20T17:28:51Z

Zookeeper: Reverted edits by RayRichardson (Talk) to last revision by Apromix

{| style="float:right"
|
__TOC__
|}

Interested in creating your own scenarios and campaigns? One of Wesnoth's best features is its extensibility. Players can create new maps, units, races, scenarios, art, music, and even entire campaigns. Access to the "guts" of the game is both simple and difficult; if you have an ASCII text editor you have everything you need to build your own world. However, learning the Wesnoth Markup Language (WML) takes some effort. This section will guide you through the process of creating and distributing your own content.

It should also be noted that '''we need a lot of help creating artwork for the core of the game.''' The current projects we are working on are [http://www.wesnoth.org/forum/viewtopic.php?t=2014&start=0&postdays=0&postorder=asc&highlight= listed here]. We'll happily help you out, if you take a swing at them.

== Read this first! ==
Before you modify or add anything, it is important to understand how the game stores and organizes its data [http://www.thesiswritingservice.com/ thesis writers]. This article will explain the game's directory structure and introduce the ''userdata'' directory.
* [[EditingWesnoth]]

== What can I create, and how? ==

<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.4-4.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.4-4-175.jpg]
<div class="thumbcaption">Battle for Wesnoth map editor</div></div>
</div>

* [[BuildingMaps|Maps]] - the layout of terrain tiles

* [[BuildingScenarios|Scenarios]] - a scenario makes things happen on a map, making it playable '''(outdated)'''
* [[BuildingCampaigns|Campaigns]] - how to put it all together into a campaign '''(outdated)'''
* [[BuildingMultiplayer|Multiplayer Maps and Scenarios]] - a specialized look at maps and scenarios '''(outdated)'''
* [[MultiplayerCampaigns|Multiplayer Campaigns]] - making a campaign accessible in multiplayer '''(outdated)'''
* [[BuildingUnits|Units]] '''(outdated)'''
* [[BuildingFactions|Multiplayer factions and eras]] '''(outdated)'''

* [[Create Art|Art]] - complete with '''tutorials!'''
* [[Create Music|Music]]
* [[Create Writing|Writing]]
* [[WesnothTranslations|Translations]] - work on translating Wesnoth

* [[Distributing content]] - all about the campaign server
* [[Authoring tools]] - tools for helping you write campaign WML
* [[Maintenance tools]] - tools for helping you sanity-check and maintain campaigns.
* [[Clueless Guides]] - half-baked guides that wait for improvement.

== What have others done? ==

There are a multitude of multiplayer maps and discussion of the campaigns on the [http://www.wesnoth.org/forum Wesnoth forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer development forum]
* [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario and campaign development forum]
* [[Faction|Complete faction list]]

If you want to be creative without having to invent an entire new campaign,
see this thread on [http://www.wesnoth.org/forum/viewtopic.php?t=17171 abandoned campaigns]. You should be able to pick one of these up and complete it with much less effort than doing an all-new one.

== The world of Wesnoth ==
Not all campaigns take place in Wesnoth, but many do. There is definitely a certain flavor to campaigns that are intended to take place somewhere in the world of Wesnoth. Stake out a time period or a map locale and tell a story.
* [[History of Wesnoth|The history of Wesnoth]]
* [[Geography of Wesnoth|The geography of Wesnoth]]
* [[Races|The races of creatures in Wesnoth]]
* [[Poetry of Wesnoth|Wesnothian poetry]]
* [[Fan fiction]]

== Miscellaneous ==
* [[ExternalUtilities| External Utilities]] - some extra tools for easier creating stuff
* [[ReferenceWML|WML Reference]] - a quicklink
* [[FAQ#Maps.2C_Scenarios_and_Campaigns|FAQ]] - if you have a question, post it
* Addon server [http://addons.wesnoth.org web interface] - An alternate way to download user made content

<div style="border:1px solid #5599FF; margin-top: 10px; margin-bottom: 5px; padding: 5px;">
- [[Create|English]] - [[Créer vf|Français]] - [[Створити|Українська]]
</div>

[[Category:Create|*]]

EffectWML

2010-11-23T06:59:37Z

Zookeeper: Added add= for apply_to=image_mod

{{WML Tags}}
== the [effect] tag ==

The tag [effect] is used to describe one modification to a unit.
Any number of [effect] tags can be used to describe a complete
modification.
Modifications are permanent changes to a unit;
currently there is no way of removing a modification.
Effects can contain a [filter] tag which applies the effect only if it matches.
See [[StandardUnitFilter]] for details.

The following keys are always recognized for [effect]:
* '''unit_type''': only apply this effect if the affected unit's type name matches the value. (can be a list)
* '''unit_gender''': only apply this effect if the affected unit's gender name matches the value. (can be a list)
* '''times''': describes how much time the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level.
* '''apply_to''': describes what the effect actually affects.
[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values:
* '''new_attack''': will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in [[UnitTypeWML]].
* '''remove_attacks''': remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. Do not use a [filter] tag otherwise it will not work properly.
* '''attack''': find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** '''set_name''': change the attack's name (ie identifier).
** '''set_description''': change the attack's description (ie displayed name).
** '''set_type''': change the attack type. The standard values are '''blade''', '''pierce''', '''impact''', '''fire''', '''cold''', and '''arcane'''.
** '''[set_specials]''': change the attack's specials. The specials to add are given exactly as in the [specials] tag.
*** '''mode''': if '''append''', adds the given specials to the attack. If '''replace''', replaces the existing specials with the given ones. Default '''replace'''.
** '''remove_specials''': remove the listed specials. The value of this key is the coma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** '''increase_damage''': increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** '''increase_attacks''': increases the number of attack strikes. Like '''increase_damage''', it can be positive or negative, or a percentage.
** '''attack_weight''': change the attack's attack_weight. See [attack] in [[UnitTypeWML]] for explanations about attack_weight.
** '''defense_weight''': change the attack's defense_weight. See [attack] in [[UnitTypeWML]] for explanations about defense_weight.
* '''hitpoints''': modifies the unit's HP and/or max HP.
** '''increase''': the amount to increase the unit's HP.
** '''heal_full''': if present and not set to "no" the unit will be put back to full HP.
** '''increase_total''': will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** '''violate_maximum''': it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. '''yes'''), the unit's HP won't be lowered to its max HP.
* '''movement''': modifies the unit's movement points.
** '''increase''': maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** '''set''': maximum movement is set to a specific value.
* '''max_experience''': affects the amount of XP the unit needs for the next level.
** '''increase''': how to change the xp; again it can be negative, positive or a percentage.
* '''loyal''': no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* '''movement_costs''': speed through specific terrain is modified
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[movement_costs]''': a subtag that describes the new movement costs just like in [[UnitTypeWML]] for describing a unit type
* '''defense''': Sets unit chance to be hit in specific terrain (100 - defense value)
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[defense]''': a subtag that describes the new defense just like in [[UnitTypeWML]] for describing a unit type
* '''resistance''': Sets percent damage taken from combat
** '''replace''': If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** '''[resistance]''': a subtag that describes the new resistance just like in [[UnitTypeWML]] for describing a unit type
* '''variation''': switches the unit into one of its variations.
** '''name''': the id of the variation to invoke.
* '''type''': transforms the unit into a new unit_type.
** '''name''': the id of the unit_type to invoke.
* '''status''': modifies the status affecting the unit.
** '''add''': a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** '''remove''': a list of status modifications to remove.
* '''zoc''': toggle the zone of control.
** '''value''': new value for zoc (0=disable, other=enable).
* '''profile''': customize the profile for this unit type
** '''portrait''': new image to display when the unit speaks
** '''description''': sets the text to display when hovering over the unit's type in the righthand pane
* '''new_ability''': Adds one or more abilities to a unit.
** '''[abilities]''': A subtag that contains the ability definitions.
* '''remove_ability''': Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
** '''[abilities]''': A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag.
* '''new_animation''': contain animations that will be added to the unit, it can contain multiple animation blocks, {{DevFeature1.9}} and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster.
* '''image_mod''': modify the image path function([[ImagePathFunctionWML]]) of all the unit's frames.
** '''replace''': replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
** '''add''': adds an image path function without removing any existing ones.
* '''ellipse''': Change the image used for the unit's ellipse.
**'''ellipse''' : the new image to use.

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]
* [[AnimationWML]]

[[Category: WML Reference]]

InterfaceActionsWML

2010-11-14T10:01:11Z

Zookeeper: Documented [floating_text]

{{WML Tags}}
== Interface actions ==

Interface actions are actions that do not have an effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [inspect] ==
This user interface action only works in debug mode. It displays the gamestate inspector dialog (the same one which can be brought up with '':inspect'' ), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.

* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed).<br>'''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.
* '''scroll''': {{DevFeature1.9}} Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[InternalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_length''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===
In 1.8, [http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes] have been adopted for '''[message]'''. These can also be used in unit names (user_description), objectives, and such. Note that you'll probably want to use a single quote ' instead of a double quote " as double quotes cannot be escaped, otherwise the string will appear fragmented and you may also encounter errors. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:

<nowiki><span color='#BCB088' size='large' font-style='italic'>You are victorious!</span></nowiki>

These are the codes taken from the Pango markup formatting guide:

*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".
*'''font_family''', '''face''': A font family name.
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
*'''strikethrough''': 'true' or 'false' whether to strike through the text.
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.
*'''gravity_hint''': One of 'natural', 'strong', 'line'.

In 1.6, Wesnoth uses older text formatting options
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

This tag renders the ''objectives'' attribute of [scenario] obsolete (see ''objectives'', [[ScenarioWML]]).
Instead of using ''objectives'', use '''[objectives]''' to set scenario objectives inside a prestart event.
It can also be used to overwrite the starting objectives mid-scenario.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides.
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives.
* '''gold_carryover_string''' {{DevFeature1.9}}: Default ' _ "Gold carryover:"', this text precedes the gold carryover information.
* '''notes_string''' {{DevFeature1.9}}: Default ' _ "Notes:"', this text precedes the notes.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.

Tags of '''[objectives]''':
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''show_turn_counter''' {{DevFeature1.9}}: If set to yes, displays the number of turns remaining in the scenario. Only works if '''condition'''=lose. Default is no.
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only. {{DevFeature}}
* '''[gold_carryover]''' {{DevFeature1.9}}: describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.
* '''[note]''' {{DevFeature1.9}}: describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.
** '''description''': the text of the note.

=== Macros ===
There are a few predefined macros for Objectives that you can use to shorten the code: [http://www.wesnoth.org/macro-reference.xhtml#SET_OBJECTIVES SET_OBJECTIVES], [http://www.wesnoth.org/macro-reference.xhtml#VICTORY_CONDITION VICTORY_CONDITION], and [http://www.wesnoth.org/macro-reference.xhtml#DEFEAT_CONDITION DEFEAT_CONDITION]. Follow the links for each one to see complete syntax and example usage.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.

'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[InternalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.

== Other interface tags ==

The following tags are also action tags:
* '''[item]''': makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros))''</tt>
** '''x''', '''y''': the location to place the item.
** '''image''': the image (in ''images/'' as .png) to place on the hex.
** '''halo''': an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image. ''Example (where the integer after the colon is the duration of each frame): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
** '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
** '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''[removeitem]''': removes any graphical items on a given hex. (In version 1.9.2, this was renamed to '''[remove_item]''')
** '''x''', '''y''': the hex to remove items off
** '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)
* '''[print]''': displays a message across the screen. The message will disappear after a certain time.
** '''text''': (translatable) the text to display.
** '''size''': (default=12) the pointsize of the font to use
** '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
* '''[move_unit_fake]''': moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
** '''type''': the type of the unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
** '''gender''': the gender of the fake unit. Example: gender=female
** '''variation''': the variation of the fake unit. Example: variation=undead
* '''[move_units_fake]''': {{DevFeature1.9}} moves multiple images of units along paths on the map. These units are moved in lockstep.
** '''[fake_unit]''': A fake unit to move
*** '''type''': the type of unit whose image to use
*** '''x''': a comma-separated list of x locations to move along
*** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
*** '''side''': the side of the fake unit, used for team-coloring the fake unit
*** '''skip_steps''': the number of steps to skip before this unit starts moving
* '''[hide_unit]''': temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Each '''[hide_unit]''' tag only hides one unit.
** '''x''', '''y''': location of the unit to be hidden. (NOT a standard unit filter! Just x and y.)
** {{DevFeature1.9}}: '''[hide_unit]''' accepts a [[StandardUnitFilter]] as argument and can disable several units at once.
* '''[unhide_unit]''': stops the currently hidden units from being hidden.
** {{DevFeature1.9}}: '''[unhide_unit]''' accepts a [[StandardUnitFilter]] as argument.
* '''[scroll]''': Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
** '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''[scroll_to]''': Scroll to a given hex
** '''x''', '''y''': the hex to scroll to
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* '''[scroll_to_unit]''' Scroll to a given unit
** [[StandardUnitFilter]]
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* '''[select_unit]''': {{DevFeature1.9}} Selects a given unit
** [[StandardUnitFilter]]
** '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no'').
** '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').
* '''[sound]''': Plays a sound
** '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
** '''repeat''': repeats the sound for a specified additional number of times (default=0)
* '''[sound_source]''': Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
** '''id''': a unique identification key of the sound source
** '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
** '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
** '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
** '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
** '''check_shrouded''': {{DevFeature}} possible values "true" and "false" - if true the source will not play if its locations are shrouded
** '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source
** '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
** '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
** '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)
* '''[remove_sound_source]''': Removes a previously defined sound source.
** '''id''': the identification key of the sound source to remove
* '''[music]''': Switches to playing different music
** '''name''': the filename of the music to play (in ''music/'' as .ogg)
** see [[MusicListWML]] for the correct syntax
* '''[volume]''': {{DevFeature1.9}} Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100:
** '''music''': Changes the music volume.
** '''sound''': Changes the sound volume.
* '''[colour_adjust]''': tints the color of the screen. {{DevFeature1.9}}: now named '''[color_adjust]'''.
** '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color
* '''[delay]''': pauses the game
** '''time''': the time to pause in milliseconds
* '''[redraw]''': redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
** '''side''': if used, recalculates fog and shroud for that side. Useful if you for example spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[unit_overlay]''': sets an image that will be drawn over a particular unit, and follow it around
** '''x''', '''y''': the location of the unit to overlay on
** '''image''': the image to place on the unit
** {{DevFeature1.9}}: '''[unit_overlay]''' accepts a [[StandardUnitFilter]] as argument
* '''[remove_unit_overlay]''': removes a particular overlayed image from a unit
** '''x''', '''y''': the location of the unit to remove an overlay from
** '''image''': the image to remove from the unit
** {{DevFeature1.9}}: '''[remove_unit_overlay]''' accepts a [[StandardUnitFilter]] as argument
* '''[animate_unit]''': Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).
** '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelin levelout healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
** '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.
** '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].
** '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.
** '''hits''': yes/no: which according variation of a attack/defense animation shall be chosen (required)
** '''text''': a text to hover during the animation
** '''red''': red value for the text color (0-255)
** '''green''': green value for the text color
** '''blue''': blue value for the text color
** '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)
** '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.
** '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated
* '''[label]''' places a label on the map.
** '''x''', '''y''': the location of the label
** '''text''': what the label should say
** '''team_name''': if specified, the label will only be visible to the given team.
** '''colour''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255. {{DevFeature1.9}}: now named '''color'''.
** '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
** '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.
** '''immutable''': whether this label is protected from being removed or changed by players. Default yes. {{DevFeature1.9}}
* '''[floating_text]''': {{DevFeature1.9}} floats text (similar to the damage and healing numbers) on the given locations.
** [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.
** '''text''': the text to display.
* '''[deprecated_message]''' shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
** '''message''': the message to show.
* '''[wml_message]''' outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
** '''message''': the message to show.
** '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.
* '''[open_help]''' opens the in-game help.
** '''topic''': the id of the topic to open
* '''[show_objectives]''': {{DevFeature}} refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
** '''side''': the side to show the objectives. If not set, all sides are used.
* '''[chat]''' displays a message in the chat area. {{DevFeature1.9}}
** '''speaker''': The sender of the message. Normally this is a string. However if you enter the name of a variable in which a unit is stored (such as ''second_unit'') it will display that unit's name instead.
** '''message''': The message that should be displayed
** '''side''': A comma separated list of sides to show the message to. If the same machine controls multiple sides that are in this list, then the message will only be displayed once. If left blank the message will be send to all sides.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{FLOATING_TEXT}''' Float some text over a unit similar to the damage numbers.
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor like screenshake and plays <soundfile>. ('''{TREMOR}''' is a deprecated version, equivalent to '''{QUAKE (rumble.ogg)}''')
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

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

BuildingCampaigns

2010-11-11T22:36:36Z

Zookeeper:

{| style="float:right; margin-left:1em;"
|__TOC__
|}

This page describes how to make your own user campaign for use with Battle for Wesnoth. Please note that this document is not normative - its author is not a Wesnoth developer. I'm simply reporting on what works for me, and on what developers have prescribed elsewhere.
If you see any errors, please fix them.

See also [[DebuggingCampaigns]] if your scenario doesn't load.

There are several steps to building a single player campaign in Wesnoth. The mechanics are covered in the sections below:

* [[BuildingCampaignsDirectoryStructure]]
* [[BuildingCampaignsTheCampaignFile]]
* [[BuildingCampaignsThePBLFile]]
* [[BuildingCampaignsDistribution]]
* [[WesCamp]] (How to make your campaign translatable, and get in touch with translators)
* [[Wesnoth UMC Dev]] (Where you can collaborate on UMC projects)

Because many aspiring campaign developers find the initial creation of a working campaign to be difficult (if not exasperating) a [[BuildingCampaignsTutorial|step-by-step tutorial]] covering the initial phase of campaign development (getting it to work) is under construction. It includes a working campaign that you can install, and then alter to fit your own needs

Xer has also created a campaign skeleton which is the barebones of a campaign: [http://www.wesnoth.org/forum/download/file.php?id=24587 here]

What follows is a collection of advice to aspiring campaign designers extracted from the Wesnoth fora. For a more in-depth treatment including heuristics for scenario and campaign balancing, see the [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To].

== Start with Something Manageable ==

If you set out to make an epic campaign spanning the whole history of Wesnoth, you'll likely (not necessarily, though)
become bored or frustrated along the
way somewhere and give up. It's much easier to start with a small story and add elements to it than it is to cut an
epic down to the length of a haiku.

;Shade (author of The Rise of Wesnoth) wrote<nowiki>:</nowiki>
: I started TRoW last April, even after it was scenario complete it was still eating all of my free time (Time not spent sleeping, at school / work, or with loved ones / friends) until mid-November... Even now there is still bugfixing and a couple of things I'd like to add... and keeping it up to date with the game engine and any new happenings on the WML front... so there is still quite a lot to keep you busy after you are done... The forums are littered with half finished epics... Before you commit to an epic think long and hard. I don't want to discourage you too much... But it is a lot of 'work' (& fun)

== Story First ==

What separates a campaign from a single scenario is the ability to tell a story. Consequently, what keeps people coming back for more is a good, interesting story mixed with good, interesting game play. If you have a good idea of where the story of your campaign is going when you start, the little
pieces will fall into place much more easily. After all, it worked for Pixar!

;Scott (author of Liberty, the outlaw campaign) wrote<nowiki>:</nowiki>
: Here is how I wrote Liberty.
:# Write a rough story and plot
:# Decide how many scenarios you want to have
:# Divide the story between the scenarios so you can decide what will happen in each scenario
:#* where are you?
:#* who are you fighting and why?
:#* what do you have to do in this scenario?
:#* where does the hero want to go next?
:# Decide on the "hook" for each scenario. There are a lot of different possible setups for scenarios, and if you want to avoid the boring repetition of "Kill the 2 enemy leaders" you can list interesting combinations of enemies, allies, shroud/fog, day/night effects, recruiting and terrain situations, etc. and pick a good mix to keep the combat interesting and fun.
: All of this has happened without doing any WML, but now you have enough to start coding.

The [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To] has much more to say about this storyboarding phase of the process.

== Share Early ==

Don't be shy to post whatever you've created for others to look at. We all had to learn too, and there are many people on the Scenario and Campaign Development forum (http://www.wesnoth.org/forum/viewforum.php?f=8) who are eager to help people learn.

;Turin (author of Eastern Invasion) wrote<nowiki>:</nowiki>
: I'm working on a loyalist campaign now. I already have the basic plot. I am wondering if anyone wants to playtest my completed levels (i am done with two). Thus i want to know if i should just post the new files as attachments, or what. There are two map files, two scenario files, an image file, a unit file, and you have to change the game file to access the campaign from the 'campaign menu. So tell me how i should make them accessable.

== Steal Often ==

There are too many quotations to pick one for this maxim. The best way to learn how to do something is to copy it from someone else's campaign. It's polite to ask first, and most Campaign designers are happy to see small bits of their WML living in other campaigns.
It's generally poor form to copy whole scenarios, maps, and campaigns, though. And especially poor form to do so without permission.

== Next: ==
* [[BuildingCampaignsTheCampaignFile]]

== See Also ==

* [[Create]]
* [[BuildingScenarios]]
* [[ReferenceWML]]
* [[UserScenarios]]
* [[ExternalUtilities]]
* [http://www.catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How To]

{{Create}}

ScenarioWML

2010-11-11T22:36:22Z

Zookeeper:

{{WML Tags}}
== the toplevel tags [multiplayer], [test], [tutorial], [scenario] ==

The top level tags '''[multiplayer]''', '''[test]''', '''[tutorial]''' and '''[scenario]''' are all formatted the same way.
The difference between these tags is the way that the scenarios they describe are accessed.

The keys '''id''' and '''next_scenario''' affect how scenarios can be accessed.
Whenever a scenario is won, the scenario with id=''next_scenario'' of the same tag type will be played.
Units from the first scenario will be available for recall in the second.

Some scenarios can be played without playing other scenarios first
(in this case there is nothing on the recall list).
These scenarios are called ''initial scenario''s.

A list of initial scenarios, and how to access them:

* All '''[multiplayer]''' scenarios are initial scenarios listed in the multiplayer scenario selector screen (accessed by the "multiplayer" button).

* The '''[test]''' scenario with the attribute '''id=test''' is an initial scenario. This test scenario can be accessed by running the game in test mode. (note: this is NOT the same as debug mode. It can be accessed using -t or --test)

* The '''[tutorial]''' scenario with the attribute '''id=tutorial''' is an initial scenario. The tutorial is accessed by clicking on the "tutorial" button.

* Any '''[scenario]''' scenario with an id listed in the value of ''first_scenario'' in a campaign tag (see [[CampaignWML]]) is an initial scenario accessed by selecting that campaign after clicking on the "campaign" button.

== The [scenario] tag ==

The following keys and tags are recognized in '''[scenario]''' tags:

* '''id''': A unique identifier for this scenario. All scenarios must have an id.

* '''next_scenario''': The id of the scenario to load when the current one is won. This can be changed dynamically, to build non-linear campaigns.

* '''description''': (translatable) only for multiplayer maps. Will show up as a tooltip when mousing over the minimap in the multiplayer setup screen.

* '''name''': (translatable) is shown in several places in the level, including the intro screen. It is also the default name for saves on the level.

* '''map_data''': inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.

* '''turns''': sets an event on turn ''turns'' causing the player to lose. Use ''-1'' to have no turn limit. See also [[EventWML]]

* '''turn_at''': the turn to start on (default=1)

* '''random_start_time''': controls random starting time of day. Possible values are yes and no or list of possible start times; starting from 1 to number of times. for example ''random_start_time=2,3,5,6'' (default=no)

* '''music''': the music file relative to ''./music/'' to play during the scenario

* '''[music]''': specifies the music tracks to play during this scenario, see [[MusicListWML]].

* '''defeat_music''': specifies a comma-separated list of music tracks which may be chosen to play on defeat. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.

* '''victory_music''': specifies a comma-separated list of music tracks which may be chosen to play on victory. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.

* '''theme''': the name of the UI theme that should be used when playing this scenario.

* '''victory_when_enemies_defeated''': when this is set to '''yes''' (default), the player wins once all non-allied units with '''canrecruit=yes''' (aka leaders) are killed. (Currently this only controls the win condition for when all enemies are defeated; it does not prevent the player from losing if he has no leader.) When this value is true the following keys can be used:
** '''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 true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.

* '''disallow_recall''': when this is set to 'no'(default), the player is allowed to recall units from previous scenarios.

* '''experience_modifier''': the percentage that required XP to level up (for all units in the scenario) is multiplied by. Default 100. Note that when used in a campaign, weird things (like units being above the required XP to level up) can happen if this value is different for different scenarios.

* '''[story]''': describes the intro screen. See [[IntroWML]]

* '''[label]''': sets a label
** '''x''', '''y''': location to set label
** '''text''': the label

* '''[time]''', '''[illuminated_time]''': how a day should progress. See [[TimeWML]]

* '''[time_area]''': how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] and [illuminated_time] tags in the [scenario] tag
** takes x and y coordinates.
** '''[time]''', '''[illuminated_time]''': how a day should progress in those locations. See [[TimeWML]]
** time areas can be used in events, assigned identifiers, and removed at discretion. They also accept complete Standard Location Filters. See [[DirectActionsWML]].

* '''[side]''': describes one player. See [[SideWML]]

* '''[event]''': describes an event that may be triggered at a certain point of the scenario. See [[EventWML]]

* '''map_generation''': another way to generate a map. The map will be generated randomly
** '''default''': the default random map generator

* '''[generator]''' if this is present, the map and scenario will be generated randomly. See [[MapGeneratorWML]]

the following key is additionally recognized in '''[multiplayer]''' scenarios:
* '''allow_new_game''': (default=yes) allow/prevent the scenario to be listed in the game creation interface. This is intended for extra scenarios in multiplayer campaigns

== See Also ==

* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]