The Battle for Wesnoth Wiki - User contributions [en]

SideWML

2014-01-15T09:43:45Z

CIB: Refined the description for controller=null

{{WML Tags}}
== the [side] tag ==

The [side] tag is used to describe a side in a particular scenario.

The following keys are recognized:

* '''side''': a number. The leader of this side is placed on the tile represented by this number (see [[BuildingMaps]]). When defining sides, they must be defined in order since the side number is checked against the number of sides seen so far. Currently, the Multiplayer server rejects entering a scenario with more than 9 sides, even if those extra sides are AI sides.

* '''controller''': how moves for this side should be inputted.
** '''ai''': the Wesnoth AI makes this side's moves. This is the default setting.
** '''human''': a player controls this side's moves.
** '''null''': the side doesn't get a turn to move and doesn't have a leader generated from the contents of the [side] tag. (It still can get units from [unit] tags in the [side] tag.) Events that would usually occur on the side's turn will not take place. This includes healing (ability, villages and rest) and ''side turn'' events.
** '''a number''': {{DevFeature1.11}} gives this side's control to a side with '''side''' matching the number (multiplayer only).

* '''no_leader''': if "no" (default), then keys describing a unit which will begin on the side's keep will be the remainder of the '''[side]''' tag, See [[SingleUnitWML]]. Note that if the keys '''x''', '''y''' are included, the leader will begin there regardless of keep location. If this side has a recall list from a previous level, then the recall list will be searched for a leader (using '''canrecruit=yes''') and if one is found it will be used instead of the one described in the '''[side]''' tag. Typical keys used for defining the leader unit are '''type''' (mandatory), '''id''', '''name''' and '''unrenamable=yes''', see [[SingleUnitWML]].

* '''recruit''': a list of unit types. At the beginning of the scenario, the side gains recruitment of these units.

* '''gold''': the starting gold for this side. Default 100. (If gold is carried over from a previous scenario, this value is the minimum starting gold.)

* '''income''': the base income for this side, default 0. This is added to ''base_income'', '''[game_config]''' to determine the side's base income. (see [[GameConfigWML]]).

* '''hidden''': if 'yes', side is not shown in status table.

* '''fog''': if 'yes', this side cannot see any tiles it is not within vision of, except at the start. Please note that the AI currently ignores the fog.

* '''fog_data''': describes the area which this team has de-fogged, using the same format as shroud_data. (This is not particularly useful when defining a side, though, as the game will recalculate fog as turns begin and end. {{DevFeature1.11}}It is used in saved games.)

* '''[fog_override]''' {{DevFeature1.11}} With keys x= and y=, this records the hexes that have been cleared (multiturn) with {{tag|DirectActionsWML|lift_fog}}.

* '''shroud''': if 'yes', this side cannot see any tiles it has not moved within sight of. Please note that the AI currently ignores the shroud. NOTE: with shroud=no, this team *ignores* shroud, so it is not possible to modify it using place_shroud and remove_shroud tags. If you want to do so, use "shroud=yes" and place_shroud/remove_shroud tags.

* '''shroud_data''': describes the area which this team has de-shrouded. An example:
|
|00011111000
:This would leave the first column on the map unaltered and would change the second column for 11 tiles. A '0' means: shrouded, '1' means unshrouded. You can either call an external file using {@filename} (see [[PreprocessorRef]]) or place the data in quotes. For making an external file see [[BuildingScenariosShroudData]].

* '''persistent''': whether the side exists in any other scenarios. If ''yes'', then ''save_id'' (see below) is used to identify the side in other scenarios. Defaults to ''yes'' for sides with a human controller, and ''no'' for ai controlled sides.

* '''save_id''': defaults to the leader's ''id'' if available, 'Unknown' otherwise. The ID of the side with respect to the previous and next scenarios. Used to carry over the side's recall list (including the side's leader), recruitment list, and starting gold from scenario to scenario. Also used for the side's displayed name in the victory gold-calculation dialog. (For versions prior to 1.7.3, some extra effort to retrieve carryover information may be needed. See [[SideSwitchingWML]])

* '''team_name''': a non translatable string representing the team's description. Sides with the same team_name are allied. Default ''side''. ''team_name'' is now a comma-separated list of teams that the side is on.

* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Default ''team_name''.

* '''current_player''': a translatable string representing the player's or leader's name. Defaults to the leader's id; if the side's leader is a human player in multiplayer, the default is the player's username.

* '''color''': May be either a numeric color index or a color name (e.g. 'blue', 'purple', 'orange', etc.). The numeric form is deprecated. The default list of numbers and corresponding colors can be found in data/core/team_colors.cfg.

* '''flag''': a custom flag animation to use instead of the default one to mark captured villages. An automatic side-coloring is applied.
** Example animation that has three frames and loops every 750ms: ''flag=misc/myflag-1.png:250,misc/myflag-2.png:250,misc/myflag-3.png:250''

* '''flag_icon''': a custom flag icon to indicate the side playing in the statusbar (a size of 24x16 is recommended). An automatic side-coloring is applied.

* '''village_gold''': the amount of gold given to this side per village it controls per turn. Default specified in ''village_income'', '''[game_config]''' ([[GameConfigWML]]).

* '''village_support''': {{DevFeature1.11}} the number of unit levels this side is able to support (does not pay upkeep on) per village it controls. Default specified in ''village_support'', '''[game_config]''' ([[GameConfigWML]]).

* '''recall_cost''': the amount of gold it costs to recall a unit. Default specified in ''recall_cost'', '''[game_config]''' ([[GameConfigWML]]).

* '''share_maps''': whether sides allied with this side see all terrains that this side sees, if they are on shroud.

* '''share_view''': whether sides allied with this side see the units that this side sees, if they are on FoW (fog).

* '''scroll_to_leader''': optional. If 'no', scroll to the leader is not performed on the start of each turn. (default: yes)

* '''suppress_end_turn_confirmation''': {{DevFeature1.11}} If "yes", then the player will not be asked to confirm ending their turn even if they have not done anything. This is provided for some (probably few) user-made scenarios in which players often skip their turns. (default: no)

* '''[ai]''' if '''controller=ai''', gives parameters to the AI. See [[AiWML]].

* '''[village]''' describes a village the side begins in control of.
** ''x'', ''y'' the location of the village. If the pair of coordinates is not a village or is duplicated in another [village] tag, behaviour is undefined. Recent game engine or wmllint should warn about these.

* '''[unit]''' describes a unit which begins on the side. See [[SingleUnitWML]]. If the side has a recall list and the unit is not given a location, it will start on the recall list. Note that the ''side'' attribute under '''[unit]''' will be ignored, as the side will come from the ''side'' attribute of '''[side]'''.

The following keys are multiplayer only:

* '''allow_player''': if false then this side will not be allowed to be modified and will be hidden during game creation. Defaults to yes.

* '''disallow_observers''': prevents observers from seeing this side turn. (default: no)

* '''controller_lock''': {{DevFeature1.11}} if true then this side's controller ("Player/Type") modification is limited. It is bound to the '''controller''' attribute in [[SideWML]].

* '''team_lock''': if true then this side's team is not allowed to be modified.

* '''color_lock''': if true then this side's color is not allowed to be modified.

* '''gold_lock''': if true then this side's gold is not allowed to be modified.

* '''income_lock''': if true then this side's income is not allowed to be modified.

* '''faction''': if valid faction id is provided then this side's faction is not allowed to be modified.

* '''faction_from_recruit''': if true then this side will be locked to the faction that matches the recruits better.

{{DevFeature1.11}} N.B. the ''lock'' attributes use [[ScenarioWML]] '''force_lock_settings''' as their default value. I.e. if no value to ''lock'' was set, it will take '''force_lock_settings''' value.

== See Also ==
* [[EraWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

DirectActionsWML

2009-01-04T23:03:04Z

CIB: /* Direct actions */

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

Direct actions are actions that have a direct effect on gameplay.

The following tags are actions:
* '''[endlevel]''': ends the scenario.
** '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless ''result=defeat'', the following keys can also 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.
** '''carryover_report''' {{DevFeature}}: whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
** '''save''' {{DevFeature}}: whether a start-of-scenario save should be created for the next scenario, the default is save=yes.
** '''linger_mode''' {{DevFeature}}: whether the game should switch to linger_mode before advancing to the next scenario, the default is linger_mode=yes.
** '''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''.
** When the result is "victory" the following keys can be used:
*** '''carryover_percentage''' {{DevFeature}}: by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
*** '''carryover_add''' {{DevFeature}}: 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''' {{DevFeature}}: (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_text''' {{DevFeature}}: 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''' {{DevFeature}}: 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]].
* '''[unit]''': places a unit on the map. For syntax see [[SingleUnitWML]].
** {{Short Note:Predefined Macro|GENERIC_UNIT}}
** {{DevFeature}} '''to_variable''': spawn directly into a variable instead of on the map.
* '''[recall]''': recalls a unit. The unit is recalled free of charge, and is placed near the leader.
** [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored.
** '''x,y''': the unit is placed here instead of next to the leader.
** '''show''': if not "no", display the unit being recalled.
* '''[teleport]''': teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be teleported.
** '''x,y''': the position to teleport to.
** '''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)
* '''[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.
** '''x,y''': the position (or range of positions) to change.
** {{DevFeature}} '''layer''': (overlay|base|both, default=both) only change the specified layer.
** {{DevFeature}} '''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.
* '''[gold]''': give one side gold.
** '''amount''': the amount of gold to give.
** '''side''': (default=1) the number of the side to give the gold to.
* '''[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 '''[store_unit]''', '''[while]''' and [clear_variable] in [[InternalActionsWML]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
** '''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.
** '''text''': (translatable) floating text to display above the unit, such as a damage amount
** '''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''': if the XP has been modified then there will be tried to advance the unit, default true.
** {{DevFeature}} '''x''' ,'''y''': override unit location
* '''[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.
* '''[disallow_recruit]''': prevents a side from recruiting units it could previously recruit.
** '''type''': the types of units that the side can no longer recruit.
** '''side''': (default=1) the number of the side that may no longer recruit the 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.
* '''[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.
** '''income''': the income given at the begining of each turn.
** '''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.
** {{DevFeature}} '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''[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).
** {{DevFeature}} '''current''': changes the current turn number after applying turn limit modifications, if any. It is possible to change the current turn number to a greater one than the current only; also, it is not possible to change the turn number to exceed the turn limit.
* '''[capture_village]''': changes the ownership of a village.
** '''side''': the side that takes control of the village. If not given, the village will become neutral.
** '''x, y''': the location of the village.
* '''[kill]''': Removes all units (including units in a recall list) that match the filter from the game.
** [[StandardUnitFilter]]: selection criterion
** '''animate''': if 'yes', displays the unit dying (fading away).
** '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event. {{DevFeature}} 'last breath' events are also fired.
* '''[unstone]''': Unstones all units that match the filter.
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be unstoned. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unstoned.
* '''[object]''': gives some unit an object and removes all items on the tile the unit is on.
** '''id''': 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 level. In a campaign objects with the same id can be assigned once per level.
** '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
** '''duration''': if 'level', 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).
** '''[filter]''': [[StandardUnitFilter]] the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
** '''[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 '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
** '''silent''': whether or not messages should be suppressed. Default is "no".
** '''image''': the displayed image of the object.
** '''name''': (translatable) displayed as a caption of the image.

** '''user_description''': {{DevFeature}} (translatable) displayed as a message of the image. In 1.4 and older versions this is just '''description'''; that will still be expected for compatibility.
** '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
** If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
** The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.
* '''[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.
** [[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.
** [[StandardLocationFilter]]: the range of tiles on which shroud should be placed.
* '''[allow_undo]''': allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.
* '''[heal_unit]''' {{DevFeature}}: 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).
** '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed.
** '''[secondary_unit_filter]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true).
** '''amount''': the maximum points the unit will be healed.
** '''animate''': a boolean which indicate if the healing animations must be played.
* '''[time_area]''' {{DevFeature}}: changes the schedule in the given locations.
** [[StandardLocationFilter]]: the locations to affect.
** [[TimeWML]]: the new schedule.
* '''[end_turn]''' {{DevFeature}}: end the current side's turn.

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

Fosdem2009

2008-12-28T19:32:05Z

CIB:

== General information ==
This page is meant to somehow coordinate the small Wesconf taking place at FOSDEM 2009. That is everyone attending should please list him/herself in the list of arrivals and stuff like this. FOSDEM 2009 will take place at the first weekend in Febuary 2009, on Saturday 7th and Sunday 8th.

* Fosdem - http://fosdem.org/2009/
* [http://www.wesnoth.org/forum/viewtopic.php?p=283311#283311 List with phone numbers] (forum moderators only)

== Schedule/Plans ==
{| border="1" width="100%"
|-
! (nick)name(s)
! Arrival
! Departure
! Accomodation
|-
| Ivanovic & Dragonking
| 6, late afternoon
| 8, evening
| Bruegel YH (not sure yet)
|-
| Mordante
| 6, afternoon (not sure yet)
| 8, evening
| Bruegel YH (not sure yet)
|-
| Boucman
| unknown
| unknown
| unknown
|-
| cib
| probably evening
| not sure yet
| not sure yet
|-
|}

For accomodations please keep in mind that parking in the center of Brussels is really problematic. It might make sense to drive to the University where FOSDEM takes place, park there and take the bus into the town center (where some of the hotels/hostels are).

On the official FOSDEM page [http://fosdem.org/2009/practical/accomodation some possible hotels/hostels] are listed.

== Maps ==
* [http://tinyurl.com/3a65gr Bruegel YH]
* [http://tinyurl.com/35br9c Brussels Central (Train Station) → Bruegel YH]
* [http://tinyurl.com/37d9v4 Bruegel YH → Brussels Central (Train Station) → Novotel Grand Place]
* [http://tinyurl.com/2mzns6 Novotel Grand Place]
* [http://tinyurl.com/3dggg3 CrownePlaza (Europa)]
* [http://tinyurl.com/36epxj FOSDEM]
* [http://tinyurl.com/2w4bms Novotel Grand Place -> FOSDEM]

== Transportation ==
Information about how to reach the FOSDEM is listed at the [http://fosdem.org/2009/practical/transportation official transportation subpage].

Short version of how to get there for those that reside in Bruegel YH and Novotel Grand Place:

* Enter Bus 71 (Debrouckere - Central Station ("Gare Centrale") - Delta) somewhere at 'Central Station'
* Leave the bus at "ULB" (crossroads Ave. Adolphe Buyl - Sq. Deveze)
* Walk down Ave. Paul Heger on your right hand.

== Wesnoth Hacking Room ==

Wesnoth will not have a room of its own. Instead we will use one of the "general hacking rooms". So far it is not sure which room it will be, if we do it like last year, it will be room number 115 in the building AW1. Last year this was the smaller of the two hacking rooms and we had no real problem with conquering (and holding) the first row in this room. There were not too many power outlets, so this year at least Ivanovic will bring one multi-outlet power strip plus some extension cable (5m or so). There is no wired network, everything wireless (and sometimes rather unstable!). Beside this you should bring laptops since there are no desktop machines available for hacking.

Short version:
AW1 - Room 115

== FOSDEM 2008 ==
We were already at FOSDEM 2008, here something as reference:

* [http://www.wesnoth.org/forum/viewtopic.php?p=283649#p283649 Forum topic (with group photo)]
* [http://www.wesnoth.org/wiki/Fosdem2008 2008 wiki page]
* [https://mail.gna.org/public/wesnoth-dev/2008-02/msg00078.html Summary of FOSDEM 2008 results]

[[Category:Development]]
[[Category:Wesconf]]

DirectActionsWML

2008-12-23T03:02:43Z

CIB: /* Direct actions */ added the new endlevel attributes

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

Direct actions are actions that have a direct effect on gameplay.

The following tags are actions:
* '''[endlevel]''': ends the scenario.
** '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless ''result=defeat'', the following keys can also 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.
** '''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.
** '''linger_mode''': whether the game should switch to linger_mode before advancing to the next scenario, the default is linger_mode=yes.
** '''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''.
** When the result is "victory" the following keys can be used:
*** '''carryover_percentage''' {{DevFeature}}: by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
*** '''carryover_add''' {{DevFeature}}: 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''' {{DevFeature}}: (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_text''' {{DevFeature}}: 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''' {{DevFeature}}: 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]].
* '''[unit]''': places a unit on the map. For syntax see [[SingleUnitWML]].{{Short Note:Predefined Macro|GENERIC_UNIT}}
* '''[recall]''': recalls a unit. The unit is recalled free of charge, and is placed near the leader.
** [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored.
** '''x,y''': the unit is placed here instead of next to the leader.
** '''show''': if not "no", display the unit being recalled.
* '''[teleport]''': teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be teleported.
** '''x,y''': the position to teleport to.
* '''[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.
** '''x,y''': the position (or range of positions) to change.
** {{DevFeature}} '''layer''': (overlay|base|both, default=both) only change the specified layer.
** {{DevFeature}} '''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.
* '''[gold]''': give one side gold.
** '''amount''': the amount of gold to give.
** '''side''': (default=1) the number of the side to give the gold to.
* '''[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 '''[store_unit]''', '''[while]''' and [clear_variable] in [[InternalActionsWML]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
** '''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.
** '''text''': (translatable) floating text to display above the unit, such as a damage amount
** '''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''': if the XP has been modified then there will be tried to advance the unit, default true.
* '''[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.
* '''[disallow_recruit]''': prevents a side from recruiting units it could previously recruit.
** '''type''': the types of units that the side can no longer recruit.
** '''side''': (default=1) the number of the side that may no longer recruit the 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.
* '''[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.
** '''income''': the income given at the begining of each turn.
** '''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.
** {{DevFeature}} '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''[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).
** {{DevFeature}} '''current''': changes the current turn number after applying turn limit modifications, if any. It is possible to change the current turn number to a greater one than the current only; also, it is not possible to change the turn number to exceed the turn limit.
* '''[capture_village]''': changes the ownership of a village.
** '''side''': the side that takes control of the village. If not given, the village will become neutral.
** '''x, y''': the location of the village.
* '''[kill]''': Removes all units (including units in a recall list) that match the filter from the game.
** [[StandardUnitFilter]]: selection criterion
** '''animate''': if 'yes', displays the unit dying (fading away).
** '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event. {{DevFeature}} 'last breath' events are also fired.
* '''[unstone]''': Unstones all units that match the filter.
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be unstoned. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unstoned.
* '''[object]''': gives some unit an object and removes all items on the tile the unit is on.
** '''id''': 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 level. In a campaign objects with the same id can be assigned once per level.
** '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
** '''duration''': if 'level', 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).
** '''[filter]''': [[StandardUnitFilter]] the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
** '''[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 '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
** '''silent''': whether or not messages should be suppressed. Default is "no".
** '''image''': the displayed image of the object.
** '''name''': (translatable) displayed as a caption of the image.

** '''user_description''': {{DevFeature}} (translatable) displayed as a message of the image. In 1.4 and older versions this is just '''description'''; that will still be expected for compatibility.
** '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
** If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
** The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.
* '''[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.
** [[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.
** [[StandardLocationFilter]]: the range of tiles on which shroud should be placed.
* '''[allow_undo]''': allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move 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 move the first time.
* '''[heal_unit]''' {{DevFeature}}: 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).
** '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed.
** '''[secondary_unit_filter]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true).
** '''amount''': the maximum points the unit will be healed.
** '''animate''': a boolean which indicate if the healing animations must be played.
* '''[time_area]''' {{DevFeature}}: changes the schedule in the given locations.
** [[StandardLocationFilter]]: the locations to affect.
** [[TimeWML]]: the new schedule.
* '''[end_turn]''' {{DevFeature}}: end the current side's turn.

== 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].
* {{LinkMacro|MOVE_UNIT}}: Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* {{LinkMacro|FULL_HEAL}}: Brings a unit to full HP
* {{LinkMacro|LOYAL_UNIT}}: Create a loyal unit
* {{LinkMacro|MODIFY_TERRAIN_MASK}}: Modify an area of terrain

== See Also ==

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

[[Category: WML Reference]]

InternalActionsWML

2008-12-21T11:48:01Z

CIB: /* [event] */

{{WML Tags}}
== Internal actions ==

Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable.

The internal actions '''[if]''', '''[while]''', and '''[event]''' describe when/whether sets of actions should be executed.

== [if] ==

Executes different sets of actions based on whether the conditions described in the condition tags are true or not.

Condition tags:
* '''[have_unit]''': a unit passing this filter with >0 HP exists
** [[StandardUnitFilter]] (almost... '''Note:''' does not check for matching units in the recall list)
** '''count''' {{DevFeature}}: if used, the given number of units must match the filter. Accepts a number, range, or comma separated range; default "1-99999"

* '''[have_location]''': a location passing this filter exists
** [[StandardLocationFilter]]
** '''count''' {{DevFeature}}: if used, the given number of location must match the filter. Accepts a number, range, or comma separated range; default "1-99999"

* '''[and]''': If an [and] is present, all must evaluate to true in order for the [if] to evaluate true. Useful as a bracket for complex conditions, but not strictly necessary.
** condition tags as in [if]: if these evaluate to true, [and] evaluates to true.

* '''[or]''': If an [or] is present, one must evaluate to true in order for the [if] to evaluate true. ([[AdvancedConditionalWML|Example]])
** condition tags as in [if]: if these evaluate to true, '''[or]''' evaluates to true.

* '''[not]''': If a [not] is present, none must evaluate to true in order for the [if] to evaluate true.
** condition tags as in [if]: if these evaluate to true, [not] evaluates to false.

* '''[and],[or],[not]''': all top-level filters will support in-order conditional handling of and, or, and not. One important thing to remember is, if you have multiple [or]s, you should not wrap your first conditional statement into an [or] block.

* '''[variable]''': tests something about the value of a WML variable (see [[VariablesWML]])
** '''name''': the name of the variable to test the value of Only one of the following keys should be used for comparing the value of the variable to another value:
** '''equals''': $name is equal (string wise) to this
** '''not_equals''': $name is not equal to this
** '''greater_than''': $name is numerically greater than this
** '''less_than''': $name is less than this
** '''greater_than_equal_to''': $name is not less than this
** '''less_than_equal_to''': $name is not greater than this
** '''numerical_not_equals''': $name is greater than or less than this
** '''numerical_equals''': $name is not greater than or less than this
** '''boolean_equals''': $name has the same boolean value (e.g. off, false, 0, no)
** '''contains''': $name contains this string
** {{DevFeature}} '''boolean_not_equals''': $name has not the same boolean value. Strictly a syntactic shortcut for the following syntax that served its absence in 1.4:
[not]
[variable]
name=...
boolean_equals=...
[/variable]
[/not]

After condition tags:
* '''[then]''': contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true
* '''[else]''': contains a set of action tags which should be executed if any condition is false, and all [or] tags are false

== [switch] {{DevFeature}} ==

Executes different sets of action based on the value of a variable.
[switch]
variable=foo
[case]
value="A"
... WML if foo=A ...
[/case]
[case]
value="B"
... WML if foo=B ...
[/case]
[else]
... WML if not foo=A nor foo=B ...
[/else]
[/switch]

* '''variable''': name of the variable to check.
* '''[case]''': Case block. Contains:
** '''value''': value to test the variable against.
** the action WML to execute if the variable matches the value (rest of the block).
* '''[else]''': Block of action WML to execute if no '''[case]''' block matches.

== [while] ==

Executes commands if all conditions are true.
Continues to execute them until a condition is not true.

Executes a maximum of 1024 iterations per invocation.
Condition tags are the same as for [if]

After condition tags:
* '''[do]''': contains actions that should be executed repeatedly until some condition is false.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.
The macros 'FOREACH' and 'NEXT' ([[UtilWML]]) can be used to iterate over an array;
i.e. run a set of actions once per element of the array.

=== {FOREACH} ===
If you wish to use a "for-each" iteration format (useful for example when you want to do an iteration for each row in a table) you can use the {{LinkMacro|FOREACH}} and {{LinkMacro|NEXT}} predefined macros.

=== {REPEAT} ===
You can use the {{LinkMacro|REPEAT}} macro to perform a quick iteration for a number of times you specify.

== [event] ==

This adds a new event to the scenario.
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).
This is useful if you want an event that can only be triggered when a prior event is fulfilled

These tags describe actions that affect the values of WML variables
(see [[VariablesWML]] for information on WML variables,
and [[UtilWML]] for convenient macro shortcuts for some of these):
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}}
** '''name''': the name of the variable to manipulate
** '''value''': set the variable to the given value (can be numeric or string). This only interprets dollars signs if it is the very first character, and then the entire value must be a simple variable name. (in 1.3.2, has the same effect as format. Use literal for no substitution)
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.
** '''format''': set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see [[VariablesWML]])
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.
** '''add''': add the given amount to the variable. To subtract, add a negative number.
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer.
** '''divide''': divide the variable by the given number. The result is an integer.
** '''modulo''': returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1.
** '''random''': the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'random=3..5'. You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''
** '''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.
** {{DevFeature}} '''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).
** {{DevFeature}} '''[join]''' joins an array of strings to 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

* {{DevFeature}} '''[set_variables]''': manipulates a WML array
** '''name''': the name of the 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'''
***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 unless the variable already contains data at that index. 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, example:
[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}
=>bar; more
** '''[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: wether to ignore empty elements

* {{DevFeature}} '''[fire_event]''': trigger a WML event
** '''name''': the name of event to trigger
** '''[primary_unit]''': primary unit for the event (usually the attacker) (optional)
** '''[secondary_unit]''': secondary unit for the event (usually the defender) (optional)
** both tags have some keys which are optional :
*** '''x,y''': location of this unit
** '''[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.

* '''[store_unit]''': stores details about units into game variables. 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 [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 [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.
** '''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 only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.
** '''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.
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''
:* description
:* experience
:* facing
:* gender
:* canrecruit
:* overlays
:* goto_x
:* goto_y
:* hitpoints
:* moves
:* resting
:* side
:* type
:* unrenamable
:* upkeep
:* user_description
:* x
:* y
:* [variables]
:* [status]
:* [modifications]
Variables, status, and modifications are children of the stored unit variable. Example:
[set_variable]
name=unit_store.status.poisoned
value=yes
[/set_variable]

:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. 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.
:* advances_to
:* alignment
:* alpha
:* attacks_left
:* canrecruit
:* controller
:* cost
:* description
:* experience
:* facing
:* flying
:* fog
:* gender
:* get_hit_sound
:* gold
:* goto_x
:* goto_y
:* hitpoints
:* id
:* image
:* image_defensive
:* income
:* language_name (same as the name key in the unit config)
:* level
:* max_attacks
:* max_experience
:* max_hitpoints
:* max_moves
:* movement
:* movement_type
:* moves
:* race
:* resting
:* shroud
:* side
:* type
:* unit_description
:* unrenamable
:* usage
:* value
:* x
:* y
:* zoc
:* [advancement]
:* [/advancement]
:* [movement_costs]
:* [/movement_costs]
:* [defense]
:* [/defense]
:* [resistance]
:* [/resistance]
:* [variables]
:* [/variables]
:* [status]
:* [/status]
:* [attack]
:* [/attack]
:* [modifications_description]
:* [/modifications_description]
:* [modifications]
:* [/modifications]

* '''[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' (the terrain type for a starting location is always 'K' unless it has been changed) and {{DevFeature}} 'owner_side' (villages only)
** '''side''': the side whose starting location is to be stored
** '''variable''': (default='location'): the name of the variable to store the location 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 {{DevFeature}} 'owner_side' (villages only).
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.
* '''[store_villages]''': Stores a series of locations of villages 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 {{DevFeature}} 'owner_side'.
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.
* '''[store_gold]''': Stores a side's gold into a variable.
** '''side''': (default=1) the side for which the gold should be stored
** '''variable''': (default='gold') the name of the variable to store the gold in
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)
** '''side''': the side whose information should be stored
** '''variable''': the name of the variable to store the information in
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario. Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.
** '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.
* '''[role]''': tries to find a unit to assign a role to. 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]]). However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] 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.
* {{DevFeature}} '''[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''.
* {{DevFeature}} '''[insert_tag]''': inserts a variable as WML
**'''name''': the ["name"] to be given to the tag
**'''variable''': name of the variable to be inserted
* {{DevFeature}} '''[store_time_of_day]''': stores time of day information from the current scenario into a WML variable container.
** '''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.

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

[[Category: WML Reference]]

InternalActionsWML

2008-03-16T11:01:27Z

CIB: /* [event] */

{{WML Tags}}
== Internal actions ==

Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable.

The internal actions '''[if]''', '''[while]''', and '''[event]''' describe when/whether sets of actions should be executed.

== [if] ==

Executes different sets of actions based on whether the conditions described in the condition tags are true or not.

Condition tags:
* '''[have_unit]''': a unit passing this filter with >0 HP exists
** [[StandardUnitFilter]] (almost... '''Note:''' does not check for matching units in the recall list)

* '''[have_location]''': a location passing this filter exists
** [[StandardLocationFilter]]

* '''[and]''': If an [and] is present, all must evaluate to true in order for the [if] to evaluate true. Useful as a bracket for complex conditions, but not strictly necessary.
** condition tags as in [if]: if these evaluate to true, [and] evaluates to true.

* '''[or]''': If an [or] is present, one must evaluate to true in order for the [if] to evaluate true. ([[AdvancedConditionalWML|Example]])
** condition tags as in [if]: if these evaluate to true, '''[or]''' evaluates to true.

* '''[not]''': If a [not] is present, none must evaluate to true in order for the [if] to evaluate true.
** condition tags as in [if]: if these evaluate to true, [not] evaluates to false.

* '''[and],[or],[not]''': all top-level filters will support in-order conditional handling of and, or, and not. One important thing to remember is, if you have multiple [or]s, you should not wrap your first conditional statement into an [or] block.

* '''[variable]''': tests something about the value of a WML variable (see [[VariablesWML]])
** '''name''': the name of the variable to test the value of Only one of the following keys should be used for comparing the value of the variable to another value:
** '''equals''': $name is equal (string wise) to this
** '''not_equals''': $name is not equal to this
** '''greater_than''': $name is numerically greater than this
** '''less_than''': $name is less than this
** '''greater_than_equal_to''': $name is not less than this
** '''less_than_equal_to''': $name is not greater than this
** '''numerical_not_equals''': $name is greater than or less than this
** '''numerical_equals''': $name is not greater than or less than this
** '''boolean_equals''': $name has the same boolean value (e.g. off, false, 0, no)
** '''contains''': $name contains this string
** {{DevFeature}} '''boolean_not_equals''': $name has not the same boolean value. Strictly a syntactic shortcut for the following syntax that served its absence in 1.4:
[not]
[variable]
name=...
boolean_equals=...
[/variable]
[/not]

After condition tags:
* '''[then]''': contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true
* '''[else]''': contains a set of action tags which should be executed if any condition is false, and all [or] tags are false

== [switch] {{DevFeature}} ==

Executes different sets of action based on the value of a variable.
[switch]
variable=foo
[case]
value="A"
... WML if foo=A ...
[/case]
[case]
value="B"
... WML if foo=B ...
[/case]
[else]
... WML if not foo=A nor foo=B ...
[/else]
[/switch]

* '''variable''': name of the variable to check.
* '''[case]''': Case block. Contains:
** '''value''': value to test the variable against.
** the action WML to execute if the variable matches the value (rest of the block).
* '''[else]''': Block of action WML to execute if no '''[case]''' block matches.

== [while] ==

Executes commands if all conditions are true.
Continues to execute them until a condition is not true.

Executes a maximum of 1024 iterations per invocation.
Condition tags are the same as for [if]

After condition tags:
* '''[do]''': contains actions that should be executed repeatedly until some condition is false.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.
The macros 'FOREACH' and 'NEXT' ([[UtilWML]]) can be used to iterate over an array;
i.e. run a set of actions once per element of the array.

=== {FOREACH} ===
If you wish to use a "for-each" iteration format (useful for example when you want to do an iteration for each row in a table) you can use the [http://www.wesnoth.org/misc/macro-reference.xhtml FOREACH] and [http://www.wesnoth.org/misc/macro-reference.xhtml NEXT] prededined macros.

=== {REPEAT} ===
You can use the REPEAT macro to perform a quick iteration for a number of times you specify.

== [event] ==

This adds a new event to the scenario.
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).
This is useful if you want an event that can only be triggered when a prior event is fulfilled

These tags describe actions that affect the values of WML variables
(see [[VariablesWML]] for information on WML variables,
and [[UtilWML]] for convenient macro shortcuts for some of these):
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}}
** '''name''': the name of the variable to manipulate
** '''value''': set the variable to the given value (can be numeric or string). This only interprets dollars signs if it is the very first character, and then the entire value must be a simple variable name. (in 1.3.2, has the same effect as format. Use literal for no substitution)
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.
** '''format''': set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see [[VariablesWML]])
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.
** '''add''': add the given amount to the variable. To subtract, add a negative number.
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer.
** '''divide''': divide the variable by the given number. The result is an integer.
** '''modulo''': returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1.
** '''random''': the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'random=3..5'. You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''
** '''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.
** {{DevFeature}} '''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).
** {{DevFeature}} '''[join]''' joins an array of strings to a textual list
***variable: name of the array
***key: array[$i].key to look for the strings
***separator: separator to connect the elements
***remove_empty: wether to ignore empty elements

* {{DevFeature}} '''[set_variables]''': manipulates a WML array
** '''name''': the name of the 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'''
** '''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, example:
[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}
=>bar; more
** '''[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: array[$i].key to put the elements in
***separator: separator to separate the elements
***remove_empty: wether to ignore empty elements

* '''[store_unit]''': stores details about units into game variables. 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 [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 [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.
** '''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 only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.
** '''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.
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''
:* description
:* experience
:* facing
:* gender
:* canrecruit
:* overlays
:* goto_x
:* goto_y
:* hitpoints
:* moves
:* resting
:* side
:* type
:* unrenamable
:* upkeep
:* user_description
:* x
:* y
:* [variables]
:* [status]
:* [modifications]
Variables, status, and modifications are children of the stored unit variable. Example:
[set_variable]
name=unit_store.status.poisoned
value=yes
[/set_variable]

:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. 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.
:* advanceto
:* alignment
:* alpha
:* attacks_left
:* canrecruit
:* controller
:* cost
:* description
:* experience
:* facing
:* flying
:* fog
:* gender
:* get_hit_sound
:* gold
:* goto_x
:* goto_y
:* hitpoints
:* id
:* image
:* image_defensive
:* income
:* language_name (same as the name key in the unit config)
:* level
:* max_attacks
:* max_experience
:* max_hitpoints
:* max_moves
:* movement
:* movement_type
:* moves
:* race
:* resting
:* shroud
:* side
:* team_name
:* type
:* unit_description
:* unrenamable
:* usage
:* value
:* x
:* y
:* zoc
:* [advancement]
:* [/advancement]
:* [movement_costs]
:* [/movement_costs]
:* [defense]
:* [/defense]
:* [resistance]
:* [/resistance]
:* [variables]
:* [/variables]
:* [status]
:* [/status]
:* [attack]
:* [/attack]
:* [modifications_description]
:* [/modifications_description]
:* [modifications]
:* [/modifications]

* '''[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', and 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed)
** '''side''': the side whose starting location is to be stored
** '''variable''': (default='location'): the name of the variable to store the location 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).
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.
* '''[store_villages]''': Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type).
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.
** '''side''': (default=1) the side for which the gold should be stored
** '''variable''': (default='gold') the name of the variable to store the gold in
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)
** '''side''': the side whose information should be stored
** '''variable''': the name of the variable to store the information in
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario. Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.
** '''name''': the name of the variable to clear.
* '''[role]''': tries to find a unit to assign a role to. 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]]). However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] 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.
* {{DevFeature}} '''[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''.

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

[[Category: WML Reference]]

InternalActionsWML

2008-03-16T10:55:38Z

CIB: /* [event] */

{{WML Tags}}
== Internal actions ==

Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable.

The internal actions '''[if]''', '''[while]''', and '''[event]''' describe when/whether sets of actions should be executed.

== [if] ==

Executes different sets of actions based on whether the conditions described in the condition tags are true or not.

Condition tags:
* '''[have_unit]''': a unit passing this filter with >0 HP exists
** [[StandardUnitFilter]] (almost... '''Note:''' does not check for matching units in the recall list)

* '''[have_location]''': a location passing this filter exists
** [[StandardLocationFilter]]

* '''[and]''': If an [and] is present, all must evaluate to true in order for the [if] to evaluate true. Useful as a bracket for complex conditions, but not strictly necessary.
** condition tags as in [if]: if these evaluate to true, [and] evaluates to true.

* '''[or]''': If an [or] is present, one must evaluate to true in order for the [if] to evaluate true. ([[AdvancedConditionalWML|Example]])
** condition tags as in [if]: if these evaluate to true, '''[or]''' evaluates to true.

* '''[not]''': If a [not] is present, none must evaluate to true in order for the [if] to evaluate true.
** condition tags as in [if]: if these evaluate to true, [not] evaluates to false.

* '''[and],[or],[not]''': all top-level filters will support in-order conditional handling of and, or, and not. One important thing to remember is, if you have multiple [or]s, you should not wrap your first conditional statement into an [or] block.

* '''[variable]''': tests something about the value of a WML variable (see [[VariablesWML]])
** '''name''': the name of the variable to test the value of Only one of the following keys should be used for comparing the value of the variable to another value:
** '''equals''': $name is equal (string wise) to this
** '''not_equals''': $name is not equal to this
** '''greater_than''': $name is numerically greater than this
** '''less_than''': $name is less than this
** '''greater_than_equal_to''': $name is not less than this
** '''less_than_equal_to''': $name is not greater than this
** '''numerical_not_equals''': $name is greater than or less than this
** '''numerical_equals''': $name is not greater than or less than this
** '''boolean_equals''': $name has the same boolean value (e.g. off, false, 0, no)
** '''contains''': $name contains this string
** {{DevFeature}} '''boolean_not_equals''': $name has not the same boolean value. Strictly a syntactic shortcut for the following syntax that served its absence in 1.4:
[not]
[variable]
name=...
boolean_equals=...
[/variable]
[/not]

After condition tags:
* '''[then]''': contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true
* '''[else]''': contains a set of action tags which should be executed if any condition is false, and all [or] tags are false

== [switch] {{DevFeature}} ==

Executes different sets of action based ont the value of a variable.
[switch]
variable=foo
[case]
value="A"
... WML if foo=A ...
[/case]
[case]
value="B"
... WML if foo=B ...
[/case]
[else]
... WML if not foo=A nor foo=B ...
[/else]
[/switch]

* '''variable''': variable to check.
* '''[case]''': Case block. Contains:
** '''value''': the value to test the variable against.
** the action WML to execute if the variable matches the value (rest of the block).
* '''[else]''': Block of action WML to execute if no '''[case]''' block matches.

== [while] ==

Executes commands if all conditions are true.
Continues to execute them until a condition is not true.

Executes a maximum of 1024 iterations per invocation.
Condition tags are the same as for [if]

After condition tags:
* '''[do]''': contains actions that should be executed repeatedly until some condition is false.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.
The macros 'FOREACH' and 'NEXT' ([[UtilWML]]) can be used to iterate over an array;
i.e. run a set of actions once per element of the array.

=== {FOREACH} ===
If you wish to use a "for-each" iteration format (useful for example when you want to do an iteration for each row in a table) you can use the [http://www.wesnoth.org/misc/macro-reference.xhtml FOREACH] and [http://www.wesnoth.org/misc/macro-reference.xhtml NEXT] prededined macros.

=== {REPEAT} ===
You can use the REPEAT macro to perform a quick iteration for a number of times you specify.

== [event] ==

This adds a new event to the scenario.
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).
This is useful if you want an event that can only be triggered when a prior event is fulfilled

These tags describe actions that affect the values of WML variables
(see [[VariablesWML]] for information on WML variables,
and [[UtilWML]] for convenient macro shortcuts for some of these):
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}}
** '''name''': the name of the variable to manipulate
** '''value''': set the variable to the given value (can be numeric or string). This only interprets dollars signs if it is the very first character, and then the entire value must be a simple variable name. (in 1.3.2, has the same effect as format. Use literal for no substitution)
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.
** '''format''': set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see [[VariablesWML]])
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.
** '''add''': add the given amount to the variable. To subtract, add a negative number.
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer.
** '''divide''': divide the variable by the given number. The result is an integer.
** '''modulo''': returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1.
** '''random''': the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'random=3..5'. You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''
** '''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.
** {{DevFeature}} '''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).
** {{DevFeature}} '''[join]''' joins an array of strings to a textual list
***variable: name of the array
***key: array[$i].key to look for the strings
***separator: separator to connect the elements
***remove_empty: wether to ignore empty elements

* {{DevFeature}} '''[set_variables]''': manipulates a WML array
** '''name''': the name of the 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'''
** '''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
** '''[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: array[$i].key to put the elements in
***separator: separator to separate the elements
***remove_empty: wether to ignore empty elements

* '''[store_unit]''': stores details about units into game variables. 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 [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 [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.
** '''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 only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.
** '''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.
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''
:* description
:* experience
:* facing
:* gender
:* canrecruit
:* overlays
:* goto_x
:* goto_y
:* hitpoints
:* moves
:* resting
:* side
:* type
:* unrenamable
:* upkeep
:* user_description
:* x
:* y
:* [variables]
:* [status]
:* [modifications]
Variables, status, and modifications are children of the stored unit variable. Example:
[set_variable]
name=unit_store.status.poisoned
value=yes
[/set_variable]

:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. 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.
:* advanceto
:* alignment
:* alpha
:* attacks_left
:* canrecruit
:* controller
:* cost
:* description
:* experience
:* facing
:* flying
:* fog
:* gender
:* get_hit_sound
:* gold
:* goto_x
:* goto_y
:* hitpoints
:* id
:* image
:* image_defensive
:* income
:* language_name (same as the name key in the unit config)
:* level
:* max_attacks
:* max_experience
:* max_hitpoints
:* max_moves
:* movement
:* movement_type
:* moves
:* race
:* resting
:* shroud
:* side
:* team_name
:* type
:* unit_description
:* unrenamable
:* usage
:* value
:* x
:* y
:* zoc
:* [advancement]
:* [/advancement]
:* [movement_costs]
:* [/movement_costs]
:* [defense]
:* [/defense]
:* [resistance]
:* [/resistance]
:* [variables]
:* [/variables]
:* [status]
:* [/status]
:* [attack]
:* [/attack]
:* [modifications_description]
:* [/modifications_description]
:* [modifications]
:* [/modifications]

* '''[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', and 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed)
** '''side''': the side whose starting location is to be stored
** '''variable''': (default='location'): the name of the variable to store the location 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).
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.
* '''[store_villages]''': Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type).
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.
** '''side''': (default=1) the side for which the gold should be stored
** '''variable''': (default='gold') the name of the variable to store the gold in
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)
** '''side''': the side whose information should be stored
** '''variable''': the name of the variable to store the information in
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario. Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.
** '''name''': the name of the variable to clear.
* '''[role]''': tries to find a unit to assign a role to. 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]]). However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] 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.
* {{DevFeature}} '''[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''.

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

[[Category: WML Reference]]

Template:WML Tags

2008-03-16T10:49:23Z

CIB:

{| class="gallery" style="width:175px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 7pt;margin-left;10px;"
|-
|
[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit ]
'''WML Tags'''

|-
|''A:''
[[AbilitiesWML|abilities]],
[[CampaignWML#The_.5Babout.5D_tag|about]],
[[UnitWML|advancefrom]],
[[UnitWML|advancement]],
[[StatisticalScenarioWML|advances]],
[[AiWML|ai]],
[[DirectActionsWML|allow_recruit]],
[[DirectActionsWML|allow_undo]],
[[AnimationWML|animation]],
[[VariablesWML|array]],
[[UnitWML|attack]],
[[AnimationWML|attack_filter]],
[[StatisticalScenarioWML|attacks]],
[[AiWML|avoid]];
|-
|''B:''
[[UnitWML|base_unit]],[[CampaignWML#The_.5Bbinary_path.5D_tag|binary_path]],[[HelpWML|bold]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]], [[DirectActionsWML|capture_village]], [[ReplayWML|choose]],
[[InternalActionsWML|clear_variable]],
[[InterfaceActionsWML|colour_adjust]],
[[ReplayWML|command]];
|-
|''D:''
[[AbilitiesWML|damage]],[[StatisticalScenarioWML|deaths]],[[InterfaceActionsWML|debug_message]],[[UnitWML|defend]],[[StatisticalScenarioWML|defends]],
[[UnitWML|defense]],
[[InterfaceActionsWML|delay]],
[[ReplayWML|destination]],
[[DirectActionsWML|disallow_recruit]],
[[InternalActionsWML|do]];
|-
|''E:''
[[EffectWML|effect]],[[InternalActionsWML|else]],[[ReplayWML|end_turn]],
[[DirectActionsWML|endlevel]],
[[EraWML|era]],
[[EventWML|event]],
[[ThemeWML|expenses]];
|-
|''F:''
[[FilterWML|filter]], [[FilterWML|filter_location]], [[FilterWML|filter_second]], [[FilterWML|filter_vision]], [[HelpWML|format]], [[AnimationWML|frame]];
|-
|''G:''
[[GameConfigWML|game_config]], [[ScenarioWML|generator]], [[DirectActionsWML|gold]], [[ThemeWML|gold]];
|-
|''H:''
[[InternalActionsWML|have_unit]], [[HelpWML|header]], [[InterfaceActionsWML|hide_unit]];
|-
|''I:''
[[InternalActionsWML|if]], [[TimeWML|illuminated_time]], [[TerrainGraphicsWML|image]],
[[HelpWML|img]], [[ThemeWML|income]], [[HelpWML|italic]], [[InterfaceActionsWML|item]];
|-
|''J:''
[[HelpWML|jump]], [[InternalActionsWML|join]];
|-
|''K:''
[[DirectActionsWML|kill]], [[StatisticalScenarioWML|killed]];
|-
|''L:''
[[LabelWML|label]] ([[InterfaceActionsWML|map]], [[ThemeWML|theme]]), [[LanguageWML|language]], [[AiWML|leader_goal]];
|-
|''M:''
[[ThemeWML|main_map]],[[ThemeWML|menu]], [[InterfaceActionsWML|message]], [[ThemeWML|mini_map]],
[[AnimationWML|missile_frame]], [[SingleUnitWML|modifications]], [[DirectActionsWML|modify_side]],
[[DirectActionsWML|modify_turns]], [[ReplayWML|move]], [[InterfaceActionsWML|move_unit_fake]], [[UnitWML|movement costs]],
[[UnitsWML|movetype]], [[ScenarioWML|multiplayer]], [[EraWML|multiplayer_side]], [[InterfaceActionsWML|music]];
|-
|''N:''
[[AnimationWML|neighbour_unit_filter]], [[FilterWML|not]], [[ThemeWML|num_units]];
|-
|''O:''
[[DirectActionsWML|object]], [[InterfaceActionsWML|objectives]], [[InterfaceActionsWML|objective]],
[[ThemeWML|observers]], [[InterfaceActionsWML|option]], [[InternalActionsWML|or]];
|-
|''P:''
[[ThemeWML|panel]], [[IntroWML|part]], [[DirectActionsWML|place_shroud]], [[ThemeWML|position]],
[[InterfaceActionsWML|print]], [[AiWML|protect_location]], [[AiWML|protect_unit]];
|-
|''R:''
[[UnitsWML|race]], [[ReplayWML|random]], [[ReplayWML|recall]], [[StatisticalScenarioWML|recalls]],
[[ReplayWML|recruit]], [[StatisticalScenarioWML|recruits]], [[InterfaceActionsWML|redraw]],
[[HelpWML|ref]], [[DirectActionsWML|remove_shroud]], [[InterfaceActionsWML|remove_unit_overlay]],
[[InterfaceActionsWML|removeitem]], [[InterfaceActionsWML|remove_sound_source]], [[SavefileWML|replay]], [[SavefileWML|replay_start]],
[[UnitWML|resistance]], [[ThemeWML|resolution]], [[ReplayWML|results]], [[InternalActionsWML|role]];
|-
|''S:''
[[SavefileWML|save]], [[ScenarioWML|scenario]],
[[InterfaceActionsWML|scroll]], [[InterfaceActionsWML|scroll_to]],
[[InterfaceActionsWML|scroll_to_unit]], [[AnimationWML|secondary_attack_filter]], [[AnimationWML|secondary_unit_filter]], [[HelpWML|section]],
[[InterfaceActionsWML#.5Bset_menu_item.5D_.28SVN_trunk_only.29|set_menu_item]], [[DirectActionsWML|set_recruit]],
[[InternalActionsWML|set_variable]], [[InternalActionsWML|set_variables]],
[[SideWML|side]], [[ThemeWML|side_playing]], [[SavefileWML|snapshot]],
[[InterfaceActionsWML|sound]], [[InterfaceActionsWML|sound_source]], [[ReplayWML|source]], [[EventWML|special_filter]], [[EventWML|special_filter_second]],
[[InternalActionsWML|split]],
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
[[ThemeWML|status]], [[DirectActionsWML|stone]], [[InternalActionsWML|store_gold]], [[InternalActionsWML|store_locations]],
[[InternalActionsWML|store_map_dimensions]],
[[InternalActionsWML|store_starting_location]], [[InternalActionsWML|store_side]], [[InternalActionsWML|store_unit]], [[IntroWML|story]];
|-
|''T:''
[[AiWML|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
[[DirectActionsWML|teleport]], [[UnitWML|teleport_anim]],
[[TerrainWML|terrain]], [[DirectActionsWML|terrain]], [[TerrainGraphicsWML|terrain_graphics]], [[TerrainMaskWML|terrain_mask]], [[ScenarioWML#Test_scenario|test]],
[[CampaignWML#The_.5Btextdomain.5D_tag|textdomain]], [[ThemeWML|theme]], [[InternalActionsWML|then]],
[[TerrainGraphicsWML|tile]], [[TimeWML|time]], [[ScenarioWML|time_area]], [[ThemeWML|time_of_day]],
[[HelpWML|topic]], [[HelpWML|toplevel]], [[SingleUnitWML|trait]], [[ThemeWML|turn]], [[ScenarioWML|tutorial]];
|-
|''U:''
[[InterfaceActionsWML|unhide_unit]], unit ([[UnitWML|define]], [[SingleUnitWML|create]]),
[[ThemeWML|unit_abilities]], [[ThemeWML|unit_alignment]], [[ThemeWML|unit_description]], [[AnimationWML|unit_filter]], [[ThemeWML|unit_hp]], [[ThemeWML|unit_image]], [[ThemeWML|unit_level]], [[ThemeWML|unit_moves]],
[[InterfaceActionsWML|unit_overlay]], [[ThemeWML|unit_profile]], [[ThemeWML|unit_status]],
[[ThemeWML|unit_traits]], [[ThemeWML|unit_type]], [[ThemeWML|unit_weapons]], [[ThemeWML|unit_xp]],
[[UnitsWML|units]], [[DirectActionsWML|unstone]], [[DirectActionsWML|unstore_unit]], [[ThemeWML|upkeep]];
|-
| ''V:''
[[InternalActionsWML|variable]], [[VariablesWML|variables]], [[SideWML|village]], [[ThemeWML|villages]];
|-
| ''W:''
[[InternalActionsWML|while]], [[FilterWML|wml_filter]]
|}

InternalActionsWML

2008-03-16T10:45:17Z

CIB: /* [event] */ add [set_variables]

{{WML Tags}}
== Internal actions ==

Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable.

The internal actions '''[if]''', '''[while]''', and '''[event]''' describe when/whether sets of actions should be executed.

== [if] ==

Executes different sets of actions based on whether the conditions described in the condition tags are true or not.

Condition tags:
* '''[have_unit]''': a unit passing this filter with >0 HP exists
** [[StandardUnitFilter]] (almost... '''Note:''' does not check for matching units in the recall list)

* '''[have_location]''': a location passing this filter exists
** [[StandardLocationFilter]]

* '''[and]''': If an [and] is present, all must evaluate to true in order for the [if] to evaluate true. Useful as a bracket for complex conditions, but not strictly necessary.
** condition tags as in [if]: if these evaluate to true, [and] evaluates to true.

* '''[or]''': If an [or] is present, one must evaluate to true in order for the [if] to evaluate true. ([[AdvancedConditionalWML|Example]])
** condition tags as in [if]: if these evaluate to true, '''[or]''' evaluates to true.

* '''[not]''': If a [not] is present, none must evaluate to true in order for the [if] to evaluate true.
** condition tags as in [if]: if these evaluate to true, [not] evaluates to false.

* '''[and],[or],[not]''': all top-level filters will support in-order conditional handling of and, or, and not. One important thing to remember is, if you have multiple [or]s, you should not wrap your first conditional statement into an [or] block.

* '''[variable]''': tests something about the value of a WML variable (see [[VariablesWML]])
** '''name''': the name of the variable to test the value of Only one of the following keys should be used for comparing the value of the variable to another value:
** '''equals''': $name is equal (string wise) to this
** '''not_equals''': $name is not equal to this
** '''greater_than''': $name is numerically greater than this
** '''less_than''': $name is less than this
** '''greater_than_equal_to''': $name is not less than this
** '''less_than_equal_to''': $name is not greater than this
** '''numerical_not_equals''': $name is greater than or less than this
** '''numerical_equals''': $name is not greater than or less than this
** '''boolean_equals''': $name has the same boolean value (e.g. off, false, 0, no)
** '''contains''': $name contains this string
** {{DevFeature}} '''boolean_not_equals''': $name has not the same boolean value. Strictly a syntactic shortcut for the following syntax that served its absence in 1.4:
[not]
[variable]
name=...
boolean_equals=...
[/variable]
[/not]

After condition tags:
* '''[then]''': contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true
* '''[else]''': contains a set of action tags which should be executed if any condition is false, and all [or] tags are false

== [switch] {{DevFeature}} ==

Executes different sets of action based ont the value of a variable.
[switch]
variable=foo
[case]
value="A"
... WML if foo=A ...
[/case]
[case]
value="B"
... WML if foo=B ...
[/case]
[else]
... WML if not foo=A nor foo=B ...
[/else]
[/switch]

* '''variable''': variable to check.
* '''[case]''': Case block. Contains:
** '''value''': the value to test the variable against.
** the action WML to execute if the variable matches the value (rest of the block).
* '''[else]''': Block of action WML to execute if no '''[case]''' block matches.

== [while] ==

Executes commands if all conditions are true.
Continues to execute them until a condition is not true.

Executes a maximum of 1024 iterations per invocation.
Condition tags are the same as for [if]

After condition tags:
* '''[do]''': contains actions that should be executed repeatedly until some condition is false.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.
The macros 'FOREACH' and 'NEXT' ([[UtilWML]]) can be used to iterate over an array;
i.e. run a set of actions once per element of the array.

=== {FOREACH} ===
If you wish to use a "for-each" iteration format (useful for example when you want to do an iteration for each row in a table) you can use the [http://www.wesnoth.org/misc/macro-reference.xhtml FOREACH] and [http://www.wesnoth.org/misc/macro-reference.xhtml NEXT] prededined macros.

=== {REPEAT} ===
You can use the REPEAT macro to perform a quick iteration for a number of times you specify.

== [event] ==

This adds a new event to the scenario.
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).
This is useful if you want an event that can only be triggered when a prior event is fulfilled

These tags describe actions that affect the values of WML variables
(see [[VariablesWML]] for information on WML variables,
and [[UtilWML]] for convenient macro shortcuts for some of these):
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}}
** '''name''': the name of the variable to manipulate
** '''value''': set the variable to the given value (can be numeric or string). This only interprets dollars signs if it is the very first character, and then the entire value must be a simple variable name. (in 1.3.2, has the same effect as format. Use literal for no substitution)
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.
** '''format''': set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see [[VariablesWML]])
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.
** '''add''': add the given amount to the variable. To subtract, add a negative number.
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer.
** '''divide''': divide the variable by the given number. The result is an integer.
** '''modulo''': returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1.
** '''random''': the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'random=3..5'. You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''
** '''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.
** {{DevFeature}} '''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).
** {{DevFeature}} '''[join]''' joins an array of strings to a textual list
***variable: name of the array
***key: array[$i].key to look for the strings
***separator: separator to connect the elements
***remove_empty: wether to ignore empty elements

* {{DevFeature}} '''[set_variables]''': manipulates a WML array
** '''name''': the name of the 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'''
** '''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
** '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used at once
**'''[split]''' splits a textual list into an array which will then be set to data
***list: textual list to split
***key: array[$i].key to put the elements in
***separator: separator to separate the elements
***remove_empty: wether to ignore empty elements

* '''[store_unit]''': stores details about units into game variables. 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 [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 [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.
** '''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 only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.
** '''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.
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''
:* description
:* experience
:* facing
:* gender
:* canrecruit
:* overlays
:* goto_x
:* goto_y
:* hitpoints
:* moves
:* resting
:* side
:* type
:* unrenamable
:* upkeep
:* user_description
:* x
:* y
:* [variables]
:* [status]
:* [modifications]
Variables, status, and modifications are children of the stored unit variable. Example:
[set_variable]
name=unit_store.status.poisoned
value=yes
[/set_variable]

:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. 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.
:* advanceto
:* alignment
:* alpha
:* attacks_left
:* canrecruit
:* controller
:* cost
:* description
:* experience
:* facing
:* flying
:* fog
:* gender
:* get_hit_sound
:* gold
:* goto_x
:* goto_y
:* hitpoints
:* id
:* image
:* image_defensive
:* income
:* language_name (same as the name key in the unit config)
:* level
:* max_attacks
:* max_experience
:* max_hitpoints
:* max_moves
:* movement
:* movement_type
:* moves
:* race
:* resting
:* shroud
:* side
:* team_name
:* type
:* unit_description
:* unrenamable
:* usage
:* value
:* x
:* y
:* zoc
:* [advancement]
:* [/advancement]
:* [movement_costs]
:* [/movement_costs]
:* [defense]
:* [/defense]
:* [resistance]
:* [/resistance]
:* [variables]
:* [/variables]
:* [status]
:* [/status]
:* [attack]
:* [/attack]
:* [modifications_description]
:* [/modifications_description]
:* [modifications]
:* [/modifications]

* '''[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', and 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed)
** '''side''': the side whose starting location is to be stored
** '''variable''': (default='location'): the name of the variable to store the location 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).
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.
* '''[store_villages]''': Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type).
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.
** '''side''': (default=1) the side for which the gold should be stored
** '''variable''': (default='gold') the name of the variable to store the gold in
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)
** '''side''': the side whose information should be stored
** '''variable''': the name of the variable to store the information in
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario. Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.
** '''name''': the name of the variable to clear.
* '''[role]''': tries to find a unit to assign a role to. 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]]). However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] 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.
* {{DevFeature}} '''[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''.

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

[[Category: WML Reference]]

InternalActionsWML

2008-03-16T10:18:08Z

CIB: /* [event] */ add [set_variable][join]

{{WML Tags}}
== Internal actions ==

Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable.

The internal actions '''[if]''', '''[while]''', and '''[event]''' describe when/whether sets of actions should be executed.

== [if] ==

Executes different sets of actions based on whether the conditions described in the condition tags are true or not.

Condition tags:
* '''[have_unit]''': a unit passing this filter with >0 HP exists
** [[StandardUnitFilter]] (almost... '''Note:''' does not check for matching units in the recall list)

* '''[have_location]''': a location passing this filter exists
** [[StandardLocationFilter]]

* '''[and]''': If an [and] is present, all must evaluate to true in order for the [if] to evaluate true. Useful as a bracket for complex conditions, but not strictly necessary.
** condition tags as in [if]: if these evaluate to true, [and] evaluates to true.

* '''[or]''': If an [or] is present, one must evaluate to true in order for the [if] to evaluate true. ([[AdvancedConditionalWML|Example]])
** condition tags as in [if]: if these evaluate to true, '''[or]''' evaluates to true.

* '''[not]''': If a [not] is present, none must evaluate to true in order for the [if] to evaluate true.
** condition tags as in [if]: if these evaluate to true, [not] evaluates to false.

* '''[and],[or],[not]''': all top-level filters will support in-order conditional handling of and, or, and not. One important thing to remember is, if you have multiple [or]s, you should not wrap your first conditional statement into an [or] block.

* '''[variable]''': tests something about the value of a WML variable (see [[VariablesWML]])
** '''name''': the name of the variable to test the value of Only one of the following keys should be used for comparing the value of the variable to another value:
** '''equals''': $name is equal (string wise) to this
** '''not_equals''': $name is not equal to this
** '''greater_than''': $name is numerically greater than this
** '''less_than''': $name is less than this
** '''greater_than_equal_to''': $name is not less than this
** '''less_than_equal_to''': $name is not greater than this
** '''numerical_not_equals''': $name is greater than or less than this
** '''numerical_equals''': $name is not greater than or less than this
** '''boolean_equals''': $name has the same boolean value (e.g. off, false, 0, no)
** '''contains''': $name contains this string
** {{DevFeature}} '''boolean_not_equals''': $name has not the same boolean value. Strictly a syntactic shortcut for the following syntax that served its absence in 1.4:
[not]
[variable]
name=...
boolean_equals=...
[/variable]
[/not]

After condition tags:
* '''[then]''': contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true
* '''[else]''': contains a set of action tags which should be executed if any condition is false, and all [or] tags are false

== [switch] {{DevFeature}} ==

Executes different sets of action based ont the value of a variable.
[switch]
variable=foo
[case]
value="A"
... WML if foo=A ...
[/case]
[case]
value="B"
... WML if foo=B ...
[/case]
[else]
... WML if not foo=A nor foo=B ...
[/else]
[/switch]

* '''variable''': variable to check.
* '''[case]''': Case block. Contains:
** '''value''': the value to test the variable against.
** the action WML to execute if the variable matches the value (rest of the block).
* '''[else]''': Block of action WML to execute if no '''[case]''' block matches.

== [while] ==

Executes commands if all conditions are true.
Continues to execute them until a condition is not true.

Executes a maximum of 1024 iterations per invocation.
Condition tags are the same as for [if]

After condition tags:
* '''[do]''': contains actions that should be executed repeatedly until some condition is false.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.
The macros 'FOREACH' and 'NEXT' ([[UtilWML]]) can be used to iterate over an array;
i.e. run a set of actions once per element of the array.

=== {FOREACH} ===
If you wish to use a "for-each" iteration format (useful for example when you want to do an iteration for each row in a table) you can use the [http://www.wesnoth.org/misc/macro-reference.xhtml FOREACH] and [http://www.wesnoth.org/misc/macro-reference.xhtml NEXT] prededined macros.

=== {REPEAT} ===
You can use the REPEAT macro to perform a quick iteration for a number of times you specify.

== [event] ==

This adds a new event to the scenario.
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).
This is useful if you want an event that can only be triggered when a prior event is fulfilled

These tags describe actions that affect the values of WML variables
(see [[VariablesWML]] for information on WML variables,
and [[UtilWML]] for convenient macro shortcuts for some of these):
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}}
** '''name''': the name of the variable to manipulate
** '''value''': set the variable to the given value (can be numeric or string). This only interprets dollars signs if it is the very first character, and then the entire value must be a simple variable name. (in 1.3.2, has the same effect as format. Use literal for no substitution)
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.
** '''format''': set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see [[VariablesWML]])
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.
** '''add''': add the given amount to the variable. To subtract, add a negative number.
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer.
** '''divide''': divide the variable by the given number. The result is an integer.
** '''modulo''': returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1.
** '''random''': the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'random=3..5'. You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''
** '''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.
** {{DevFeature}} '''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).
** {{DevFeature}} '''[join]''' joins an array of strings to a textual list
***variable: name of the array
***key: array[$i].key to look for the strings
***separator: separator to connect the elements
***remove_empty: wether to ignore empty elements

* '''[store_unit]''': stores details about units into game variables. 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 [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 [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.
** '''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 only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.
** '''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.
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''
:* description
:* experience
:* facing
:* gender
:* canrecruit
:* overlays
:* goto_x
:* goto_y
:* hitpoints
:* moves
:* resting
:* side
:* type
:* unrenamable
:* upkeep
:* user_description
:* x
:* y
:* [variables]
:* [status]
:* [modifications]
Variables, status, and modifications are children of the stored unit variable. Example:
[set_variable]
name=unit_store.status.poisoned
value=yes
[/set_variable]

:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. 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.
:* advanceto
:* alignment
:* alpha
:* attacks_left
:* canrecruit
:* controller
:* cost
:* description
:* experience
:* facing
:* flying
:* fog
:* gender
:* get_hit_sound
:* gold
:* goto_x
:* goto_y
:* hitpoints
:* id
:* image
:* image_defensive
:* income
:* language_name (same as the name key in the unit config)
:* level
:* max_attacks
:* max_experience
:* max_hitpoints
:* max_moves
:* movement
:* movement_type
:* moves
:* race
:* resting
:* shroud
:* side
:* team_name
:* type
:* unit_description
:* unrenamable
:* usage
:* value
:* x
:* y
:* zoc
:* [advancement]
:* [/advancement]
:* [movement_costs]
:* [/movement_costs]
:* [defense]
:* [/defense]
:* [resistance]
:* [/resistance]
:* [variables]
:* [/variables]
:* [status]
:* [/status]
:* [attack]
:* [/attack]
:* [modifications_description]
:* [/modifications_description]
:* [modifications]
:* [/modifications]

* '''[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', and 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed)
** '''side''': the side whose starting location is to be stored
** '''variable''': (default='location'): the name of the variable to store the location 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).
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.
* '''[store_villages]''': Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type).
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages.
** '''variable''': the name of the variable (array) into which to store the locations
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.
** '''side''': (default=1) the side for which the gold should be stored
** '''variable''': (default='gold') the name of the variable to store the gold in
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)
** '''side''': the side whose information should be stored
** '''variable''': the name of the variable to store the information in
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario. Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.
** '''name''': the name of the variable to clear.
* '''[role]''': tries to find a unit to assign a role to. 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]]). However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] 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.
* {{DevFeature}} '''[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''.

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

[[Category: WML Reference]]

InterfaceActionsWML

2008-01-12T13:24:05Z

CIB: added text_input

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

== [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]:
* standard unit filter - the unit whose profile and name are displayed. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). '''[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
** '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 ''' " ''')
* ''side_for'' (default: all sides) comma seperated list of sides for who message is shown. {{DevFeature}}
* ''image'' (default: profile image of speaker) the image to display next to the message.
* ''caption'' (default: name of speaker) the caption to display under the image. Name to be displayed.
* ''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. {{DevFeature}}
* ''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]''' zero or more '''[option]''' elements may be present. 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]]) {{DevFeature}}
** '''[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_chars'' the maximum number of characters that may be typed into the field
** ''text'' text that is written into the field in the beginning
* note that '''[option]''' and '''[text_input]''' can only be used in moveto events in MP, otherwise they cause OOS

Text formatting options for '''[message]'''. These can also be used in unit names (user_description), objectives, and such.
* An asterisk (*) 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.
* 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.
* ''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'')

== [set_menu_item] {{DevFeature}} ==
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.

* ''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.
** ''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.
* '''[removeitem]''' removes any graphical items on a given hex
** ''x'', ''y'' the hex to remove items off
* '''[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-seperated list of x locations to move along
** ''y'' a comma-seperated list of y locations to move along (x and y values are matched pairs)
** ''side'' the side of the fake unit, used for team colouring the fake unit
* '''[hide_unit]''' makes the given unit become invisible. Useful in conjunction with '''[move_unit_fake]''' to move a leader unit into position on-screen. Only one unit may be hidden at a time.
** ''x'', ''y'' location of the unit to be hidden. (NOT a standard unit filter! Just x and y.)
* '''[unhide_unit]''' stops the currently hidden unit from being hidden.
* '''[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
** standard unit filter
** ''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.
* '''[sound]''' Plays a sound
** ''name'' the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
** ''repeat'' {{DevFeature}} repeats the sound for a specified additional number of times (default=0)
* '''[sound_source]''' {{DevFeature}} 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/shrouded
** ''x,y'' a standard location filter for the locations associated with the sound source
* '''[remove_sound_source]''' {{DevFeature}} 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
* '''[colour_adjust]''' tints the colour of the screen.
** ''red'', ''green'', ''blue'' values from -255 to 255, the amount to tint by for each colour
* '''[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
* '''[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
* '''[animate_unit]''' uses the custom animation of a unit to animate it on screen (if the unit has the corresponding animation)
** ''flag'' the key to find the good custom animation in the unit description see the '''[extra_anim]''' description in [[AnimationWML]]
** '''[filter]''' a standard unit filter see [[FilterWML]] by default, the unit at the event location will be animated. You can use this tag to choose what unit to animate
* '''[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.
* '''[deprecated_message]''' {{DevFeature}} 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.
* '''[debug_message]''' {{DevFeature}} 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.
** ''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.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EffectWML

2007-12-30T17:25:17Z

CIB: added 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.

The following keys are always recognized for [effect]:
* ''unit_type'' only apply this effect if the affected unit's type name matches ''unit_type'' (can be a list of types).
* ''times'' {{DevFeature}} 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 [[AttackWML]].
* ''remove_attacks'' {{DevFeature}} remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. Notes: do not use a [filter] tag. Also, the last remaining attack will never be removed (since Wesnoth don't support it).
* "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). ({{DevFeature}} this doesn't change the weapon's description like in 1.2)
** ''set_description'' {{DevFeature}} change the attack's description (ie displayed name).
** ''set_type'' change the attack type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'holy'.
** ''set_special'' change the attack's specials. See [[AbilitiesWML]] for a list of possible values. Note that you can only set the normal specials defined in ''data/abilities.cfg'', not custom ones.
** ''[set_specials]'' {{DevFeature}} 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'' {{DevFeature}} 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 [[AttackWML]] for explainations about attack_weight.
** ''defense_weight'' change the attack's defense_weight. See [[AttackWML]] for explainations 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).
** [set_specials]
** [movement_costs] a subtag that describes the new movement costs just like in [[UnitWML]] 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 [[UnitWML]] 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 [[UnitWML]] for describing a unit type
* "variation" switches the unit into one of its variations.
** ''name'' the name of the variation 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'' {{DevFeature}} toggle the zone of control.
** ''value'' new value for zoc (0=disable, other=enable).
* ''profile'' {{DevFeature}} 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" {{DevFeature}} Adds one or more abilities to a unit.
** [abilities] A subtag that contains the ability definitions.
* "remove_ability" {{DevFeature}} 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'' {{DevFeature}} contain animations that will be added to the unit
* "image_mod" modify the image path function([[ImagePathFunctionWML]]) of all the unit's frames
** ''replace'' the image path function to be used, e.g. "RC(magenta>red)"

== See Also ==

* [[UnitWML]]
* [[AttackWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

TranslationsWML

2007-09-10T19:30:03Z

CIB: documentation for textdomain syntax and tags

This page describes tags and syntax used for enabling translation in your user made campaign.

== _ "<translatable string>" ==
Any string that you want to be translated has to be put inside _ " ".
Example:
[message]
speaker=narrator
message= _ "This string is going to be translated."
[/message]

== #textdomain <textdomain> ==
This comment tells Wesnoth to use a certain textdomain. Affects the tag that it has been placed in and all children until another #textdomain is found. A textdomain is a set of translations(you can create your own one for your campaign).
Example:
#textdomain wesnoth-trow
[event]
#textdomain wesnoth-httt
[message]
message= _ "heir to the throne message" #this will be translated using the HttT textdomain
[/message]
[message]
message= _ "heir to the throne message two" #same as above
[/message]

#textdomain wesnoth-utbs
[message]
message= _ "under the burning suns message" #UtbS textdomain
[/message]
[/event]

[event]
[message]
message= _ "the rise of wesnoth message" #TroW textdomain
[/message]
[/event]

Note: The [scenario] tag isn't a child of [campaign], so you will have to specify a textdomain for both, your campaign and each of your scenarios.

== the [textdomain] tag ==

This tag, which has to be placed at the same level as [campaign], is used to specify a path for your own textdomain.

Example:
[textdomain]
name="wesnoth-Liberty"
path="data/campaigns/Liberty/translations"
[/textdomain]

TerrainCodesWML

2007-08-31T13:22:51Z

CIB: /* Terrain strings '''''(SVN terrain only)''''' */ - updated terrain table, added ^ to terrain strings description

{{WML Tags}}
== Values of terrain letters ==

What each letter represents in Wesnoth maps,
and the possible values of the ''letter'' key.

See [[TerrainWML]] for information on how to define a terrain.

* '''A''' human (snow) hill village
* '''a''' human hill village
* '''B''' desert village (adobe)
* '''b''' human mountain village
* '''C''' castle
* '''c''' shallow water, "coast"
* '''D''' underground village (cave, village), "dungeon village"
* '''d''' sand, (old desert)
* '''E''' desert road
* '''e''' elven (snow) village
* '''F''' forest (snow)
* '''f''' forest
* '''G''' savanna (grass)
* '''g''' grass
* '''H''' hills (snow)
* '''h''' hills
* '''I''' desert
* '''i''' ice (tundra)
* '''J''' desert hills
* '''j''' -nothing- (will be snowy mountains)
* '''K''' keep (castle)
* '''k''' river ford (grass, shallow water)
* '''L''' tropical forest village (savanna, village)
* '''l''' lava (canyon)
* '''M''' desert mountains
* '''m''' mountain
* '''N''' ruined castle
* '''n''' encampment (castle)
* '''O''' -nothing- (will probably be an Orc Castle one day)
* '''o''' dwarven castle (castle)
* '''P''' desert oasis
* '''p''' dwarven village
* '''Q''' sunken ruin
* '''q''' ruin (swamp)
* '''R''' road (grass)
* '''r''' dirt (grass)
* '''S''' tundra
* '''s''' deep water
* '''T''' forest (tropical)
* '''t''' village
* '''U''' desert village (tent)
* '''u''' cave
* '''V''' snow village (tundra, village)
* '''v''' human village (village)
* '''W''' cavewall
* '''w''' swamp
* '''X''' canyon (replaced by chasm in trunk)
* '''x''' reserved for UMCs
* '''Y''' swamp village (swamp, village)
* '''y''' reserved for UMCs
* '''Z''' mermen village (shallow water)
* '''z''' reserved for UMCs
* '''/''','''|''','''\''' bridge (grass, shallow water)
* '''~''' fog
* ' ' void/shroud (it uses the "space" character)
* '''*''' reserved for UMCs
* '''^''' reserved for UMCs
* '''%''' reserved for UMCs
* '''@''' reserved for UMCs
* '''[''' rockbound cave
* ''']''' mushroom grove
* ''' ' ''' illuminated cave
* ''' ? ''' great Elven tree
* ''' & ''' impassable mountains
* ''' " ''' ???
* ''' $ ''' ???
* ''' . ''' ???
* ''' ; ''' ???
* ''' : ''' ???
* ''' < ''' ???
* ''' > ''' ???
* ''' _ ''' ???
* ''' ` ''' ???

==Reserved letters and non-letter Characters==
Reserved letters are for custom terrains in user-made campaigns. In addition to these it is currently also possible to use other characters not on the above list to represent custom terrain, such as ½ § @ % etc., but new "official" terrain may be assigned for these characters in the future. So when creating custom terrain, the letters marked as reserved on the above list should be used first.
Use campaign definitions (see [[CampaignWML]]) to prevent your custom terrains from interfering with other campaigns.

== Terrain strings '''''[[User:SkeletonCrew#Branch_terrain|(SVN terrain only)]]''''' ==
The terrains will be changed from a single letter to a multi letter system. There will be a compability layer for a short while. This layer doesn't work for campaigns with custom terrains, these campaigns have to be changed to use the new system.

The following rules are stated for the new terrain letters, note most of these rules are not validated since it would slow down Wesnoth; not following these rules might break Wesnoth.
* terrain strings are between 2 and 4 characters
* terrain strings start with a capital letter and the following letters are lower case
* terrain strings can only contain letters, the symbols /|\ which are meant for directional items like bridges and the symbol ^
* the underscore is used for internal terrains
* the star '*' can be used for wildcards in some parts
* the symbol ^ usually points out that a terrain is created with layers, for example Gs^Fp means Forest(Fp) overlayer on Savanna(Gs).

Starting positions are defined by a number followed by 1 space and then the terrain string; this means that a starting position is no longer automatically a keep.

The letters Y,y,Z,z are reserved for UMC so any string containing any of these letters is a custom terrain. Other undefined terrain strings are reserved for future expansion within Wesnoth.

=== Conversion form old to new ===
Map conversion logic is included in the [[Maintenance_tools|upconvert]] tool (in newer versions, [[Maintenance_tools|wmllint]]). This script will, among other things, convert a map with the old letters to the new strings. Here is a lookup table with the letters.

char= a b c d e f g h i j k l m
str= Vhh Vhm Ww Ds Vea Ff Gg Hh Ai Wwf Ql Mm

char= n o p q r s t u v w x y z
str= Ce Cud Vud Chs Re Wo Veg Uu Vhg Ss

char= A B C D E F G H I J K L M
str= Vhha Vda Ch Vu Rd Fa Gs Ha Dd Hd _K Vht Md

char= N O P Q R S T U V W X Y Z
str= Chr Do Chw Rr Aa Ft Vdt Vha Xu Qxu Vs Vwm

char= / | \ & _ ~ ? ] [ '
str= Bww/ Bww| Bww\ Xm _s _f Fet Uf Uh Uui

=== Terrain Table ===
This is a list of the terrains, the strings used for them in the new map format, the letters used for them in the old map format, their id and the terrains they take their stats from. Generated from terrain.cfg using terrain2wiki.

<table border="1"><tr>
<th>String</th>
<th>Old letter</th>
<th>Name</th>
<th>Stats from</th>
</tr>
<tr>
<td>_off^_usr</td>
<td></td>
<td>None</td>
<td></td>
</tr>
<tr>
<td>_s</td>
<td></td>
<td>Shroud</td>
<td></td>
</tr>
<tr>
<td>_f</td>
<td>~</td>
<td>Fog</td>
<td></td>
</tr>
<tr>
<td>Ai</td>
<td>i</td>
<td>Ice</td>
<td>Snow</td>
</tr>
<tr>
<td>Aa</td>
<td>S</td>
<td>Snow</td>
<td></td>
</tr>
<tr>
<td>Ww^Bw|</td>
<td>|</td>
<td>Bridge</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>Ww^Bw/</td>
<td>/</td>
<td>Bridge</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>Ww^Bw\</td>
<td>\</td>
<td>Bridge</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>Wo^Bw|</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Deep Water</td>
</tr>
<tr>
<td>Wo^Bw/</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Deep Water</td>
</tr>
<tr>
<td>Wo^Bw\</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Deep Water</td>
</tr>
<tr>
<td>Ss^Bw|</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Swamp</td>
</tr>
<tr>
<td>Ss^Bw/</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Swamp</td>
</tr>
<tr>
<td>Ss^Bw\</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Swamp</td>
</tr>
<tr>
<td>Ce</td>
<td>n</td>
<td>Encampment</td>
<td>Castle</td>
</tr>
<tr>
<td>Ch</td>
<td>y</td>
<td>Castle</td>
<td></td>
</tr>
<tr>
<td>Cv</td>
<td>y</td>
<td>Elven Castle</td>
<td>Castle</td>
</tr>
<tr>
<td>Cud</td>
<td>o</td>
<td>Dwarven Castle</td>
<td>Castle</td>
</tr>
<tr>
<td>Chr</td>
<td>N</td>
<td>Ruin</td>
<td>Castle</td>
</tr>
<tr>
<td>Chw</td>
<td>Q</td>
<td>Sunken Ruin</td>
<td>Castle,Shallow Water</td>
</tr>
<tr>
<td>Chs</td>
<td>q</td>
<td>Swamp Ruin</td>
<td>Castle,Swamp</td>
</tr>
<tr>
<td>Ke</td>
<td></td>
<td>Encampment keep</td>
<td>Castle</td>
</tr>
<tr>
<td>Kh</td>
<td></td>
<td>Keep</td>
<td>Castle</td>
</tr>
<tr>
<td>Kv</td>
<td></td>
<td>Elven Keep</td>
<td>Castle</td>
</tr>
<tr>
<td>Kud</td>
<td></td>
<td>Dwarven keep</td>
<td>Castle</td>
</tr>
<tr>
<td>Khr</td>
<td></td>
<td>Ruined keep</td>
<td>Castle</td>
</tr>
<tr>
<td>Khw</td>
<td></td>
<td>Sunken keep</td>
<td>Castle,Shallow Water</td>
</tr>
<tr>
<td>Khs</td>
<td></td>
<td>Swamp keep</td>
<td>Castle,Swamp</td>
</tr>
<tr>
<td>Dd^Dc</td>
<td></td>
<td>Crater</td>
<td>Sand</td>
</tr>
<tr>
<td>Dd</td>
<td>I</td>
<td>Desert</td>
<td>Sand</td>
</tr>
<tr>
<td>Dd^Dr</td>
<td></td>
<td>Rubble</td>
<td>Hills</td>
</tr>
<tr>
<td>Ds</td>
<td>d</td>
<td>Sand</td>
<td></td>
</tr>
<tr>
<td>Dd^Do</td>
<td>P</td>
<td>Oasis</td>
<td>Sand</td>
</tr>
<tr>
<td>Aa^Fpa</td>
<td>F</td>
<td>Snow Forest</td>
<td>Snow,Forest</td>
</tr>
<tr>
<td>Gg^Fet</td>
<td>?</td>
<td>Great Tree</td>
<td>Forest</td>
</tr>
<tr>
<td>Gs^Fp</td>
<td>f</td>
<td>Forest</td>
<td></td>
</tr>
<tr>
<td>Gs^Ft</td>
<td>T</td>
<td>Tropical Forest</td>
<td>Forest</td>
</tr>
<tr>
<td>Gg</td>
<td>g</td>
<td>Grassland</td>
<td></td>
</tr>
<tr>
<td>Ggf</td>
<td></td>
<td>Grassland</td>
<td>Grassland</td>
</tr>
<tr>
<td>Gs</td>
<td>G</td>
<td>Savanna</td>
<td>Grassland</td>
</tr>
<tr>
<td>Ha</td>
<td>H</td>
<td>Snow Hills</td>
<td>Snow,Hills</td>
</tr>
<tr>
<td>Hd</td>
<td>J</td>
<td>Dunes</td>
<td>Sand,Hills</td>
</tr>
<tr>
<td>Hh</td>
<td>h</td>
<td>Hills</td>
<td></td>
</tr>
<tr>
<td>Md</td>
<td>M</td>
<td>Mountains</td>
<td>Mountains</td>
</tr>
<tr>
<td>Mm</td>
<td>m</td>
<td>Mountains</td>
<td></td>
</tr>
<tr>
<td>Qxu</td>
<td>X</td>
<td>Chasm</td>
<td></td>
</tr>
<tr>
<td>Ql</td>
<td>l</td>
<td>Lava</td>
<td>Chasm</td>
</tr>
<tr>
<td>Rd</td>
<td>E</td>
<td>Desert road</td>
<td>Grassland</td>
</tr>
<tr>
<td>Re</td>
<td>r</td>
<td>Dirt</td>
<td>Grassland</td>
</tr>
<tr>
<td>Rr</td>
<td>E</td>
<td>Road</td>
<td>Grassland</td>
</tr>
<tr>
<td>Re^Gvs</td>
<td></td>
<td>Farmland</td>
<td>Grassland</td>
</tr>
<tr>
<td>Ss</td>
<td>w</td>
<td>Swamp</td>
<td></td>
</tr>
<tr>
<td>Uu</td>
<td>u</td>
<td>Cave</td>
<td></td>
</tr>
<tr>
<td>Uu^Ii</td>
<td>'</td>
<td>Cave Lit</td>
<td>Cave</td>
</tr>
<tr>
<td>Uu^Uf</td>
<td>]</td>
<td>Mushroom Grove</td>
<td></td>
</tr>
<tr>
<td>Re^Uf</td>
<td></td>
<td>Mushroom Grove</td>
<td>Mushroom Grove</td>
</tr>
<tr>
<td>Uh</td>
<td>[</td>
<td>Rockbound Cave</td>
<td>Cave,Hills</td>
</tr>
<tr>
<td>Uh^Ii</td>
<td></td>
<td>Rockbound Cave Lit</td>
<td>Cave,Hills</td>
</tr>
<tr>
<td>Dd^Vda</td>
<td>U</td>
<td>Village</td>
<td>Village,Sand</td>
</tr>
<tr>
<td>Dd^Vdt</td>
<td>U</td>
<td>Village</td>
<td>Village,Sand</td>
</tr>
<tr>
<td>Aa^Vea</td>
<td>e</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>Gg^Ve</td>
<td>t</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>Aa^Vha</td>
<td>V</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>Gg^Vh</td>
<td>t</td>
<td>Village</td>
<td></td>
</tr>
<tr>
<td>Hh^Vhh</td>
<td>a</td>
<td>Village</td>
<td>Village,Hills</td>
</tr>
<tr>
<td>Ha^Vhha</td>
<td>A</td>
<td>Village</td>
<td>Village,Hills</td>
</tr>
<tr>
<td>Mm^Vhh</td>
<td>b</td>
<td>Village</td>
<td>Village,Mountains</td>
</tr>
<tr>
<td>Gs^Vht</td>
<td>L</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>Uu^Vu</td>
<td>D</td>
<td>Village</td>
<td>Village,Cave</td>
</tr>
<tr>
<td>Uu^Vud</td>
<td>p</td>
<td>Village</td>
<td>Village,Cave</td>
</tr>
<tr>
<td>Ww^Vm</td>
<td>Z</td>
<td>Village</td>
<td>Shallow Water</td>
</tr>
<tr>
<td>Ss^Vhs</td>
<td>Y</td>
<td>Village</td>
<td>Village,Swamp</td>
</tr>
<tr>
<td>Ss^Vm</td>
<td></td>
<td>Village</td>
<td>Swamp</td>
</tr>
<tr>
<td>Wo</td>
<td>s</td>
<td>Deep Water</td>
<td></td>
</tr>
<tr>
<td>Ww</td>
<td>c</td>
<td>Shallow Water</td>
<td></td>
</tr>
<tr>
<td>Wwf</td>
<td>k</td>
<td>River Ford</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>Mm^Xm</td>
<td>&</td>
<td>Impassable Mountains</td>
<td>Cave Wall</td>
</tr>
<tr>
<td>Md^Xm</td>
<td></td>
<td>Impassable Desert Mountains</td>
<td>Cave Wall</td>
</tr>
<tr>
<td>Xu</td>
<td>W</td>
<td>Cave Wall</td>
<td></td>
</tr>

</table>

== Adding terrains ==
When adding terrains make sure the following files are also checked:

data/faction/* contains favorite positions for the different factions, this is only used for the random map generator at the moment so it is not very important.

data/abilities.cfg contains the definition of ''submerge'' and ''ambush'' so depending on the change these need to be updated.

data/utils/utils.cfg contains the macro STARTING_VILLAGES which contains a list of village strings. This list doesn't support wildcards (yet).

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

[[Category: WML Reference]]

TerrainCodesWML

2007-08-31T12:48:51Z

CIB:

{{WML Tags}}
== Values of terrain letters ==

What each letter represents in Wesnoth maps,
and the possible values of the ''letter'' key.

See [[TerrainWML]] for information on how to define a terrain.

* '''A''' human (snow) hill village
* '''a''' human hill village
* '''B''' desert village (adobe)
* '''b''' human mountain village
* '''C''' castle
* '''c''' shallow water, "coast"
* '''D''' underground village (cave, village), "dungeon village"
* '''d''' sand, (old desert)
* '''E''' desert road
* '''e''' elven (snow) village
* '''F''' forest (snow)
* '''f''' forest
* '''G''' savanna (grass)
* '''g''' grass
* '''H''' hills (snow)
* '''h''' hills
* '''I''' desert
* '''i''' ice (tundra)
* '''J''' desert hills
* '''j''' -nothing- (will be snowy mountains)
* '''K''' keep (castle)
* '''k''' river ford (grass, shallow water)
* '''L''' tropical forest village (savanna, village)
* '''l''' lava (canyon)
* '''M''' desert mountains
* '''m''' mountain
* '''N''' ruined castle
* '''n''' encampment (castle)
* '''O''' -nothing- (will probably be an Orc Castle one day)
* '''o''' dwarven castle (castle)
* '''P''' desert oasis
* '''p''' dwarven village
* '''Q''' sunken ruin
* '''q''' ruin (swamp)
* '''R''' road (grass)
* '''r''' dirt (grass)
* '''S''' tundra
* '''s''' deep water
* '''T''' forest (tropical)
* '''t''' village
* '''U''' desert village (tent)
* '''u''' cave
* '''V''' snow village (tundra, village)
* '''v''' human village (village)
* '''W''' cavewall
* '''w''' swamp
* '''X''' canyon (replaced by chasm in trunk)
* '''x''' reserved for UMCs
* '''Y''' swamp village (swamp, village)
* '''y''' reserved for UMCs
* '''Z''' mermen village (shallow water)
* '''z''' reserved for UMCs
* '''/''','''|''','''\''' bridge (grass, shallow water)
* '''~''' fog
* ' ' void/shroud (it uses the "space" character)
* '''*''' reserved for UMCs
* '''^''' reserved for UMCs
* '''%''' reserved for UMCs
* '''@''' reserved for UMCs
* '''[''' rockbound cave
* ''']''' mushroom grove
* ''' ' ''' illuminated cave
* ''' ? ''' great Elven tree
* ''' & ''' impassable mountains
* ''' " ''' ???
* ''' $ ''' ???
* ''' . ''' ???
* ''' ; ''' ???
* ''' : ''' ???
* ''' < ''' ???
* ''' > ''' ???
* ''' _ ''' ???
* ''' ` ''' ???

==Reserved letters and non-letter Characters==
Reserved letters are for custom terrains in user-made campaigns. In addition to these it is currently also possible to use other characters not on the above list to represent custom terrain, such as ½ § @ % etc., but new "official" terrain may be assigned for these characters in the future. So when creating custom terrain, the letters marked as reserved on the above list should be used first.
Use campaign definitions (see [[CampaignWML]]) to prevent your custom terrains from interfering with other campaigns.

== Terrain strings '''''[[User:SkeletonCrew#Branch_terrain|(SVN terrain only)]]''''' ==
The terrains will be changed from a single letter to a multi letter system. There will be a compability layer for a short while. This layer doesn't work for campaigns with custom terrains, these campaigns have to be changed to use the new system.

The following rules are stated for the new terrain letters, note most of these rules are not validated since it would slow down Wesnoth; not following these rules might break Wesnoth.
* terrain strings are between 2 and 4 characters
* terrain strings start with a capital letter and the following letters are lower case
* terrain strings can only contain letters and the symbols /|\ which are meant for directional items like bridges.
* the underscore is used for internal terrains
* the star '*' can be used for wildcards in some parts

Starting positions are defined by a number followed by 1 space and then the terrain string; this means that a starting position is no longer automatically a keep.

The letters Y,y,Z,z are reserved for UMC so any string containing any of these letters is a custom terrain. Other undefined terrain strings are reserved for future expansion within Wesnoth.

=== Conversion form old to new ===
Map conversion logic is included in the [[Maintenance_tools|upconvert]] tool (in newer versions, [[Maintenance_tools|wmllint]]). This script will, among other things, convert a map with the old letters to the new strings. Here is a lookup table with the letters.

char= a b c d e f g h i j k l m
str= Vhh Vhm Ww Ds Vea Ff Gg Hh Ai Wwf Ql Mm

char= n o p q r s t u v w x y z
str= Ce Cud Vud Chs Re Wo Veg Uu Vhg Ss

char= A B C D E F G H I J K L M
str= Vhha Vda Ch Vu Rd Fa Gs Ha Dd Hd _K Vht Md

char= N O P Q R S T U V W X Y Z
str= Chr Do Chw Rr Aa Ft Vdt Vha Xu Qxu Vs Vwm

char= / | \ & _ ~ ? ] [ '
str= Bww/ Bww| Bww\ Xm _s _f Fet Uf Uh Uui

=== Terrain Table ===
This is a list of the terrains, the strings used for them in the new map format, the letters used for them in the old map format, their id and the terrains they take their stats from.

<table border="1"><tr>
<th>ID</th>
<th>String</th>
<th>Old letter</th>
<th>Name</th>
<th>Stats from</th>
</tr>
<tr>
<td>off_map</td>
<td>_off^_usr</td>
<td></td>
<td>None</td>
<td></td>
</tr>
<tr>
<td>shroud</td>
<td>_s</td>
<td></td>
<td>Shroud</td>
<td></td>
</tr>
<tr>
<td>fog</td>
<td>_f</td>
<td>~</td>
<td>Fog</td>
<td></td>
</tr>
<tr>
<td>ice</td>
<td>Ai</td>
<td>i</td>
<td>Ice</td>
<td>Snow</td>
</tr>
<tr>
<td>tundra</td>
<td>Aa</td>
<td>S</td>
<td>Snow</td>
<td></td>
</tr>
<tr>
<td>bridge</td>
<td>Ww^Bw|</td>
<td>|</td>
<td>Bridge</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>bridgediag1</td>
<td>Ww^Bw/</td>
<td>/</td>
<td>Bridge</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>bridgediag2</td>
<td>Ww^Bw\</td>
<td>\</td>
<td>Bridge</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>bridgedeep</td>
<td>Wo^Bw|</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Deep Water</td>
</tr>
<tr>
<td>bridgedeepdiag1</td>
<td>Wo^Bw/</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Deep Water</td>
</tr>
<tr>
<td>bridgedeepdiag2</td>
<td>Wo^Bw\</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Deep Water</td>
</tr>
<tr>
<td>bridgeswamp</td>
<td>Ss^Bw|</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Swamp</td>
</tr>
<tr>
<td>bridgeswampdiag1</td>
<td>Ss^Bw/</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Swamp</td>
</tr>
<tr>
<td>bridgeswampdiag2</td>
<td>Ss^Bw\</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Swamp</td>
</tr>
<tr>
<td>encampment</td>
<td>Ce</td>
<td>n</td>
<td>Encampment</td>
<td>Castle</td>
</tr>
<tr>
<td>castle</td>
<td>Ch</td>
<td>y</td>
<td>Castle</td>
<td></td>
</tr>
<tr>
<td>castle</td>
<td>Cv</td>
<td>y</td>
<td>Elven Castle</td>
<td>Castle</td>
</tr>
<tr>
<td>dwarven_castle</td>
<td>Cud</td>
<td>o</td>
<td>Dwarven Castle</td>
<td>Castle</td>
</tr>
<tr>
<td>ruin</td>
<td>Chr</td>
<td>N</td>
<td>Ruin</td>
<td>Castle</td>
</tr>
<tr>
<td>sunkenruin</td>
<td>Chw</td>
<td>Q</td>
<td>Sunken Ruin</td>
<td>Castle,Shallow Water</td>
</tr>
<tr>
<td>swampruin</td>
<td>Chs</td>
<td>q</td>
<td>Swamp Ruin</td>
<td>Castle,Swamp</td>
</tr>
<tr>
<td>encampment_keep</td>
<td>Ke</td>
<td></td>
<td>Encampment keep</td>
<td>Castle</td>
</tr>
<tr>
<td>human_keep</td>
<td>Kh</td>
<td></td>
<td>Keep</td>
<td>Castle</td>
</tr>
<tr>
<td>elven_keep</td>
<td>Kv</td>
<td></td>
<td>Elven Keep</td>
<td>Castle</td>
</tr>
<tr>
<td>dwarven_keep</td>
<td>Kud</td>
<td></td>
<td>Dwarven keep</td>
<td>Castle</td>
</tr>
<tr>
<td>ruined_keep</td>
<td>Khr</td>
<td></td>
<td>Ruined keep</td>
<td>Castle</td>
</tr>
<tr>
<td>sunken_keep</td>
<td>Khw</td>
<td></td>
<td>Sunken keep</td>
<td>Castle,Shallow Water</td>
</tr>
<tr>
<td>swamp_keep</td>
<td>Khs</td>
<td></td>
<td>Swamp keep</td>
<td>Castle,Swamp</td>
</tr>
<tr>
<td>crater</td>
<td>Dd^Dc</td>
<td></td>
<td>Crater</td>
<td>Sand</td>
</tr>
<tr>
<td>desert</td>
<td>Dd</td>
<td>I</td>
<td>Desert</td>
<td>Sand</td>
</tr>
<tr>
<td>sand_rubble</td>
<td>Dd^Dr</td>
<td></td>
<td>Rubble</td>
<td>Hills</td>
</tr>
<tr>
<td>sand</td>
<td>Ds</td>
<td>d</td>
<td>Sand</td>
<td></td>
</tr>
<tr>
<td>oasis</td>
<td>Dd^Do</td>
<td>P</td>
<td>Oasis</td>
<td>Sand</td>
</tr>
<tr>
<td>snow_forest</td>
<td>Aa^Fpa</td>
<td>F</td>
<td>Snow Forest</td>
<td>Snow,Forest</td>
</tr>
<tr>
<td>great_tree</td>
<td>Gg^Fet</td>
<td>?</td>
<td>Great Tree</td>
<td>Forest</td>
</tr>
<tr>
<td>forest</td>
<td>Gs^Fp</td>
<td>f</td>
<td>Forest</td>
<td></td>
</tr>
<tr>
<td>tropical_forest</td>
<td>Gs^Ft</td>
<td>T</td>
<td>Tropical Forest</td>
<td>Forest</td>
</tr>
<tr>
<td>grassland</td>
<td>Gg</td>
<td>g</td>
<td>Grassland</td>
<td></td>
</tr>
<tr>
<td>grassland_flowers</td>
<td>Ggf</td>
<td></td>
<td>Grassland</td>
<td>Grassland</td>
</tr>
<tr>
<td>savanna</td>
<td>Gs</td>
<td>G</td>
<td>Savanna</td>
<td>Grassland</td>
</tr>
<tr>
<td>snow_hills</td>
<td>Ha</td>
<td>H</td>
<td>Snow Hills</td>
<td>Snow,Hills</td>
</tr>
<tr>
<td>desert_hills</td>
<td>Hd</td>
<td>J</td>
<td>Dunes</td>
<td>Sand,Hills</td>
</tr>
<tr>
<td>hills</td>
<td>Hh</td>
<td>h</td>
<td>Hills</td>
<td></td>
</tr>
<tr>
<td>desert_mountains</td>
<td>Md</td>
<td>M</td>
<td>Mountains</td>
<td>Mountains</td>
</tr>
<tr>
<td>mountains</td>
<td>Mm</td>
<td>m</td>
<td>Mountains</td>
<td></td>
</tr>
<tr>
<td>canyon</td>
<td>Qxu</td>
<td>X</td>
<td>Chasm</td>
<td></td>
</tr>
<tr>
<td>lava</td>
<td>Ql</td>
<td>l</td>
<td>Lava</td>
<td>Chasm</td>
</tr>
<tr>
<td>road</td>
<td>Rd</td>
<td>E</td>
<td>Desert road</td>
<td>Grassland</td>
</tr>
<tr>
<td>dirt</td>
<td>Re</td>
<td>r</td>
<td>Dirt</td>
<td>Grassland</td>
</tr>
<tr>
<td>road</td>
<td>Rr</td>
<td>E</td>
<td>Road</td>
<td>Grassland</td>
</tr>
<tr>
<td>farm</td>
<td>Re^Gvs</td>
<td></td>
<td>Farmland</td>
<td>Grassland</td>
</tr>
<tr>
<td>swamp_water</td>
<td>Ss</td>
<td>w</td>
<td>Swamp</td>
<td></td>
</tr>
<tr>
<td>cave</td>
<td>Uu</td>
<td>u</td>
<td>Cave</td>
<td></td>
</tr>
<tr>
<td>cave_beam</td>
<td>Uu^Ii</td>
<td>'</td>
<td>Cave Lit</td>
<td>Cave</td>
</tr>
<tr>
<td>fungus</td>
<td>Uu^Uf</td>
<td>]</td>
<td>Mushroom Grove</td>
<td></td>
</tr>
<tr>
<td>fungusabove</td>
<td>Re^Uf</td>
<td></td>
<td>Mushroom Grove</td>
<td>Mushroom Grove</td>
</tr>
<tr>
<td>rocky_cave</td>
<td>Uh</td>
<td>[</td>
<td>Rockbound Cave</td>
<td>Cave,Hills</td>
</tr>
<tr>
<td>rocky_cave_beam</td>
<td>Uh^Ii</td>
<td></td>
<td>Rockbound Cave Lit</td>
<td>Cave,Hills</td>
</tr>
<tr>
<td>desert_village</td>
<td>Dd^Vda</td>
<td>U</td>
<td>Village</td>
<td>Village,Sand</td>
</tr>
<tr>
<td>desert_village</td>
<td>Dd^Vdt</td>
<td>U</td>
<td>Village</td>
<td>Village,Sand</td>
</tr>
<tr>
<td>elven_snow_village</td>
<td>Aa^Vea</td>
<td>e</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>village</td>
<td>Gg^Ve</td>
<td>t</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>snow_village</td>
<td>Aa^Vha</td>
<td>V</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>village</td>
<td>Gg^Vh</td>
<td>t</td>
<td>Village</td>
<td></td>
</tr>
<tr>
<td>hill_village</td>
<td>Hh^Vhh</td>
<td>a</td>
<td>Village</td>
<td>Village,Hills</td>
</tr>
<tr>
<td>snow-hill_village</td>
<td>Ha^Vhha</td>
<td>A</td>
<td>Village</td>
<td>Village,Hills</td>
</tr>
<tr>
<td>mountain_village</td>
<td>Mm^Vhh</td>
<td>b</td>
<td>Village</td>
<td>Village,Mountains</td>
</tr>
<tr>
<td>tropical_forest_village</td>
<td>Gs^Vht</td>
<td>L</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>underground_village</td>
<td>Uu^Vu</td>
<td>D</td>
<td>Village</td>
<td>Village,Cave</td>
</tr>
<tr>
<td>dwarven_village</td>
<td>Uu^Vud</td>
<td>p</td>
<td>Village</td>
<td>Village,Cave</td>
</tr>
<tr>
<td>mermen_village</td>
<td>Ww^Vm</td>
<td>Z</td>
<td>Village</td>
<td>Shallow Water</td>
</tr>
<tr>
<td>swamp_village</td>
<td>Ss^Vhs</td>
<td>Y</td>
<td>Village</td>
<td>Village,Swamp</td>
</tr>
<tr>
<td>swamp_merfolk-village</td>
<td>Ss^Vm</td>
<td></td>
<td>Village</td>
<td>Swamp</td>
</tr>
<tr>
<td>deep_water</td>
<td>Wo</td>
<td>s</td>
<td>Deep Water</td>
<td></td>
</tr>
<tr>
<td>shallow_water</td>
<td>Ww</td>
<td>c</td>
<td>Shallow Water</td>
<td></td>
</tr>
<tr>
<td>ford</td>
<td>Wwf</td>
<td>k</td>
<td>River Ford</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>cloud</td>
<td>Mm^Xm</td>
<td>&</td>
<td>Impassable Mountains</td>
<td>Cave Wall</td>
</tr>
<tr>
<td>clouddesert</td>
<td>Md^Xm</td>
<td></td>
<td>Impassable Desert Mountains</td>
<td>Cave Wall</td>
</tr>
<tr>
<td>cavewall</td>
<td>Xu</td>
<td>W</td>
<td>Cave Wall</td>
<td></td>
</tr>

</table>

==== Specials ====
These terrains are hardcoded in the game and translated
automatically. The old UMC terrains are here for backwards
compability this compability will only be guaranteed till
the next major release after 1.2.(That would be 1.4 or 2.0.)
As stated before the * will no longer be supported.

<table border="1"><tr>
<th>String</th>
<th>Old letter</th>
<th>Description</th>
<th>Theme</th>
</tr>

<tr>
<td>_f</td>
<td>~</td>
<td>fog</td>
<td>misc</td>
</tr>

<tr>
<td>_s</td>
<td> (space character)</td>
<td>void/shroud</td>
<td>misc</td>
</tr>

</table>

== Adding terrains ==
When adding terrains make sure the following files are also checked:

data/faction/* contains favorite positions for the different factions, this is only used for the random map generator at the moment so it is not very important.

data/abilities.cfg contains the definition of ''submerge'' and ''ambush'' so depending on the change these need to be updated.

data/utils/utils.cfg contains the macro STARTING_VILLAGES which contains a list of village strings. This list doesn't support wildcards (yet).

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

[[Category: WML Reference]]

TerrainCodesWML

2007-08-31T12:46:57Z

CIB: /* Terrain strings '''''(SVN terrain only)''''' */

{{WML Tags}}
== Values of terrain letters ==

What each letter represents in Wesnoth maps,
and the possible values of the ''letter'' key.

See [[TerrainWML]] for information on how to define a terrain.

* '''A''' human (snow) hill village
* '''a''' human hill village
* '''B''' desert village (adobe)
* '''b''' human mountain village
* '''C''' castle
* '''c''' shallow water, "coast"
* '''D''' underground village (cave, village), "dungeon village"
* '''d''' sand, (old desert)
* '''E''' desert road
* '''e''' elven (snow) village
* '''F''' forest (snow)
* '''f''' forest
* '''G''' savanna (grass)
* '''g''' grass
* '''H''' hills (snow)
* '''h''' hills
* '''I''' desert
* '''i''' ice (tundra)
* '''J''' desert hills
* '''j''' -nothing- (will be snowy mountains)
* '''K''' keep (castle)
* '''k''' river ford (grass, shallow water)
* '''L''' tropical forest village (savanna, village)
* '''l''' lava (canyon)
* '''M''' desert mountains
* '''m''' mountain
* '''N''' ruined castle
* '''n''' encampment (castle)
* '''O''' -nothing- (will probably be an Orc Castle one day)
* '''o''' dwarven castle (castle)
* '''P''' desert oasis
* '''p''' dwarven village
* '''Q''' sunken ruin
* '''q''' ruin (swamp)
* '''R''' road (grass)
* '''r''' dirt (grass)
* '''S''' tundra
* '''s''' deep water
* '''T''' forest (tropical)
* '''t''' village
* '''U''' desert village (tent)
* '''u''' cave
* '''V''' snow village (tundra, village)
* '''v''' human village (village)
* '''W''' cavewall
* '''w''' swamp
* '''X''' canyon (replaced by chasm in trunk)
* '''x''' reserved for UMCs
* '''Y''' swamp village (swamp, village)
* '''y''' reserved for UMCs
* '''Z''' mermen village (shallow water)
* '''z''' reserved for UMCs
* '''/''','''|''','''\''' bridge (grass, shallow water)
* '''~''' fog
* ' ' void/shroud (it uses the "space" character)
* '''*''' reserved for UMCs
* '''^''' reserved for UMCs
* '''%''' reserved for UMCs
* '''@''' reserved for UMCs
* '''[''' rockbound cave
* ''']''' mushroom grove
* ''' ' ''' illuminated cave
* ''' ? ''' great Elven tree
* ''' & ''' impassable mountains
* ''' " ''' ???
* ''' $ ''' ???
* ''' . ''' ???
* ''' ; ''' ???
* ''' : ''' ???
* ''' < ''' ???
* ''' > ''' ???
* ''' _ ''' ???
* ''' ` ''' ???

==Reserved letters and non-letter Characters==
Reserved letters are for custom terrains in user-made campaigns. In addition to these it is currently also possible to use other characters not on the above list to represent custom terrain, such as ½ § @ % etc., but new "official" terrain may be assigned for these characters in the future. So when creating custom terrain, the letters marked as reserved on the above list should be used first.
Use campaign definitions (see [[CampaignWML]]) to prevent your custom terrains from interfering with other campaigns.

== Terrain strings '''''[[User:SkeletonCrew#Branch_terrain|(SVN terrain only)]]''''' ==
The terrains will be changed from a single letter to a multi letter system. There will be a compability layer for a short while. This layer doesn't work for campaigns with custom terrains, these campaigns have to be changed to use the new system.

The following rules are stated for the new terrain letters, note most of these rules are not validated since it would slow down Wesnoth; not following these rules might break Wesnoth.
* terrain strings are between 2 and 4 characters
* terrain strings start with a capital letter and the following letters are lower case
* terrain strings can only contain letters and the symbols /|\ which are meant for directional items like bridges.
* the underscore is used for internal terrains
* the star '*' can be used for wildcards in some parts

Starting positions are defined by a number followed by 1 space and then the terrain string; this means that a starting position is no longer automatically a keep.

The letters Y,y,Z,z are reserved for UMC so any string containing any of these letters is a custom terrain. Other undefined terrain strings are reserved for future expansion within Wesnoth.

=== Conversion form old to new ===
Map conversion logic is included in the [[Maintenance_tools|upconvert]] tool (in newer versions, [[Maintenance_tools|wmllint]]). This script will, among other things, convert a map with the old letters to the new strings. Here is a lookup table with the letters.

char= a b c d e f g h i j k l m
str= Vhh Vhm Ww Ds Vea Ff Gg Hh Ai Wwf Ql Mm

char= n o p q r s t u v w x y z
str= Ce Cud Vud Chs Re Wo Veg Uu Vhg Ss

char= A B C D E F G H I J K L M
str= Vhha Vda Ch Vu Rd Fa Gs Ha Dd Hd _K Vht Md

char= N O P Q R S T U V W X Y Z
str= Chr Do Chw Rr Aa Ft Vdt Vha Xu Qxu Vs Vwm

char= / | \ & _ ~ ? ] [ '
str= Bww/ Bww| Bww\ Xm _s _f Fet Uf Uh Uui

=== Terrain Table ===
This is a list of the terrains, the strings used for them in the new map format, the letters used for them in the old map format, their id and the terrains they take their stats from.

<table border="1"><tr>
<th>ID</th>
<th>String</th>
<th>Old letter</th>
<th>Name</th>
<th>Stats from</th>
</tr>
<tr>
<td>off_map</td>
<td>_off^_usr</td>
<td></td>
<td>None</td>
<td></td>
</tr>
<tr>
<td>shroud</td>
<td>_s</td>
<td></td>
<td>Shroud</td>
<td></td>
</tr>
<tr>
<td>fog</td>
<td>_f</td>
<td>~</td>
<td>Fog</td>
<td></td>
</tr>
<tr>
<td>ice</td>
<td>Ai</td>
<td>i</td>
<td>Ice</td>
<td>Snow</td>
</tr>
<tr>
<td>tundra</td>
<td>Aa</td>
<td>S</td>
<td>Snow</td>
<td></td>
</tr>
<tr>
<td>bridge</td>
<td>Ww^Bw|</td>
<td>|</td>
<td>Bridge</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>bridgediag1</td>
<td>Ww^Bw/</td>
<td>/</td>
<td>Bridge</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>bridgediag2</td>
<td>Ww^Bw\</td>
<td>\</td>
<td>Bridge</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>bridgedeep</td>
<td>Wo^Bw|</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Deep Water</td>
</tr>
<tr>
<td>bridgedeepdiag1</td>
<td>Wo^Bw/</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Deep Water</td>
</tr>
<tr>
<td>bridgedeepdiag2</td>
<td>Wo^Bw\</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Deep Water</td>
</tr>
<tr>
<td>bridgeswamp</td>
<td>Ss^Bw|</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Swamp</td>
</tr>
<tr>
<td>bridgeswampdiag1</td>
<td>Ss^Bw/</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Swamp</td>
</tr>
<tr>
<td>bridgeswampdiag2</td>
<td>Ss^Bw\</td>
<td></td>
<td>Bridge</td>
<td>Grassland,Swamp</td>
</tr>
<tr>
<td>encampment</td>
<td>Ce</td>
<td>n</td>
<td>Encampment</td>
<td>Castle</td>
</tr>
<tr>
<td>castle</td>
<td>Ch</td>
<td>y</td>
<td>Castle</td>
<td></td>
</tr>
<tr>
<td>castle</td>
<td>Cv</td>
<td>y</td>
<td>Elven Castle</td>
<td>Castle</td>
</tr>
<tr>
<td>dwarven_castle</td>
<td>Cud</td>
<td>o</td>
<td>Dwarven Castle</td>
<td>Castle</td>
</tr>
<tr>
<td>ruin</td>
<td>Chr</td>
<td>N</td>
<td>Ruin</td>
<td>Castle</td>
</tr>
<tr>
<td>sunkenruin</td>
<td>Chw</td>
<td>Q</td>
<td>Sunken Ruin</td>
<td>Castle,Shallow Water</td>
</tr>
<tr>
<td>swampruin</td>
<td>Chs</td>
<td>q</td>
<td>Swamp Ruin</td>
<td>Castle,Swamp</td>
</tr>
<tr>
<td>encampment_keep</td>
<td>Ke</td>
<td></td>
<td>Encampment keep</td>
<td>Castle</td>
</tr>
<tr>
<td>human_keep</td>
<td>Kh</td>
<td></td>
<td>Keep</td>
<td>Castle</td>
</tr>
<tr>
<td>elven_keep</td>
<td>Kv</td>
<td></td>
<td>Elven Keep</td>
<td>Castle</td>
</tr>
<tr>
<td>dwarven_keep</td>
<td>Kud</td>
<td></td>
<td>Dwarven keep</td>
<td>Castle</td>
</tr>
<tr>
<td>ruined_keep</td>
<td>Khr</td>
<td></td>
<td>Ruined keep</td>
<td>Castle</td>
</tr>
<tr>
<td>sunken_keep</td>
<td>Khw</td>
<td></td>
<td>Sunken keep</td>
<td>Castle,Shallow Water</td>
</tr>
<tr>
<td>swamp_keep</td>
<td>Khs</td>
<td></td>
<td>Swamp keep</td>
<td>Castle,Swamp</td>
</tr>
<tr>
<td>crater</td>
<td>Dd^Dc</td>
<td></td>
<td>Crater</td>
<td>Sand</td>
</tr>
<tr>
<td>desert</td>
<td>Dd</td>
<td>I</td>
<td>Desert</td>
<td>Sand</td>
</tr>
<tr>
<td>sand_rubble</td>
<td>Dd^Dr</td>
<td></td>
<td>Rubble</td>
<td>Hills</td>
</tr>
<tr>
<td>sand</td>
<td>Ds</td>
<td>d</td>
<td>Sand</td>
<td></td>
</tr>
<tr>
<td>oasis</td>
<td>Dd^Do</td>
<td>P</td>
<td>Oasis</td>
<td>Sand</td>
</tr>
<tr>
<td>snow_forest</td>
<td>Aa^Fpa</td>
<td>F</td>
<td>Snow Forest</td>
<td>Snow,Forest</td>
</tr>
<tr>
<td>great_tree</td>
<td>Gg^Fet</td>
<td>?</td>
<td>Great Tree</td>
<td>Forest</td>
</tr>
<tr>
<td>forest</td>
<td>Gs^Fp</td>
<td>f</td>
<td>Forest</td>
<td></td>
</tr>
<tr>
<td>tropical_forest</td>
<td>Gs^Ft</td>
<td>T</td>
<td>Tropical Forest</td>
<td>Forest</td>
</tr>
<tr>
<td>grassland</td>
<td>Gg</td>
<td>g</td>
<td>Grassland</td>
<td></td>
</tr>
<tr>
<td>grassland_flowers</td>
<td>Ggf</td>
<td></td>
<td>Grassland</td>
<td>Grassland</td>
</tr>
<tr>
<td>savanna</td>
<td>Gs</td>
<td>G</td>
<td>Savanna</td>
<td>Grassland</td>
</tr>
<tr>
<td>snow_hills</td>
<td>Ha</td>
<td>H</td>
<td>Snow Hills</td>
<td>Snow,Hills</td>
</tr>
<tr>
<td>desert_hills</td>
<td>Hd</td>
<td>J</td>
<td>Dunes</td>
<td>Sand,Hills</td>
</tr>
<tr>
<td>hills</td>
<td>Hh</td>
<td>h</td>
<td>Hills</td>
<td></td>
</tr>
<tr>
<td>desert_mountains</td>
<td>Md</td>
<td>M</td>
<td>Mountains</td>
<td>Mountains</td>
</tr>
<tr>
<td>mountains</td>
<td>Mm</td>
<td>m</td>
<td>Mountains</td>
<td></td>
</tr>
<tr>
<td>canyon</td>
<td>Qxu</td>
<td>X</td>
<td>Chasm</td>
<td></td>
</tr>
<tr>
<td>lava</td>
<td>Ql</td>
<td>l</td>
<td>Lava</td>
<td>Chasm</td>
</tr>
<tr>
<td>road</td>
<td>Rd</td>
<td>E</td>
<td>Desert road</td>
<td>Grassland</td>
</tr>
<tr>
<td>dirt</td>
<td>Re</td>
<td>r</td>
<td>Dirt</td>
<td>Grassland</td>
</tr>
<tr>
<td>road</td>
<td>Rr</td>
<td>E</td>
<td>Road</td>
<td>Grassland</td>
</tr>
<tr>
<td>farm</td>
<td>Re^Gvs</td>
<td></td>
<td>Farmland</td>
<td>Grassland</td>
</tr>
<tr>
<td>swamp_water</td>
<td>Ss</td>
<td>w</td>
<td>Swamp</td>
<td></td>
</tr>
<tr>
<td>cave</td>
<td>Uu</td>
<td>u</td>
<td>Cave</td>
<td></td>
</tr>
<tr>
<td>cave_beam</td>
<td>Uu^Ii</td>
<td>'</td>
<td>Cave Lit</td>
<td>Cave</td>
</tr>
<tr>
<td>fungus</td>
<td>Uu^Uf</td>
<td>]</td>
<td>Mushroom Grove</td>
<td></td>
</tr>
<tr>
<td>fungusabove</td>
<td>Re^Uf</td>
<td></td>
<td>Mushroom Grove</td>
<td>Mushroom Grove</td>
</tr>
<tr>
<td>rocky_cave</td>
<td>Uh</td>
<td>[</td>
<td>Rockbound Cave</td>
<td>Cave,Hills</td>
</tr>
<tr>
<td>rocky_cave_beam</td>
<td>Uh^Ii</td>
<td></td>
<td>Rockbound Cave Lit</td>
<td>Cave,Hills</td>
</tr>
<tr>
<td>desert_village</td>
<td>Dd^Vda</td>
<td>U</td>
<td>Village</td>
<td>Village,Sand</td>
</tr>
<tr>
<td>desert_village</td>
<td>Dd^Vdt</td>
<td>U</td>
<td>Village</td>
<td>Village,Sand</td>
</tr>
<tr>
<td>elven_snow_village</td>
<td>Aa^Vea</td>
<td>e</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>village</td>
<td>Gg^Ve</td>
<td>t</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>snow_village</td>
<td>Aa^Vha</td>
<td>V</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>village</td>
<td>Gg^Vh</td>
<td>t</td>
<td>Village</td>
<td></td>
</tr>
<tr>
<td>hill_village</td>
<td>Hh^Vhh</td>
<td>a</td>
<td>Village</td>
<td>Village,Hills</td>
</tr>
<tr>
<td>snow-hill_village</td>
<td>Ha^Vhha</td>
<td>A</td>
<td>Village</td>
<td>Village,Hills</td>
</tr>
<tr>
<td>mountain_village</td>
<td>Mm^Vhh</td>
<td>b</td>
<td>Village</td>
<td>Village,Mountains</td>
</tr>
<tr>
<td>tropical_forest_village</td>
<td>Gs^Vht</td>
<td>L</td>
<td>Village</td>
<td>Village</td>
</tr>
<tr>
<td>underground_village</td>
<td>Uu^Vu</td>
<td>D</td>
<td>Village</td>
<td>Village,Cave</td>
</tr>
<tr>
<td>dwarven_village</td>
<td>Uu^Vud</td>
<td>p</td>
<td>Village</td>
<td>Village,Cave</td>
</tr>
<tr>
<td>mermen_village</td>
<td>Ww^Vm</td>
<td>Z</td>
<td>Village</td>
<td>Shallow Water</td>
</tr>
<tr>
<td>swamp_village</td>
<td>Ss^Vhs</td>
<td>Y</td>
<td>Village</td>
<td>Village,Swamp</td>
</tr>
<tr>
<td>swamp_merfolk-village</td>
<td>Ss^Vm</td>
<td></td>
<td>Village</td>
<td>Swamp</td>
</tr>
<tr>
<td>deep_water</td>
<td>Wo</td>
<td>s</td>
<td>Deep Water</td>
<td></td>
</tr>
<tr>
<td>shallow_water</td>
<td>Ww</td>
<td>c</td>
<td>Shallow Water</td>
<td></td>
</tr>
<tr>
<td>ford</td>
<td>Wwf</td>
<td>k</td>
<td>River Ford</td>
<td>Grassland,Shallow Water</td>
</tr>
<tr>
<td>cloud</td>
<td>Mm^Xm</td>
<td>&</td>
<td>Impassable Mountains</td>
<td>Cave Wall</td>
</tr>
<tr>
<td>clouddese

==== Specials ====
These terrains are hardcoded in the game and translated
automatically. The old UMC terrains are here for backwards
compability this compability will only be guaranteed till
the next major release after 1.2.(That would be 1.4 or 2.0.)
As stated before the * will no longer be supported.

<table border="1"><tr>
<th>String</th>
<th>Old letter</th>
<th>Description</th>
<th>Theme</th>
</tr>

<tr>
<td>_f</td>
<td>~</td>
<td>fog</td>
<td>misc</td>
</tr>

<tr>
<td>_s</td>
<td> (space character)</td>
<td>void/shroud</td>
<td>misc</td>
</tr>

</table>

== Adding terrains ==
When adding terrains make sure the following files are also checked:

data/faction/* contains favorite positions for the different factions, this is only used for the random map generator at the moment so it is not very important.

data/abilities.cfg contains the definition of ''submerge'' and ''ambush'' so depending on the change these need to be updated.

data/utils/utils.cfg contains the macro STARTING_VILLAGES which contains a list of village strings. This list doesn't support wildcards (yet).

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

[[Category: WML Reference]]

ScenarioWML

2007-06-18T00:51:17Z

CIB: added the objectives attribute

{{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) You can speed up scenario development a lot by this when used in a clever way: Move a scenario into ~campaigns (so that it will be read even without its campaign being loaded), change it to a [test] scenario, and change the ID to 'test'. Then run Wesnoth in test mode. This saves about a minute for each time you want to test changes to your scenario. However it should not be used for balancing as there will be no recallable units...

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

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

* ''objectives'' sets the objectives for all sides. Useful for giving information about a MP scenario.

* ''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_starting_time=2,3,5,6'' (default=no) {{DevFeature}}

* ''music'' the music file relative to ''./music/'' to play during the scenario

* '''[music]''' specifies the music tracks to play during this scenario, see [[MusicListWML]].

* ''theme'' the UI theme that should be used when playing this scenario. See [[Using_custom_themes_in_campaigns]]

* ''victory_when_enemies_defeated'' when this is set to 'yes'(default), the player wins once all non-allied units with '''canrecruit=1''' (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.)

* ''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
** standard location filter
** '''[time]''', '''[illuminated_time]''' how a day should progress in those locations. See [[TimeWML]]

* '''[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 additionnally recognized in '''[multiplayer]''' scenarios:
* ''allow_new_game'' {{DevFeature}} (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]]

InternalActionsWML

2007-06-18T00:30:26Z

CIB: changed poison=on to poison=true