The Battle for Wesnoth Wiki - User contributions [en]

WesnothTranslations

2023-02-22T00:24:22Z

Luther: Change my email address

== Translations ==

Wesnoth is currently being translated into the following languages. Instructions on how to contribute are found here:
[[WesnothTranslationsHowTo]].

{| class="wikitable"
|-
! Translation !! Maintainer !! Contact
|-
| [[AfrikaansTranslation|Afrikaans]] || None || N/A
|-
| [[AncientGreekTranslation|Ancient Greek]] || None || N/A
|-
| [[ArabicTranslation|Arabic]] || Mejri Ziad (Hermestrismi)|| [mailto:beja.comuneATgmailDOTcom]
|-
| [[BasqueTranslation|Basque]] || None || N/A
|-
| [[BurmeseTranslation|Burmese]] || None || N/A
|-
| [[BulgarianTranslation|Bulgarian]] || Ivan Petrov (TheWhiteKnight) || [mailto:vankata_petrovATabvDOTbg]
|-
| [[CatalanTranslation|Catalan]] || Miquel-Àngel Burgos i Fradeja || [mailto:miquel.angel.burgosATgmailDOTcom]
|-
| [[ChineseTranslation|Chinese]] || CloudiDust || [mailto:cloudidustATgmailDOTcom]
|-
| [[ChineseTaiwanTranslation|Chinese (Taiwan)]] || 楊綮銘 (Taiwan) || [mailto:steven2880ATgmailDOTcom]
|-
| [[CroatianTranslation|Croatian]] || None || N/A
|-
| [[CzechTranslation|Czech]] || Michal Žejdl || [mailto:lachimATemerDOTcz]
|-
| [[DanishTranslation|Danish]] || None || N/A
|-
| [[DutchTranslation|Dutch]] || Merijn de Vet || [mailto:tybonzerATliveDOTnl]
|-
| [[EnglishGBTranslation|English (GB)]] || Wedge009 || [mailto:wedge009ATwedge009DOTnet]
|-
| [[EnglishShawTranslation|English (Shaw)]] || Arc Riley || [mailto:ArcRileyATubuntuDOTcom]
|-
| [[Esperanto_translation|Esperanto]] || Luther Thompson || [mailto:lutherotoATgmailDOTcom]
|-
| [[EstonianTranslation|Estonian]] || None || N/A
|-
| [[FilipinoTranslation|Filipino]] || None || N/A
|-
| [[FinnishTranslation|Finnish]] || Jaakko Saarikko (styxnix) || [mailto:jaakkoDOTsaarikkoATprotonmailDOTcom]
|-
| [[FrenchTranslation|French]] || Mathieu Guilbaud (Guim) || Translations ML
|-
| [[GalicianTranslation|Galician]] || None || N/A
|-
| [[GermanTranslation|German]] || Aaron Winter (Bitron) ||
|-
| [[GreekTranslation|Greek]] || None || N/A
|-
| [[HebrewTranslation|Hebrew]] || None || N/A
|-
| [[HungarianTranslation|Hungarian]] || Széll András || [mailto:szellDOTandrisATgmailDOTcom]
|-
| [[IcelandicTranslation|Icelandic]] || None || N/A
|-
| [[IndonesianTranslation|Indonesian]] || Irsyad Musthafa || [mailto:sevennightmareATtutanotaDOTde]
|-
| [[IrishTranslation|Irish]] || None || N/A
|-
| [[ItalianTranslation|Italian]] || Antonio Rosella || [mailto:arosellaATyahooDOTcom]
|-
| [[JapaneseTranslation|Japanese]] || Hironori Fujimoto (RatArmy) || [mailto:broadbarredfirefishATgmailDOTcom]
|-
| [[KoreanTranslation|Korean]] || mistzone || [mailto:drier22ATgmailDOTcom]
|-
| [[LatinTranslation|Latin]] || None || N/A
|-
| [[LatvianTranslation|Latvian]] || None || N/A
|-
| [[LithuanianTranslation|Lithuanian]] || None || N/A
|-
| [[MarathiTranslation|Marathi]] || None || N/A
|-
| [[MacedonianTranslation|Macedonian]] || None || N/A
|-
| [[NorwegianTranslation|Norwegian]] || None || N/A
|-
| [[OldEnglishTranslation|Old English]] || None || N/A
|-
| [[PolishTranslation|Polish]] || ForPeace || [https://forums.wesnoth.org/viewtopic.php?f=7&t=3796 forum thread]
|-
| [[PortugueseTranslation|Portuguese Brazilian]] || Andrei Machado || [mailto:andreisp.machadoATyahooDOTcom]
|-
| [[PortugueseContinentalTranslation|Portuguese (European)]] || trewe || [mailto:sjrs456ATyahooDOTfr]
|-
| [[RACVTranslation|RACV]] || None || N/A
|-
| [[RomanianTranslation|Romanian]] || None || N/A
|-
| [[RussianTranslation|Russian]] || Artem Khrapov || ([[User:kabachuha|kabachuha]]) [mailto:artemkhrapov2001ATyandexDOTru]
|-
| [[Scottish_Gaelic_Translation|Scottish Gaelic]] || GunChleoc || [mailto:fiosAIGforamnagaidhligDOTnet]
|-
| [[SerbianTranslation|Serbian]] || None || N/A
|-
| [[SlovakTranslation#Preklad|Slovak]] || Aceman ||
|-
| [[SlovenianTranslation|Slovenian]] || None || N/A
|-
| [[SpanishTranslation|Spanish]] || Toranks || [mailto:davinciATtoranksDOTes]
|-
| [[SpanishLatinAmericanTranslation|Spanish (Latin American)]] || None || N/A
|-
| [[SwedishTranslation|Swedish]] || Alex Alowersson (fluxbird) || [mailto:alexalowersonATgmailDOTcom]
|-
| [[TurkishTranslation|Turkish]] || Nilgün Belma Bugüner || [mailto:nilgunATbelgelerDOTorg]
|-
| [[UkrainianTranslation|Ukrainian]] || None || N/A
|-
| [[ValencianTranslation|Valencian]] || None || N/A
|-
| [[VietnameseTranslation|Vietnamese]] || None || N/A
|}

== Mailing List ==

There now is a mailing list dedicated to translation matters. It is mainly intended to be used for informing translation maintainers about important changes, to announce string freezes and other special things. Everyone is free to subscribe to this list.

* [https://listengine.tuxfamily.org/wesnoth.org/i18n/ List info, how to subscribe, and archives from April 2022]
* [https://mailman.wesnoth.org/pipermail/i18n/ Old list archives (up until April 2022)]

Please keep in mind that this list is not meant for discussing changes for one single translation but instead subjects which are relevant to all translations.

== See also ==

* [[WesnothTranslationsHowTo]]
* [[ImageLocalization]]
* [[GetText]]
* [http://gettext.wesnoth.org Translations statistics (stable)]
* [http://gettext.wesnoth.org/index.php?version=trunk&package=alloff Translations statistics (development)]
* [[WesCamp| Translating User made Campaigns (featuring WesCamp-i18n)]]
* [[SpellingMistakes]]
* [[CharactersStorys| Character descriptions for Translators (Spoiler Warning)]]
* [[Poetry of Wesnoth Translations]]

[[Category:Translations|*]]

Esperanto translation

2019-12-27T06:34:19Z

Luther: Update the maintainer

{{(eo) Traduko}}

En la forumo oni diskutas pri la Esperanta traduko ĉe la temo [http://www.wesnoth.org/forum/viewtopic.php?t=9742 #9742].

Se vi volas helpi traduki, bonvolu retpoŝte kontakti na Luther Thompson (luther ĉe librem punkto one).
Eĉ se vi ne scipovas la anglan, vi povas traduki uzante alilingvajn ekzistantajn tradukojn.

La tre ofte uzataj frazoj (ekzemple la nomoj de la milit-unuoj) kaj la ali-kiale gravaj frazoj (ekzemple la nomoj de scenaroj) meritas apartan atenton. Tial en tiu ĉi vikio oni kunordigas kaj pridiskutas pri ili.

== Nuna tradukteamo ==

* Luther Thompson - Kunordiganto - tradukas

== Malnova tradukteamo ==

En la programo aperas la nomoj (kaj kromnomoj) de ĉiuj kunaŭtoroj, inkluzive tradukantoj.
Ankaŭ por ni estas utile scii kiun kontakti rilate al unuopaj tradukoj.
Bonvolu trovi kaj eventuale korekti la informon pri vi jen.

* Aleksej Korgenkov ("Grimpanto") -- wesnoth-editor, wesnoth-tutorial
* Lubo Fajth -- wesnoth
* Maarten Albrecht -- wesnoth-ei
* Rasto Sarissky -- wesnoth-httt
* Manuel Ortega -- wesnoth, kunordiganto
* Viliam Bur -- kunordigado kaj helpo

== Ligiloj ==

* [http://wesnoth.slack.it/units.cgi Listo de milit-unuoj]
* [http://gettext.wesnoth.org/index.lang.php?lang=eo&version=trunk Statistiko de Esperanta traduko]

[[Category:Translations]]
[[Category:Esperanto]]

WesnothTranslations

2019-12-27T06:23:29Z

Luther: /* Translations */ Update Esperanto maintainer

== Translations ==

Wesnoth is currently being translated into the following languages. Instructions on how to contribute are found here:
[[WesnothTranslationsHowTo]].
* [[AfrikaansTranslation|Afrikaans]] - maintainer: Friedel Wolff - [mailto:friedelATSIGNtranslateDOTorgDOTza]
* [[ArabicTranslation|Arabic]] - maintainer: Amnay Mokhtari - [mailto:amnayAToperamailDOTcom]
* [[BasqueTranslation|Basque]] - maintainer: Alfredo Beaumont (ziberpunk) - [mailto:alfredo.beaumontATgmailDOTcom]
* [[BulgarianTranslation|Bulgarian]] maintainer: Ivan Petrov (TheWhiteKnight) - [mailto:vankata_petrovATabvDOTbg]
* [[CatalanTranslation|Catalan]] - maintainer: Jordà Polo (ettin) - [mailto:jordaATettinDOTorg]
* [[ChineseTranslation|Chinese]] - maintainer: CloudiDust - [mailto:cloudidustATgmailDOTcom]
* [[ChineseTaiwanTranslation|Chinese (Taiwan)]] - maintainer: 楊綮銘 (Taiwan) - [mailto:steven2880ATgmailDOTcom]
* [[CroatianTranslation|Croatian]] - maintainer: Ivica Đurenec (charlieh65) - [mailto:ivicaDOTdurenecATgmailDOTcom]
* [[CzechTranslation|Czech]] - maintainer: [[User:hrubymar10|Martin Hrubý (hrubymar10)]] - [mailto:hrubymar10ATgmailDOTcom]
* [[DanishTranslation|Danish]] maintainer: Joe Hansen (joedalton) - [mailto:joedalton2ATyahooDOTdk]
* [[DutchTranslation|Dutch]] - maintainer: Merijn de Vet (Ty Bonzer) - [mailto:merijndevetAThotmailDOTcom]
* [[EnglishGBTranslation|English (GB)]] - maintainer: Wedge009 [mailto:wedge009ATwedge009DOTnet]
* [[EnglishShawTranslation|English (Shaw)]] - maintainer: Arc Riley - [mailto:ArcRileyATubuntu.com]
* [[Esperanto_translation|Esperanto]] - maintainer: Luther Thompson - [mailto:lutherATlibremDOTone]
* [[EstonianTranslation|Estonian]] - maintainer: Kaido Kikkas (UncleOwl) - [mailto:kaidoDOTkikkasATkakupesaDOTnet]
* [[FilipinoTranslation|Filipino]] - maintainer: Karen Eso (keeve) - [mailto:eveUNDERSCOREesoATyahooDOTca]
* [[FinnishTranslation|Finnish]] - maintainer: Jarkko Patteri (Jarkko) - [mailto:jarkkopatteriATgmailDOTcom], Samu Voutilainen (Smar) - [mailto:samu.voutilainenATgmailDOTcom]
* [[FrenchTranslation|French]] - maintainer: Mathieu Guilbaud (Guim) - Please use the translation team mailing list [mailto:wesnothATmlDOTfreeDOTfr]
* [[GalicianTranslation|Galician]] - maintainer: Adrián Chaves Fernández (Gallaecio) - [mailto:adriyetichavesATgmailDOTcom] [http://trasno.net Proxecto Trasno]
* [[GermanTranslation|German]] - maintainer: Aaron Winter (Bitron)
* [[GreekTranslation|Greek]] - maintainer: Konstantinos Egarhos [mailto:konsnoslATgmailDOTcom]
* [[HebrewTranslation|Hebrew]] - maintainer: Oron Peled - [mailto:oronATactcomDOTcoDOTil]
* [[HungarianTranslation|Hungarian]] - maintainer: Széll András - [mailto:szellDOTandrisATgmailDOTcom]
* [[IcelandicTranslation|Icelandic]] - maintainer: Gabríel A. Pétursson [mailto:gabrielpATsimnetDOTis]
* [[IndonesianTranslation|Indonesian]] - maintainer: Yuristyawan Pambudi Wicaksana [mailto:yuris_wicaksana@yahoo.com]
* [[IrishTranslation|Irish]] - maintainer: Carson "Mountain_King" [mailto:tree_ringsATrocketmailDOTcom]
* [[ItalianTranslation|Italian]] - maintainer: Antonio Rosella - [mailto:arosellaATyahooDOTcom]
* [[JapaneseTranslation|Japanese]] - maintainer: Hironori Fujimoto (RatArmy) [mailto:broadbarredfirefishATgmailDOTcom]
* [[KoreanTranslation|Korean]] - maintainer: mistzone - [mailto:drier22ATgmailDOTcom]
* [[LatinTranslation|Latin]] - maintainer: Michael Babich ([[User:Aethaeryn|Aethaeryn]])
* [[LatvianTranslation|Latvian]] - maintainer: Reinis Danne - [mailto:rei4danATgmailDOTcom]
* [[LithuanianTranslation|Lithuanian]] - maintainer: Andrius Štikonas - [mailto:stikonasATgmailDOTcom]
* [[MarathiTranslation|Marathi]] - maintainer: Sujit R Jadhav - [mailto:sujitrjadhavATgmailDOTcom]
* [[MacedonianTranslation|Macedonian]] - maintainer: Dimitar Ilccov (Mythological)
* [[NorwegianTranslation|Norwegian]] - maintainer: Gaute Jao (Gauteamus) - [mailto:gauteamusATgmailDOTcom]
* [[OldEnglishTranslation|Old English]] - maintainer: no one (contact Espreon via private message on the forums for information)
* [[PolishTranslation|Polish]] - maintainer: Paweł Jackowski (fatality), contact via translation thread
* [[PortugueseTranslation|Portuguese Brazilian]] - maintainer: Andrei Machado - [mailto:andreisp.machadoATyahooDOTcom]
* [[PortugueseContinentalTranslation|Portuguese (European)]] - maintainer: trewe [mailto:sjrs456ATyahooDOTfr]
* [[RACVTranslation|RACV]] - maintainer: Mario (Mavorte) - [mailto:mavorte1ATyahooDOTes]
* [[RomanianTranslation|Romanian]] - maintainer: Alexandru Szasz [mailto:alexxedATgmailDOTcom]
* [[RussianTranslation|Russian]] - maintainer: Aldarisvet [mailto:rassvetozaaarATgmailDOTcom]
* [[Scottish_Gaelic_Translation|Scottish Gaelic]] - maintainer: GunChleoc- [mailto:fiosAIGforamnagaidhligDOTnet]
* [[SerbianTranslation|Serbian]] - maintainer: Srećko Toroman (freecraft)- [mailto:sreckotoromanATgmailDOTcom]
* [[SlovakTranslation#Preklad|Slovak]] - maintainer: Aceman
* [[SlovenianTranslation|Slovenian]] - maintainer: Klemen Košir (nNa) - [mailto:klemen913ATgmailDOTcom]
* [[SpanishTranslation|Spanish]] - maintainer: Pepe - [mailto:donpepe1963ATgmailDOTcom])
* [[SwedishTranslation|Swedish]] - maintainer: Niklas Bolmdahl (dacovale) - [mailto:wesnothATniklasDOTbolmdahlDOTse]
* [[TurkishTranslation|Turkish]] - maintainer: Nilgün Belma Bugüner - [mailto:nilgunATbelgelerDOTorg]
* [[UkrainianTranslation|Ukrainian]] - maintainer: robson - [mailto:arobsonATyandexDOTru]
* [[VietnameseTranslation|Vietnamese]] - maintainer: Huynh Yen Loc (hhyloc) - [mailto:nightgaunt13ATgmailDOTcom]

== Mailing List ==

There now is a mailing list dedicated to translation matters. It is mainly intended to be used for informing translation maintainers about important changes, to announce string freezes and other special things. Everyone is free to subscribe to this list.

* [https://mailman.wesnoth.org/listinfo/i18n List information, including the subscription form]
* [https://mailman.wesnoth.org/pipermail/i18n/ List archives]

Please keep in mind that this list is not meant for discussing changes for one single translation but instead subjects which are relevant to all translations.

== See also ==

* [[WesnothTranslationsHowTo]]
* [[ImageLocalization]]
* [[GetText]]
* [http://gettext.wesnoth.org Translations statistics (stable)]
* [http://gettext.wesnoth.org/index.php?version=trunk&package=alloff Translations statistics (development)]
* [[WesCamp| Translating User made Campaigns (featuring WesCamp-i18n)]]
* [[SpellingMistakes]]
* [[CharactersStorys| Character descriptions for Translators (Spoiler Warning)]]
* [[TextdomainStatus]]

[[Category:Translations|*]]

DirectActionsWML

2019-05-29T20:18:12Z

Luther: /* [set_recruit] */ Delete where it says the default side is 1.

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

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

The following tags are actions:

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

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

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

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

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

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

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

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

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

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

=== [terrain] ===
Changes the terrain on the map.
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.
* '''layer''': (overlay|base|both, default=both) only change the specified layer.
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.

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

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

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

=== [unstore_unit] ===
Creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
* '''variable''': the name of the variable.
* '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit. This key has no effect if find_vacant=no (no check performed then). Before 1.9 this key is always "no".
* '''text''': (translatable) floating text to display above the unit, such as a damage amount
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
* '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.
* '''fire_event''': (boolean yes|no, default no) Whether any advance/post advance events shall be fired if an advancement takes place, no effect otherwise.
* '''animate''': (boolean yes|no, default yes) Whether "levelout" and "levelin" (or fade to white and back) animations shall be played if an advancement takes place, no effect otherwise.
* '''x''' ,'''y''': override unit location, "x,y=recall,recall" will put the unit on the unit's side's recall list.
Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit–and killed–in combat.) The details of the unusual behavior are subject to change between stable releases without warning.

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

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

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

=== [disallow_extra_recruit] ===
Prevents a leader from recruiting units it could previously recruit.
* '''extra_recruit''': the types of units that the side can no longer recruit.
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.

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

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

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

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

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

=== [disallow_end_turn] ===
Disallows human players to end their turn through the user interface. This action doesn't take any arguments.

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

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

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

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

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

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

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

Some some peorperties of the units are reset sometimes for exmapel when the unit advances or when [remove_object] is called. So it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit], this list of properties that are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit] is:
* '''side'''
* '''gender'''
* '''name'''
* '''canrecruit'''
* '''unrenamable'''
* '''extra_recruit'''
* '''[variables]'''
* '''facing'''
* '''goto_x, goto_y'''
* '''hitpoints'''
* '''experience'''
* '''moves'''
* '''[status]''' (not sure on this one)
* '''attacks_left'''
* '''role'''

=== [transform_unit] ===
Transforms every unit on the map matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points.
* [[StandardUnitFilter]]: do not use a [filter] tag.
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.

=== [petrify] ===

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

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

=== [object] ===
Gives some unit an object which modifies their stats in some way.
* '''id''': (Optional) allows the item to be removed later. By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores.
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
* '''duration''':
**if 'scenario', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
**if 'forever' or not set, effects never wear off.
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it is tried to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.
* '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.
* '''image''': the displayed image of the object.
* '''name''': (translatable) displayed as a caption of the image.

* '''description''': (translatable) displayed as a message of the image.
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.

=== [remove_object] ===

{{DevFeature1.13|6}}

Removes an object from matching units.

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

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

Note that remove_object worked the following way: Step1) remove thos objects from the unit wml, Step2) Rebuild the unit to make the changes effective. Step2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [modify_unit] to get a list of properties that can safely be changes via [modify_unit]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== [cancel_action] ===
Although Wesnoth 1.12 does not have this tag, it is the default behavior of {{tag|EventWML|enter_hex}}/{{tag|EventWML|leave_hex}} events in that version.

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

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

=== [heal_unit] ===
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed.
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to yes) for each of the units healed.
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. Can't set below 1 or above max_hitpoints. If "full", sets hitpoints to max_hitpoints. Before 1.9 the default is 0.
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable. Before 1.9 this is always "no".

=== [harm_unit] ===
Harms every unit matching the filter, for the specific damage amount.
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.
* '''amount''': the amount of damage that will be done (required).
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the "harm_amount" key.
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.

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

''Example:'' (caves in parts of a map)
[time_area]
x=1-2,4-5
y=1-2,1-2
{UNDERGROUND}
[/time_area]

=== [remove_time_area] ===

{{DevFeature1.13|2}}

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

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

=== [replace_map] ===

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

=== [replace_schedule] ===
Replace the time of day schedule of the entire scenario.
* [[TimeWML]]: the new schedule.
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.

=== [tunnel] ===

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

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

* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
* '''id''': (optional) identifier for the tunnel, to allow removing.
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction.
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.

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

=== [do_command] ===

{{DevFeature1.13|0}}

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

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

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

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

This command should always be replay safe.

=== [put_to_recall_list] ===

{{DevFeature1.13|0}}

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

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

== See Also ==

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

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

LuaWML/Units

2012-05-06T02:56:32Z

Luther: hitpoints is read/write

This page describes the [[LuaWML]] functions for handling units.

A unit is a proxy table with the following fields:
* '''x''', '''y''': integers (read only, read/write if the unit is not on the map)
* '''side''': integer (read/write)
* '''id''': string (read only)
* '''type''': string (read only)
* '''name''': translatable string (read only)
* '''max_hitpoints''', '''experience''', '''max_experience''', '''max_moves''': integers (read only)
* '''max_attacks''': integer (read only)
* '''attacks_left''': integer (read/write) Setting below 0 is limited to 0.
* '''extra_recruit''': table (read/write)
* '''advances_to''': table (read/write)
* '''hitpoints''', '''experience''': integer (read/write)
* '''moves''': integer (read/write)
* '''resting''': boolean (read/write)
* '''hidden''': boolean (read/write)
* '''petrified''', '''canrecruit''': booleans (read only)
* '''role''', '''facing''': strings (read/write)
* '''status''': proxy associative table (read only, read/write fields)
* '''image_mods''': string (read only)
* '''variables''': proxy associative table (read only, read/write fields, including ''variables.__cfg''), only toplevel named fields are proxied
* '''valid''': string or nil (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit"'''.

A unit can be either visible on the map ([[#wesnoth.get_units]], [[#wesnoth.put_unit]]), or on a recall list ([[#wesnoth.get_recall_units]], [[#wesnoth.put_recall_unit]]), or private to the Lua code ([[#wesnoth.create_unit]], [[#wesnoth.copy_unit]], [[#wesnoth.extract_unit]]). The Lua code has complete control over the private units; they will not be modified unless accessed through the proxy unit. Units on the map and on the recall lists, however, can be modified by the user, the engine, WML, independently of the Lua code. In particular, if a unit is killed, any further use of the proxy unit will cause an error. For units on the map, the proxy unit is valid as long as there is a unit on the map that has the same "underlying_id" WML field as the original one. The behavior is similar for units on the recall lists. The ''valid'' field reflects the unit availability by returning '''"map"''', '''"recall"''', '''"private"''', or ''nil''. The latter value is used for units that were removed (e.g. killed). In that case, the ''valid'' field is the only one that can be read without causing an error.

The term "proxy", here in particular "proxy unit", means that the variable retrieved in the lua code (with get_units for example) is an accessor (reference) to the C++ object which represents that unit. This is very different from unit variables obtained by [store_unit] in wml. The fields marked as "writable" above can be modified without the need to use put_unit afterwards. This same reason explains that modifications to the unit from outside the lua code (like [kill] invalidating the proxy unit) have immediate effect on the lua code's proxy unit variable (with the exception of private proxy units).

==== wesnoth.get_units ====

Returns an array of all the units on the map matching the WML filter passed as the first argument. See [[StandardUnitFilter]] for details about filters.

local leaders_on_side_two = get_units { side = 2, canrecruit = true }
local name_of_leader = leaders_on_side_two[1].name

==== wesnoth.get_unit ====

Returns the unit at the given location or with the given underlying ID.

local args = ...
local unit = wesnoth.get_unit(args.x1, args.y1)

==== wesnoth.match_unit ====

Returns true if the given unit matches the WML filter passed as the second argument.

assert(unit.canrecruit == wesnoth.match_unit(unit, { canrecruit = true }))

==== wesnoth.put_unit ====

Places a unit on the map. This unit is described either by a WML table or by a proxy unit. Coordinates can be passed as the first two arguments, otherwise the table is expected to have two fields '''x''' and '''y''', which indicate where the unit will be placed. If the function is called with coordinates only, the unit on the map at the given coordinates is removed instead.

-- create a unit with random traits, then erase it
wesnoth.put_unit(17, 42, { type = "Elvish Lady" })
wesnoth.put_unit(17, 42)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on a recall list, it no longer is; and if the unit was on the map, it has been moved to the new location. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on the map.

-- move the leader back to the top-left corner
wesnoth.put_unit(1, 1, wesnoth.get_units({ canrecruit = true })[1])

==== wesnoth.get_recall_units ====

Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.

==== wesnoth.put_recall_unit ====

Places a unit on a recall list. This unit is described either by a WML table or by a proxy unit. The side of the recall list is given by the second argument, or by the side of the unit if missing.

-- put the unit at location 17,42 on the recall list for side 2
wesnoth.put_recall_unit(wesnoth.get_units({ x= 17, y = 42 })[1], 2)

When the argument is a proxy unit, no duplicate is created. In particular, if the unit was private or on the map, it no longer is. Note: passing a WML table is just a shortcut for calling [[#wesnoth.create_unit]] and then putting the resulting unit on a recall list.

==== wesnoth.create_unit ====

Creates a private unit from a WML table.

local u = wesnoth.create_unit { type = "White Mage", gender = "female" }

==== wesnoth.copy_unit ====

Creates a private unit from another unit.

-- extract a unit from the map
local u = wesnoth.copy_unit(wesnoth.get_units({ type = "Thug" })[1])
wesnoth.put_unit(u.x, u.y)
-- u is still valid at this point

==== wesnoth.extract_unit ====

Removes a unit from the map or from a recall list and makes it private.

-- remove all the units from the recall list of side 1 and put them in a WML container
local l = {}
for i,u in ipairs(wesnoth.get_recall_units { side = 1 }) do
wesnoth.extract_unit(u)
table.insert(l, u.__cfg)
end
helper.set_variable_array("player_recall_list", l)

Note: if the unit is on the map, it is just a shortcut for calling [[#wesnoth.copy_unit]] and then [[#wesnoth.put_unit]] without a unit. It is, however, the only way for removing a unit from a recall list without putting it on the map.

==== wesnoth.add_modification ====

Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (either trait, object, or advance). The option "advance" applies effects as if the unit would advance (e.g. AMLA effects). The third argument is a WML table describing the effect, so mostly containing '''[effect]''' children. See [[EffectWML]] for details about effects.

local u = wesnoth.get_units { canrecruit = true }[1]
wesnoth.add_modification(u, "object", { { "effect", { apply_to = "image_mod", replace = "RC(red>blue)" } } })

==== wesnoth.unit_resistance ====

Returns the resistance of a unit against an attack type. (Note: it is a WML resistance. So the higher it is, the weaker the unit is.) The third argument indicates whether the unit is the attacker. Last arguments are the coordinates of an optional map location (for the purpose of taking abilities into account).

local fire_resistance = 100 - wesnoth.unit_resistance(u, "fire")

==== wesnoth.unit_defense ====

Returns the defense of a unit on a particular terrain. (Note: it is a WML defense. So the higher it is, the weaker the unit is.)

local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")

==== wesnoth.unit_movement_cost ====

Returns the movement cost of a unit on a particular terrain.

local move_cost = wesnoth.unit_movement_cost(u, "Gt")

==== wesnoth.unit_ability ====

Returns true if the unit is currently under effect by an ability with this given TAG NAME. This means that the ability could be owned by the unit itself, or by an adjacent unit.

function has_teleport(u)
return wesnoth.unit_ability(u, "teleport")
end

==== wesnoth.get_unit_type_ids ====
{{DevFeature1.11}}: This function is deprecated, use wesnoth.unit_types.

==== wesnoth.get_unit_type ====
{{DevFeature1.11}}: This function is deprecated, use wesnoth.unit_types instead.

==== wesnoth.unit_types ====

This is not a function but a table indexed by unit type ids. Its elements are proxy tables with these fields:

* '''id''': string
* '''name''': translatable string (read only)
* '''max_moves''', '''max_experience''', '''max_hitpoints''', '''level''', '''cost''': integers (read only)
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"unit type"'''.

local lich_cost = wesnoth.unit_types["Ancient Lich"].cost

==== wesnoth.races ====

This is not a function but a table indexed by race ids. Its elements are proxy tables for all races the engine knows about.
known fields of each element:
* '''id''': string
* '''description''', '''name''', '''plural_name''' (translatable strings)
* '''num_traits''' (integer)
* '''ignore_global_traits''' (boolean)
* '''undead_variation''' (string)
(all read only)
* '''__cfg''': WML table (dump)

wesnoth.message(tostring(wesnoth.races["lizard"].name))

==== wesnoth.get_traits ====

Returns a table with named fields (trait id strings) holding the wml tables defining the traits. arguments: none. All global traits the engine knows about, race-specific traits are not included.
Known fields and subtags of each element are the ones which were given in the wml definition of the [[SingleUnitWML|trait]].
wesnoth.message(tostring(wesnoth.get_traits().strong.male_name))

==== wesnoth.simulate_combat ====

Computes the hitpoint distribution and status chance after a combat between two units. Optional integers can be passed to select a particular weapon, otherwise the "best" one is selected. The first unit is the attacker; it does not have to be on the map, though its location should be meaningful. The second unit is the defender; it has to be on the map.

When giving the attack, the parameter is the attack id (integer) and not an element from the table returned by helper.child_range(att, "attack").

local function display_stats(n, t)
wesnoth.message(string.format(
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))
end
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def)
display_stats("attacker", att_stats)
display_stats("defender", def_stats)

==== wesnoth.transform_unit ====

Changes the type of a unit and adjust attributes accordingly. Note that hitpoints might be modified accordingly to the unit type.

local ev = wesnoth.current.event_context
local u = wesnoth.get_units{x=ev.x1, y=ev.y1}[1]
local old_hp = u.hitpoints
wesnoth.transform_unit(u, "Skeleton")
u.hitpoints = old_hp
u.status.poisoned = false

[[Category: Lua Reference]]

LuaWML/Misc

2012-03-17T01:05:03Z

Luther: /* wesnoth.synchronize_choice */ Reformatted the code to be more readable

This page describes miscellaneous [[LuaWML]] objects and helpers.

==== wesnoth.game_config ====

Contrarily to the other values of the ''wesnoth'' table, ''game_config'' is simply a proxy table. Its fields offer an interface to the global settings of Wesnoth:

* '''version''': string (read only)
* '''base_income''': integer (read/write)
* '''village_income''': integer (read/write)
* '''poison_amount''': integer (read/write)
* '''rest_heal_amount''': integer (read/write)
* '''recall_cost''': integer (read/write)
* '''kill_experience''': integer (read/write)
* '''debug''': boolean (read only)
* '''mp_debug''': boolean (read only) {{DevFeature1.11}}

-- Poison a bit weak? Let's boost it!
wesnoth.game_config.poison_amount = 15

==== wesnoth.current ====

As with ''game_config'', ''current'' is a proxy table. Its fields are getter for game-related properties:

* '''side''': integer (read only)
* '''turn''': integer (read only)
* '''event_context''': WML table with attributes ''name'', ''x1'', ''y1'', ''x2'', ''y2'', and children ''weapon'', ''second_weapon'', describing the trigger for the current event.

wesnoth.message(string.format("Turn %d, side %d is playing.", wesnoth.current.turn, wesnoth.current.side))

==== wesnoth.synchronize_choice ====

Recovers a WML table that was computed on one client only or was stored in a replay. The actual computation is performed by the function passed as the first argument, assuming that the client is the side currently playing. For all the other clients, the function will not be called. An optional second function can be passed; if present, it will be used instead of the first one when the client happens to be an AI (hence not enable to interact with a user interface).

local result = wesnoth.synchronize_choice(
function()
-- Called only on the client handling the current side, if it is a human.
local choice = 0
wesnoth.show_dialog(
some_dialog_cfg, nil,
function()
choice = wesnoth.get_dialog_value "some_list"
end)
return { value = choice }
end,
function()
-- Called only on the client handling the current side, if it is an AI.
return { value = math.random(some_list_size) }
end)
wesnoth.message(string.format("Selected item: %d", result.value))

==== wesnoth.get_image_size ====

Returns the width and height of an image.

local w, h = wesnoth.get_image_size "units/transport/galleon.png"

==== wesnoth.compare_versions ====

Takes two versions strings and an operator, returns whether the comparison yields true.
Follows the same rules like the #ifver preprocessor statement.

local function version_is_sufficient(required)
if not wesnoth.compare_versions then return false end
return wesnoth.compare_versions(wesnoth.game_config.version, ">=", required)
end
local required = "1.9.6+svn"
if not version_is_sufficient(required) then wesnoth.message(string.format(
"Your BfW version is insufficient, please get BfW %s or greater!", required)) end

==== wesnoth.debug ====

Takes a userdata with metatable wml object or a wml table and dumps its content into a pretty string.
wesnoth.set_variable("number", 100)
local vconfig = wesnoth.tovconfig({ key = "$number", another_key = true,
{"a_subtag", { a_key_in_the_subtag = "foo" }}
})
wesnoth.message(wesnoth.debug(vconfig))
wesnoth.message(wesnoth.debug(vconfig.__literal))

==== helper.set_wml_tag_metatable ====

Sets the metable of a table so that it can be used to create subtags with less brackets. Returns the table. The fields of the table are simple wrappers around table constructors.

T = helper.set_wml_tag_metatable {}
W.event { name = "new turn", T.message { speaker = "narrator", message = "?" } }

==== helper.modify_unit ====

Modifies all the units satisfying the given filter (argument 1) with some WML attributes/objects (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MODIFY_UNIT] macro.

helper.modify_unit({ id="Delfador" }, { moves=0 })

==== helper.move_unit_fake ====

Fakes the move of a unit satisfying the given filter (argument 1) to the given position (argument 2). This is a Lua implementation of the [http://www.wesnoth.org/macro-reference.xhtml MOVE_UNIT] macro.

helper.move_unit_fake({ id="Delfador" }, 14, 8)

==== helper.rand ====

(A shortcut to set_variable's rand= since math.rand is an OOS magnet and therefore disabled.) Pass a string like you would to set_variable's rand=.

create a random unit at (1, 1) on side=1 :
wesnoth.put_unit(1, 1, { type = helper.rand("Dwarvish Fighter,Dwarvish Thunderer,Dwarvish Scout") })

[[Category: Lua Reference]]

PreprocessorRef

2011-03-01T16:15:21Z

Luther: /* The WML preprocessor */ 'non-recursively' makes it sound like it does not resolve any further filenames. Refer to subdirectories to be more clear.

{{WML Tags}}
== The WML preprocessor ==

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

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

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

The following directives are used to create and use ''macros'',
i.e. shortcuts which reduce repetition of information.
See [[UtilWML]], [[UsefulWMLFragments]] for examples and [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the predefined core macros.
* '''#define ''symbol'' [''parameters''] ''newline'' ''substitution'' #enddef''' all subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by ''substitution'' with all occurences of any parameter {''parameter''} within ''substitution'' replaced by the parameter's corresponding value in ''arguments''. For example, the UNIT macro used below would be defined:

#define UNIT TYPE X Y## the ordering is important here;
## since WML does not distinguish
## data into different types, only
## the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE}## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
(See [[SingleUnitWML]] for information on creating units using WML.)
* '''{''symbol'' [''arguments'']}''' if ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' is defined as, using ''arguments'' as parameters. You can create multiple word arguments by using parentheses to restrain the argument. For example, while '''{UNIT Wolf Rider 18 24}''' will attempt to create a "Wolf" at (Rider,18), causing Wesnoth to crash, the macro '''{UNIT (Wolf Rider) 18 24}''' will create a "Wolf Rider" at (18,24) as it should. ('''UNIT''' is defined above). See the ''#define'' preprocessor instruction above for information on defining symbols, including symbols with arguments. Several symbols are defined in the normal game code; for reference they are listed in [[UtilWML]].

Note: Using the name-string of an existing macro as the name-string of a macro argument will always overwrite the original definition of the macro, e.g.:
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef

Unlike the other preprocessor directives, #ifdef and #ifndef are not
mere conveniences.
They are necessary to distinguish between different modes of play.
* '''#ifdef ''symbol'' ''substitution-if-stored'' [#else ''substitution-if-not-stored''] #endif''' If ''symbol'' has been stored, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available. ''symbol'' can take the following values:
** a campaign difficulty level. Usually '''EASY''', '''NORMAL''', or '''HARD''', it is decided by the key ''difficulties'' (see [[CampaignWML]]).
** a campaign ID. Each campaign stores a preprocessor ID. See ''define'', [[CampaignWML]].
** '''MULTIPLAYER''' is stored when the player is playing or setting up a multiplayer game (i.e. a game with '''scenario_type=multiplayer''').
** '''DEBUG_MODE''' is stored when the player has launched wesnoth in debug mode (i.e. with '''-d''')
** '''TUTORIAL''' is stored when the player is playing the tutorial.
** '''APPLE''' is stored if the computer Wesnoth is being run on is an Apple. (this one is only available to the configuration of the game)
* '''#ifndef''' behaves exactly like '''#ifdef''', except that it inverts the test sense; guarded text is included only if ''symbol'' has not been stored.
''#undef'' can be useful too if ''#ifdef'' is not enough.
* '''#undef ''symbol'' ''' erases ''symbol''
* '''#ifhave''' {{DevFeature1.9}} checks for the existence of a file. Uses the same relative paths as include directives (see below). Example: '''#ifhave ~add-ons/MyAddon/_main.cfg''' note: For a multiplayer game, the #ifhave directive works only for the host, not for the other clients.
* '''#ifnhave''' {{DevFeature1.9}} is the inverted version of '''#ifhave'''.

These directives expand a file by including other files, ''filename'' may not contain '..' or the directive will be skipped:
* '''{''filename''}''' if ''filename'' isn't a predefined symbol (see above), Wesnoth will assume it's a path to a file in the main '''data/''' subdirectory of Wesnoth and include the file it points to here "as is". Forward slashes('''/''') should be used to separate directories from their elements, even if your platform uses a different symbol such as colon (''':''') or backslash ('''\''').
* '''{~''filename''}''' similar to above, but the preprocessor assumes that the filename is relative to '''data/''' subdirectory of the user data directory. The ''user data directory'' varies depending on platform. See [[EditingWesnoth#Where_is_my_user_data_directory.3F|Where_is_my_user_data_directory?]]

* '''{./''filename''}''' is similar to the '''{''filename''}''' directive, but is assumed to be relative to the directory which contains the file in which this appears. For example, if used in game.cfg, it is equivalent to '''{''filename''}'''.
* If ''filename'' points to a directory, the preprocessor will include all files in the directory ''filename'', except subdirectories, in alphabetical order. Some files in such directories are handled specially.

If there is a file named ''dir/_main.cfg'' in a directory referenced as '''{''dir''}''', only that ''_main.cfg'' file is processed; it may include other files in itself, of course . This feature is useful for creating WML directories that are self-contained WML packages with their own initializations (like campaigns). This can replace the older convention of having a ''dir.cfg'' at the same level as ''dir'' which does '''{''dir''}''' somewhere in itself.

If there are files named ''dir/*/_main.cfg'' in a directory referenced as '''{''dir''}''', where * is any subdirectories ''dir'', then they all are processed (except if there is also a file named ''dir/_main.cfg''). This means that if you have a layout like this:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Then '''{dir}''' will process (in alphabetical order): dir/a/_main.cfg, dir/b/main.cfg, dir/other.cfg.

If there is a file named ''dir/_final.cfg'' in a directory referenced as '''{''dir''}''' (and no ''main.cfg'', so that all files in the directory are processed normally) the ''_final.cfg'' is guaranteed to be processed ''after'' all other files in the directory.

If there is a file named ''dir/_initial.cfg'' in a directory referenced as '''{''dir''}''' (and no ''main.cfg'', so that all files in the directory are processed normally) the ''_initial.cfg'' is guaranteed to be processed ''before'' all other files in the directory.

Note that the parser was changed various times, so don't expect older Wesnoth version to behave exactly the same.

{{DevFeature1.9}} Including non-existent file is now a fatal error and halts the preprocessing. Use #ifhave to test for the existence of files that aren't a part of your own add-on.

== The preprocessor command line ==
{{DevFeature1.9}}

As of wesnoth 1.9, there is a new command line available:
--preprocess[=define1,define2,...] <file/folder> <target directory>
or the short form:
-p[=define1,define2,...] <file/folder> <target directory>

The define1,define2,... is a list of defines, to be added ''before'' anything is preprocessed.

The preprocess command will '''preprocess first''' the common config files in ''data/core'', and afterwards, the specified ones. You can specifiy a single file to be preprocesses (if you want to preprocess multiple separate files, you have to invoke the command separately), or an entire folder (this will be preprocessed on the known preprocessor rules).

The resulted preprocessed files will be written in the target directory. There will be 2 types of files: the .cfg files and .plain files (this contain the line symbols and textdomain changes)

If <file/folder> and <target directory> are not in ''absolute path'' form, they will be treated like relative to the wesnoth's executable path.

Some examples:
-p ~/wesnoth/data/campaigns/tutorial ~/result
will preprocess entire tutorial folder, and write the resulted files in the ~/result folder
-p=MULTIPLAYER data/campaigns/my_campaign/some_scenario.cfg data/result
will add the ''MULTIPLAYER'' define in defines list and then preprocess the scenario config file
-p=SINGLEPLAYER,HARD ~/wesnoth/data/campaigns/my_campaign ~/result
will add the ''SINGLEPLAYER'' and ''HARD'' defines before preprocessing the files.

Note! As you saw in the examples, the '=' character is mandatory if you want to specify any auxiliar defines

If you want a more detailed log, you can simply add the command: "--log-debug=all" or "--log-info=all" before the preprocessing command, so you will see how things are parsed,etc.

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

[[Category: WML Reference]]

LuaWML/Location set

2011-01-20T00:47:26Z

Luther: Clarified intro after seeing the source code

{{DevFeature1.9}}

This page describes the [[LuaWML]] class for handling location sets and location maps. Objects of this class store a set of locations, with some data (boolean ''true'', by default) attached to each of them. It is not possible to associate ''nil'' or ''false'' to a location.

There is one main constructor [[#location_set.create]] and two auxiliary helper constructors [[#location_set.of_pairs]] and [[#location_set.of_wml_var]]. They are provided by the ''lua/location_set.lua'' file. All the other functions are methods from the class and they are available through the ':' operator only.

local location_set = wesnoth.require "lua/location_set.lua"
local a_set = location_set.create()
a_set:insert(17, 42, "something")
assert(a_set:get(17, 42) == "something")
local b_set = location_set.of_pairs(wesnoth.get_locations { { "filter_adjacent", { x=17, y=42 } } })
a_set:union(b_set)
a_set:to_wml_var "locations"

==== location_set.create ====

Returns an empty location set.

==== location_set.of_pairs ====

Returns a fresh location set filled by [[#location_set:of_pairs]].

==== location_set.of_wml_var ====

Returns a fresh location set filled by [[#location_set:of_wml_var]].

==== location_set:empty ====

Returns ''true'' if the set is empty.

local some_set = location_set.create()
assert(some_set:empty())

==== location_set:size ====

Returns the number of locations in the set.

some_set:insert(17, 42)
assert(some_set:size() == 1)

==== location_set:clear ====

Empties the content of the set.

some_set:clear()
assert(not some_set:get(17, 42))

==== location_set:get ====

Returns the data associated to the given location or ''nil'' if the location is not in the set.

some_set:insert(17, 42, "something")
assert(some_set:get(17, 42) == "something")

==== location_set:insert ====

Associates some data to the given location, or ''true'' if there is no data. Previous associated data is lost.

some_set:insert(17, 42)
assert(some_set:get(17, 42))

==== location_set:remove ====

Removes the given location from the set.

some_set:remove(17, 42)

==== location_set:of_pairs ====

Inserts all the locations from an array containing pairs (arrays with two elements). Previous content of the set is kept, unless overwritten by the content of the array.

some_set:of_pairs(wesnoth.get_locations { { "filter_adjacent", { x=17, y=42 } } })

==== location_set:of_wml_var ====

Inserts all the locations from a WML array. If a container has more than just ''x'' and ''y'' attributes, the remaining attributes and children are associated to the location as a WML table. Previous content of the set is kept, unless overwritten by the content of the WML array.

wesnoth.wml_actions.store_locations { variable="target", { "filter_adjacent", { x=17, y=42 } } }
some_set:of_wml_var "target"

==== location_set:to_pairs ====

Returns an array of pairs containing the locations of the set. Associated data are ignored. The order of the locations is not deterministic. If the order actually matters, the [[#location_set:to_stable_pairs]] method should be used instead.

local size = #(some_set:to_pairs())

==== location_set:to_stable_pairs ====

Returns an array of pairs containing the locations of the set. Contrarily to [[#location_set:to_pairs]], the locations are guaranteed to be sorted and hence synchronized over networks and replays.

==== location_set:to_wml_var ====

Fills a WML array with the content of the set. The order of the elements is safe.

local some_set = location_set.of_pairs(wesnoth.get_locations { { "filter_adjacent", { x=17, y=42 } } })
some_set:to_wml_var "locations"

==== location_set:union ====

Inserts the locations from the other set, possibly overwriting the associated of data the locations already present.

a_set:insert(17, 42, "nothing")
b_set:insert(17, 42, "something")
a_set:union(b_set)
assert(a_set:get(17, 42) == "something")

==== location_set:inter ====

Deletes the locations that are not in the other set. Associated data is kept intact if not removed.

a_set:insert(17, 42, "nothing")
b_set:insert(17, 42, "something")
a_set:inter(b_set)
assert(a_set:get(17, 42) == "nothing")

==== location_set:iter ====

Calls the given function on all the locations of the set. Iteration order is not deterministic. If the order actually matters, the [[#location_set:stable_iter]] method should be used instead.

some_set:iter(function(x, y, data) wesnoth.message(string.format("[%d,%d] = %s", x, y, type(data))) end)

==== location_set:stable_iter ====

Calls the given function on all the locations of the set. Contrarily to [[#location_set:iter]], the iteration is deterministic and hence safe for networks and replays.

some_set:stable_iter(function(x, y, data) wesnoth.message(string.format("[%d,%d] = %s", x, y, type(data))) end)

==== location_set:filter ====

Returns a new set containing all the locations of the set for which the given function returns true.

local new_set = old_set:filter(function(x, y, v)
local d = helper.distance_between(a, b, x, y)
return d <= 5 and v == "not found"
end)
wesnoth.message(string.format("%d traps in the neighborhood of (%d,%d)", new_set:size(), a, b))

==== location_set:union_merge ====

Calls the given function for all the locations of the other set and uses the returned values to fill the set. Note: the merge order is not stable.

-- merge the elements of s2 into s1 but preserve the old data of s1
function set_union(s1, s2)
s1:union_merge(s2, function(x, y, v1, v2) return v1 or v2 end)
end

-- remove from s1 the elements of s2
function set_difference(s1, s2)
-- the nested function is called s2:size() times; note: v2 is never nil
s1:union_merge(s2, function(x, y, v1, v2) return nil end)
end

==== location_set:inter_merge ====

Calls the given function for all the locations of the set and uses the returned values to replace it. Note: the merge order is not stable.

-- compute the intersection of s1 and s2 and put it into s1, but overwrite the data of s1
function set_inter(s1, s2)
s1:inter_merge(s2, function(x, y, v1, v2) return v2 or v1 end)
end

-- remove from s1 the elements of s2
function set_difference(s1, s2)
-- the nested function is called s1:size() times; note: v1 is never nil
s1:inter_merge(s2, function(x, y, v1, v2) return not v2 end)
end

Distributing content

2011-01-12T20:33:12Z

Luther: /* The Add-on Server */ Suggest MyCampaign.pbl as a filename

== The Forum ==

The [http://www.wesnoth.org/forum/ BFW forum] is a good way to distribute small creations, like single multiplayer maps. Larger creations, like multiplayer eras or campaigns, should be compressed before uploading them. Note that you may encounter a size limit on attachments.

Also, there is a [http://www.wesnoth.org/forum/viewtopic.php?t=2014 legal announcement] that you should read before distributing anything on the forum. Basically, by posting you say that you own the license to what you are posting, and that you are licensing it under the [http://www.gnu.org/copyleft/gpl.html General Public License].

== The Add-on Server ==

The add-on server is the preferred way to distribute your creations, but it is more suited for larger projects. It currently lacks advanced organization features such as reviewing (although it does have a filter text box), so adding hundreds of little things makes it harder to find anything. Basically, the server should not be used to post single maps, units, songs, or artwork, but map packs, campaigns, entire eras, music packs, and unit packs are fine.

Once you are ready to publish, here is how you access the add-on server:
# Open Wesnoth
# Select "Add-ons" from the main menu
# Connect to the default ''add-ons.wesnoth.org'' add-on server
# Select "Publish add-on: ''Your Add-on Name''" (the last entry in the list of add-ons)

Anything you distribute on the server will be uploaded from and downloaded to the ''[[EditingWesnoth#Where_is_my_user_data_directory.3F|userdata]]''/data/add-ons directory regardless of what it is (units, maps, campaign, etc). For this reason, you need three things in the add-ons directory to distribute via the server:
# A folder, for example MyCampaign
# A .cfg file MyCampaign/_main.cfg
# A .pbl file MyCampaign.pbl ''or'' MyCampaign/_server.pbl
Note that only the contents of your add-on directory (in this case, MyCampaign) will get uploaded, nothing else, so you need to have all the necessary files inside that directory.

The following files and directories will not be uploaded: those that begin with '.' and those that end in '~'. Also, the GNU GPL version 2 will be added in the file COPYING.txt.

==== General Reading ====
* [[BuildingCampaignsThePBLFile|General information about the .pbl file]] - It has a campaign flavor, but it is adaptable to any content
* [[PblWML|Syntax reference for the .pbl file]]

==== Content-specific instructions ====
* Maps - see [[BuildingMaps|Building Maps]]
** [[BuildingMapsDistribution|About distributing map-packs]]
* Campaign - see [[BuildingCampaigns|Building Campaigns]]
** [[BuildingCampaignsDistribution|About distributing campaigns]]
* Multiplayer era - see [[BuildingFactions#Adding_a_whole_new_era_with_its_own_factions_-_modular|Building MP Era]]
* Unit pack - see [[BuildingUnits#Distributing_your_unit|Building Units]]

==== License ====
Whenever you upload or update your content pack, you will have to say "OK" to this statement: "All add-ons uploaded to this server must be licensed under the terms of the GNU General Public License (GPL). By uploading content to this server, you certify that you have the right to place the content under the conditions of the GPL, and choose to do so."

== See Also ==

* [[Create]]
* [[BuildingMapsDistribution]]
* [[BuildingCampaignsDistribution]]
* [[BuildingCampaignsThePBLFile]]
* [[PblWML]]
* [[IGNFileFormat]]
* [[Wesnoth:Copyrights]]

[[Category:Create]]

CommandMode

2010-09-26T11:11:14Z

Luther: /* Command Mode */ :lua is a debug command

== Command Mode ==

You can access command mode by typing ' ''':''' ' in a single player or multiplayer scenario.
(Prior to version 1.1.1, you need to type shift - semicolon( ''';''' ). However this isn't possible on all keyboards; if your keyboard doesn't have ':' above ';' you can change the hotkey in the Preferences, or you could edit '''game.cfg''' by hand.')

Note: you can highlight, copy, and paste text in debug mode.

Several vi-like commands are available in command mode. They are defined in ''menu_events.cpp''. In the 1.5 branch, there is a ''':help''' command that lists all available commands, and ''':help ''foo''''' displays more info about command ''foo''. This is more reliable than the list that follows here:

;<nowiki>:q or :q!</nowiki>
:quit the scenario (without prompting)
;<nowiki>:w</nowiki>
:save the game (without prompting)
;<nowiki>:wq</nowiki>
:save the game and quit the scenario (without prompting)
;<nowiki>:refresh</nowiki>
:redraw the screen
;<nowiki>:droid</nowiki> [''side''] [on|off]
:toggle player on ''side'' between human and AI player. The player/client who controls that side needs to issue this command. If you don't provide ''side'', the current side is assumed.
;<nowiki>:muteall</nowiki>
:toggles muting/silencing of all observers on/off
;<nowiki>:mute</nowiki> [''username'']
:mute a specific observer. If no ''username'' is supplied the muted usernames are displayed.
;<nowiki>:unmute</nowiki> [''username'']
:unmute a specific observer. If no ''username'' is given everyone is unmuted. (Doesn't effect the muteall setting.)
;<nowiki>:kick</nowiki> ''username''
:kick a user in multiplayer. They will be able to rejoin the game. Generally a friendly way to remove someone who is having connection or other difficulties.
;<nowiki>:ban</nowiki> ''username''
:kick and ban a user in multiplayer by the IP address used by that ''username''. Can be used on users not in the game but on the server. (Of course they won't be kicked then.)
;<nowiki>:unban</nowiki> ''username''
:unban a user by the IP address used by that ''username''. Can be used on users not in the game but on the server.
;<nowiki>:control</nowiki> ''side'' ''username''
:change the controller for ''side'' (write here the number of the side, the side must be controlled by you) to ''username'' (write here the nick of the player or observer)
;<nowiki>:clear</nowiki>
:clear chat messages
;<nowiki>:debug</nowiki>
:switch debug mode on (does not work in multiplayer). Debug mode is turned off by quitting the game or using the :nodebug command.
;<nowiki>:theme</nowiki>
:bring up theme selection menu
;<nowiki>:nosaves</nowiki>
:turns off the autosave function
;<nowiki>:show_coordinates (or :sc)</nowiki>
:Overlay x,y coordinates on map tiles. 1.5.5 onwards
;<nowiki>:show_terrain_codes (or :tc)</nowiki>
:Overlay terrain codes on visible map tiles. 1.5.5 onwards
;<nowiki>:discover</nowiki>
:Show all hidden unit descriptions in the in-game Help. 1.7.0 onwards

===Extra Debugging Commands===
[[DebugMode]] enables additional commands in command mode:

;<nowiki>:lua</nowiki> ''statement''
:{{DevFeature}} execute a Lua statement
;<nowiki>:nodebug</nowiki>
:disables debug-mode commands
;<nowiki>:n</nowiki>
:skip to next scenario by triggering a win event
;<nowiki>:shroud</nowiki>
:toggles shroud on/off (implemented since 1.3.10)
;<nowiki>:fog</nowiki>
:toggles fog on/off (implemented since 1.3.10)
;<nowiki>:gold</nowiki> ''amount''
:add ''amount'' gold to the current player's side
;<nowiki>:create</nowiki> ''unit_type''
:create a unit of type specified at last selected hex
;<nowiki>:unit hitpoints=</nowiki>''amount''
:edit units hitpoints
;<nowiki>:unit experience=</nowiki>''amount''
:edit units experience
;<nowiki>:unit</nowiki> ''attribute=value''
:when a unit is selected, this will set the unit's ''attribute'' to ''value''. See [[SingleUnitWML]] for possible values.
;<nowiki>:unit</nowiki> ''advances=N''
:{{DevFeature}} when a unit is selected, this will advance (level up) the unit N times.
;<nowiki>:set_var</nowiki> ''attribute=value''
:this will set a WML variable to a given value
;<nowiki>:show_var</nowiki> ''attribute''
:this will display a popup with the content of the variable
;<nowiki>:throw/fire</nowiki> ''event_name''
:throw an event by name, like ''time over'' or ''enemies defeated''. (Only available in 1.3.5 or later.)
;<nowiki>:inspect</nowiki>
:{{DevFeature}} show a gamestate inspector dialog which allows to see variable info, team info, ai info.
;<nowiki>:cl</nowiki>
:pops up a menu that allows you to move directly to a specified scenario.
;<nowiki>:turn</nowiki> [''number'']
:{{DevFeature1.9}} change the current turn to the specified number. If no number is provided, the turn number is increased by one.
;<nowiki>:turn_limit</nowiki> [''number'']
:{{DevFeature1.9}} change the turn limit for the current scenario to the specified number. If no number is provided, or it is -1, the turn limit is switched off.
;<nowiki>:version</nowiki>
:Report version and SVN revision level.

== See Also ==

* [[DebugMode]]
* [[DeveloperResources]]

[[Category:Playing Wesnoth]]
[[Category:Development]]

WesnothRepository

2010-07-26T05:58:29Z

Luther: 1.6 -> 1.8

{{Compiling Wesnoth}}
== SVN ==

Wesnoth development currently uses the [[SVN|Subversion]] software tool to keep developers in sync with each other. See the [http://svnbook.org SVN book] for more on how to use Subversion.

== Browse the code ==

There are currently two main streams of development: trunk (1.9.x) and stable branch (1.8.x). Most other branches are only used for a short time to do some testing without disturbing the main development. You can use your web browser to navigate through the source code:

http://svn.gna.org/viewcvs/wesnoth/

== Download ==

To check out trunk into a directory ''wesnoth'' (about 400 MB to download and 960 MB disk space, including .svn dirs, required as of March 30th 2009):
svn co http://svn.gna.org/svn/wesnoth/trunk wesnoth

Or, to check out the 1.8 branch (about 400 MB to download and 960 MB to store on disk as of March 30th 2009) into a directory ''wesnoth-1.8'':
svn co http://svn.gna.org/svn/wesnoth/branches/1.8 wesnoth-1.8

More info on the repository: https://gna.org/svn/?group=wesnoth

Note that if you are trying for commit access, you must have a developer account on gna, it must be registered as part of the Wesnoth group, and you must check out with
svn co svn+ssh://gna_username@svn.gna.org/svn/wesnoth/trunk wesnoth

== Update ==

Do this from inside the ''wesnoth'' or ''wesnoth-1.8'' directory where you checked out the repository:
svn update

The following is only relevant when relying on the autotools based build system. This is not needed when relying on CMake or SCons as build environment:

Note that when you update from Subversion, you should always run 'autogen.sh' if ''configure.ac'' or any of the ''Makefile.am'' files were changed. It is safest to 'make clean' before updating, then update and finally run 'autogen.sh', 'configure' and 'make'.

You may be able to skip the 'autogen.sh' and the 'make clean' if the makefiles and ''configure.ac'' have not changed. If only minor changes were made then even the 'configure' step is optional.

== See Also ==

* [[CompilingWesnoth]]
* [[UsingAutotools]]
* [[SVN_on_Windows]]

[[Category:Development]]

Distributing content

2010-05-07T06:17:20Z

Luther: /* The Add-on Server */ Corrections for 1.8 and info about what files aren't uploaded

== The Forum ==

The [http://www.wesnoth.org/forum/ BFW forum] is a good way to distribute small creations, like single multiplayer maps. Larger creations, like multiplayer eras or campaigns, should be compressed before uploading them. Note that you may encounter a size limit on attachments.

Also, there is a [http://www.wesnoth.org/forum/viewtopic.php?t=2014 legal announcement] that you should read before distributing anything on the forum. Basically, by posting you say that you own the license to what you are posting, and that you are licensing it under the [http://www.gnu.org/copyleft/gpl.html General Public License].

== The Add-on Server ==

The add-on server is the preferred way to distribute your creations, but it is more suited for larger projects. It currently lacks advanced organization features such as reviewing (although it does have a filter text box), so adding hundreds of little things makes it harder to find anything. Basically, the server should not be used to post single maps, units, songs, or artwork, but map packs, campaigns, entire eras, music packs, and unit packs are fine.

Once you are ready to publish, here is how you access the add-on server:
# Open Wesnoth
# Select "Add-ons" from the main menu
# Connect to the default ''add-ons.wesnoth.org'' add-on server
# Select "Publish add-on: ''Your Add-on Name''" (the last entry in the list of add-ons)

Anything you distribute on the server will be uploaded from and downloaded to the ''userdata''/data/add-ons directory regardless of what it is (units, maps, campaign, etc). For this reason, you need three things in the add-ons directory to distribute via the server:
# A folder, for example MyCampaign
# A .cfg file MyCampaign/_main.cfg
# A .pbl file MyCampaign/_server.pbl
Note that only the contents of your add-on directory (in this case, MyCampaign) will get uploaded, nothing else, so you need to have all the necessary files inside that directory.

The following files and directories will not be uploaded: those that begin with '.' and those that end in '~'. Also, the GNU GPL version 2 will be added in the file COPYING.txt.

==== General Reading ====
* [[BuildingCampaignsThePBLFile|General information about the .pbl file]] - It has a campaign flavor, but it is adaptable to any content
* [[PblWML|Syntax reference for the .pbl file]]

==== Content-specific instructions ====
* Maps - see [[BuildingMaps|Building Maps]]
** [[BuildingMapsDistribution|About distributing map-packs]]
* Campaign - see [[BuildingCampaigns|Building Campaigns]]
** [[BuildingCampaignsDistribution|About distributing campaigns]]
* Multiplayer era - see [[BuildingFactions#Adding_a_whole_new_era_with_its_own_factions_-_modular|Building MP Era]]
* Unit pack - see [[BuildingUnits#Distributing_your_unit|Building Units]]

==== License ====
You should note that by uploading anything to the add-on server, you say that you own the license to all content in your upload and that it is under the GPL. Whenever you upload or update your content pack, you will have to say "OK" to this statement: "All add-ons uploaded to this server must be licensed under the terms of the GNU General Public License (GPL). By uploading content to this server, you certify that you have the right to place the content under the conditions of the GPL, and choose to do so."

== See Also ==

* [[Create]]
* [[BuildingMapsDistribution]]
* [[BuildingCampaignsDistribution]]
* [[BuildingCampaignsThePBLFile]]
* [[PblWML]]
* [[IGNFileFormat]]
* [[Wesnoth:Copyrights]]

[[Category:Create]]

EventWML

2010-05-06T04:49:59Z

Luther: /* Predefined 'name' Key Values */ Removed {{DevFeature}} from 'prestart'

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

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

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

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

Usage:
name=<value>

This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.

'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''

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

For example:

name=attacker misses,defender misses

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

==== Predefined 'name' Key Values ====

All predefined event types are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else. Spaces in event names can be interchanged with underscores (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

; preload
: Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.
: '''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

; prestart
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.
: '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

; start
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.
: '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

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

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

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

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

; turn ''X''
: Triggers at the start of turn ''X''. It's the first side initialization event. Side initialization events go in the order of:
: 1) '''turn ''X''''' 2) '''new turn''' 3) '''side turn''' 4) '''side ''X'' turn''' 5) '''side ''X'' turn ''Y''''' 6) '''turn refresh'''

; side ''X'' turn ''Y''
: This event triggers at the start of turn ''Y'' of side X {{DevFeature}}

; side ''X'' turn
: This event triggers at the start of any turn of side X {{DevFeature}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; side X turn Y refresh
: This event triggers at the turn refresh for side X on turn Y {{DevFeature1.9}}

; side ''X'' turn refresh
: This event triggers at the turn refresh for side X {{DevFeature1.9}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; time over
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])

; enemies defeated
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.

; victory
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])

; defeat
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])

Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]

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

; sighted
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.) (Double note: it also appears that the sighted event in more recent versions of the game (1.6 and 1.7, maybe?) does not fire on enemy turns. That is, it only fires for units that become visible as a result of the motion of another unit, not for units that move into the vision of an enemy. This event is also buggy in general... it's usually better to use a moveto event with a [filter_vision] tag than to use a sighted event (and note that the combination of the two can achieve something like the old sighted event)).

; attack
: Triggers when the primary unit attacks the secondary unit.

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

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

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

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

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

; stone
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability). In {{DevFeature}}, this event name is changed to "petrified".

; last breath
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.

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

; capture
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.

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

; prerecruit
: Triggers when the primary unit is recruited but before it is displayed.

; recall
: Triggers after a unit is recalled.

; prerecall
: Triggers when a unit is recalled but before it is displayed.

; advance
: Triggers just before the primary unit is going to advance to another unit.

; post advance
: Triggers just after the primary unit has advanced to another unit.

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

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

==== Custom events ====

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

=== Optional Keys and Tags ===

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

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

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

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

==== [filter_attack] ====
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'' and ''attack end''. For more information and other filter keys, see [[FilterWML]].
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the secondary unit.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [event] ====
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].

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

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

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

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

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

=== Nested Events ===

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

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

==== Delayed Variable Substitution ====

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

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

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

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

== Multiplayer safety ==

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

List of synchronized events:
* moveto
* sighted
* attack
* attack_end
* attacker hits
* attacker misses
* defender hits
* defender misses
* stone
* last breath
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* post_advance
Events fired from a WML event handler that is synchronized:
* new turn {{DevFeature}}
* side turn {{DevFeature}}
* turn X {{DevFeature}}
* side X turn {{DevFeature}}
* side X turn Y {{DevFeature}}
* turn refresh {{DevFeature}}

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

== A Trap for the Unwary ==

It is perfectly possible (and, in fact, useful) to have multiple events with the same predefined name and thus the same trigger condition. However, it is not defined what order such events will fire in, so you need to code so the order
will not matter.

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

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

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}

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

== Miscellaneous Notes and Examples ==

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

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

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

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

=== Nested Event Example ===

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

[event]
name=turn 10

[event]
name=moveto

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

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

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

=== Delayed Variable Substitution Example ===

This code will display the turn on which the nested ''moveto'' event happens.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes

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

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

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

[event]
name=turn 10

[event]
name=moveto

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

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

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

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

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

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

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

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

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

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

=== Multiple Nested Events ===

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

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

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

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

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

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

== See Also ==

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

[[Category: WML Reference]]

LuaWML/Misc

2010-03-20T21:03:43Z

Luther: /* wesnoth. game_config */ Spurious space

BuildingMaps

2010-03-15T18:04:23Z

Luther: /* Play your map */ Use -> User

A map is just a bunch of terrain strings arranged in a rectangle (the rectangle is known as the "map data"). There are two ways to use this rectangle in a file: as a stand-alone map or within a scenario. The easiest way to create maps is just to use the built-in editor, but if you want to actually understand how maps work, you should read a little about the map data format. This page explains that format, and then has some pointers about the editor, saving files, and how to play on a map once you've made it. For instructions on how to distribute maps, see [[BuildingMapsDistribution]].

== Creating a map ==

Wesnoth has a fully functional map editor, accessible from within the game. The map editor should be fairly straightforward, however some helpful hotkeys can be found in the [[WesnothMapEditor]] article. Making good, balanced, interesting maps is another task altogether. ESR has addressed it in his [http://catb.org/~esr/wesnoth/campaign-design-howto.html Campaign Design How-To]. If you run into trouble with the map editor, go ahead and ask for help on the [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum].

If you're a programmer, note that while the source code and most binary distributions come with the official graphical map editor, you may have to give the build system a flag or argument to tell it to compile them as well as the main game.

=== Adding units and map descriptions ===

Campaign writers can't write campaigns without scenarios, so campaigns will always use scenario files. Multiplayer mapmakers, however, '''have a choice'''. If you want to place an object or unit on the map, you must create a scenario file starting with the '''[multiplayer]''' tag and containing the ''map_data'' key therein. The ''map_data'' key can either point to a standalone map file or include the raw map data in quotes inside the scenario file.

Using scenario files for multiplayer maps, you lose the simplicity of the standalone map file, but you gain tremendous power. With a scenario file, you can add units and objects, include a map description, and set default map settings like allies, starting gold, and experience modifiers. You can even create custom events. Check out [[BuildingScenarios]], [[ScenarioWML]], and [[BuildingMultiplayer]] for more information.

=== Map data format ===

This is not the Matrix. You normally don't need to look at encoded maps. However, if you would like to use some advanced terrain features or create scenarios and campaigns, you'll have to dive into the map code. The encoding for maps has a specific format in Wesnoth:

* A map starts with a header with the following keys
** '''usage''', this should be 'map' for a map and 'mask' for an overlay mask
** '''border_size''', the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
* Between the header and the data should be 1 empty line
* A map data file consists of any number of lines, each with the same number of strings.
* Each string must be a string specified in a ''string'' key specifying a terrain (see [[TerrainLettersWML]]).
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
* When the file is interpreted, each string will be replaced by the terrain it refers to.
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''. ''n'' = 1, 2, 3, ... 9 (more might work but is untested and unsupported). This is a change from the previous system where a starting position was automatically a keep.

It's advised to use spaces for padding and pad each column to be the same width; the game does this when writing a map file.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
Tiles in even-numbered columns are shifted down 1/2 of a tile.
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

== So now what? ==

You've created an awesome map with the map editor and you're ready to test it out. But how can you do this? It's actually quite simple.

=== Play your map ===

If you just want to play the map, maybe against the computer or with a friend, all you have to do is save it into the map editor's folder (the default location). Then, when you launch the game and host a multiplayer game, the map should appear '''at the top''' of the map choices screen.

When creating a game on the multiplayer server, your map will be described to other players as a "User Map" and any replays stored on the server will refer to the game as "User Map."

For the curious: Saving a map file like this creates a stand-alone file that holds the map data. That file is by default saved in '''''userdata''/editor/maps/''', and maps in that location are added to the top of the multiplayer map selection list.

=== Share your map ===

When you're ready to share your map with the world, post it to the [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development forum] or package it to be distributed on the in-game add-ons server. For instructions on how to distribute maps, see [[BuildingMapsDistribution]]

== See Also ==

* [[WesnothMapEditor]]
* [[TerrainCodesWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]

{{Create}}

InternalActionsWML

2010-03-14T18:42:24Z

Luther: /* [store_locations] */ Now returns border hexes

{{WML Tags}}

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

== Variable Actions ==

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

=== [set_variable] ===

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

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

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

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

* '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.

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

* '''add''': add the given amount to the variable. To subtract, add a negative number.

* '''sub''' {{DevFeature}}: subtract the given amount from the variable.

* '''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. Floating point values are not rounded.

* '''divide''': divide the variable by the given number. The result is an integer. Floating point results are not rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.

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

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

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

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

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

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

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

* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
**'''ceil''': Rounds upward to the nearest integer.
**'''floor''': Rounds down to the nearest integer.

=== [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. ([[#Using_.5Bset_variables.5D_to_Create_Arrays_of_WML|See Example]])

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

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

=== Capturing Game Data ===

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

==== [store_gold] ====

Stores a side's gold into a variable.

* '''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_locations] ====

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

* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. 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]''' with a [[StandardUnitFilter]] as argument. Only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.

==== [store_map_dimensions] ====

Stores the map dimensions in a variable.

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

==== [store_side] ====

Stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', '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

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

==== [store_unit] ====

Stores details about units into a [[VariablesWML#Container|container]] variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]. A sample list of these tags and keys can be found [[InternalActionsWMLUnitTags|here]]. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the '''[unit]''' tag(s) in any save file).

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

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

* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.

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

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

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

== Other Internal Actions ==

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

=== [fire_event] ===

Trigger a WML event

* '''name''': the name of event to trigger

* '''[primary_unit]''': ''(Optional)'' Primary unit for the event (usually the attacker). Will never match on a recall list unit. If it matches multiple units, only one will be chosen.
** '''x,y''': ''(Optional)'' The location of this unit.

* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary 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.

=== [insert_tag] ===

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

*'''name''': The ["name"] to be given to the tag. This must be a valid WML tag name for anything to happen.

*'''variable''': Name of the variable which will have it's value inserted into the tag.

=== [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 [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] (without [filter]) with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.

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

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

== Examples ==

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

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

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

=== [insert_tag] Example ===

[event]
name=moveto

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

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

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]

This is effectively identical to:

[event]
name=moveto

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

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

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

InternalActionsWML

2010-03-02T00:27:36Z

Luther: /* [store_locations] */ Specify if it stores border tiles

{{WML Tags}}

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

== Variable Actions ==

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

=== [set_variable] ===

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

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

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

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

* '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.

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

* '''add''': add the given amount to the variable. To subtract, add a negative number.

* '''sub''' {{DevFeature}}: subtract the given amount from the variable.

* '''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. Floating point values are not rounded.

* '''divide''': divide the variable by the given number. The result is an integer. Floating point results are not rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.

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

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

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

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

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

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

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

* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
**'''ceil''': Rounds upward to the nearest integer.
**'''floor''': Rounds down to the nearest integer.

=== [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. ([[#Using_.5Bset_variables.5D_to_Create_Arrays_of_WML|See Example]])

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

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

=== Capturing Game Data ===

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

==== [store_gold] ====

Stores a side's gold into a variable.

* '''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_locations] ====

Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only). Does not store the unreachable border hexes.

* [[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]''' with a [[StandardUnitFilter]] as argument. Only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.

==== [store_map_dimensions] ====

Stores the map dimensions in a variable.

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

==== [store_side] ====

Stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', '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

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

==== [store_unit] ====

Stores details about units into a [[VariablesWML#Container|container]] variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]. A sample list of these tags and keys can be found [[InternalActionsWMLUnitTags|here]]. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the '''[unit]''' tag(s) in any save file).

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

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

* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.

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

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

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

== Other Internal Actions ==

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

=== [fire_event] ===

Trigger a WML event

* '''name''': the name of event to trigger

* '''[primary_unit]''': ''(Optional)'' Primary unit for the event (usually the attacker). Will never match on a recall list unit. If it matches multiple units, only one will be chosen.
** '''x,y''': ''(Optional)'' The location of this unit.

* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary 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.

=== [insert_tag] ===

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

*'''name''': The ["name"] to be given to the tag. This must be a valid WML tag name for anything to happen.

*'''variable''': Name of the variable which will have it's value inserted into the tag.

=== [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 [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] (without [filter]) with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.

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

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

== Examples ==

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

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

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

=== [insert_tag] Example ===

[event]
name=moveto

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

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

[insert_tag]
name=message
variable=temp
[/insert_tag]
[/event]

This is effectively identical to:

[event]
name=moveto

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

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

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

Template:WML Tags

2010-01-08T03:57:28Z

Luther: Changed unit_type to point to UnitTypeWML

{| class="gallery" style="width:225px;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|about]],
[[AdvancedPreferenceWML|advanced_preference]],
[[UnitTypeWML|advancefrom]],
[[UnitTypeWML|advancement]],
[[StatisticalScenarioWML|advances]],
[[AiWML|ai]],
[[DirectActionsWML|allow_recruit]],
[[DirectActionsWML|allow_undo]],
[[ConditionalActionsWML#Meta_Condition_Tags|and]],
[[InterfaceActionsWML|animate_unit]],
[[AnimationWML|animation]],
[[VariablesWML|array]],
[[UnitTypeWML|attack]],
[[AnimationWML|attack_filter]],
[[StatisticalScenarioWML|attacks]],
[[AiWML|avoid]];
|-
|''B:''
[[UnitTypeWML|base_unit]], [[CampaignWML#The_.5Bbinary_path.5D_tag|binary_path]], [[HelpWML|bold]], [[EditorWML|brush]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],
[[DirectActionsWML|capture_village]],
[[ConditionalActionsWML#.5Bswitch.5D|case]],
[[ReplayWML|choose]],
[[InternalActionsWML|clear_variable]],
[[InterfaceActionsWML|colour_adjust]],
command([[InterfaceActionsWML|action]], [[ReplayWML|replay]]);
|-
|''D:''
[[AbilitiesWML|damage]],
[[StatisticalScenarioWML|deaths]],
[[InterfaceActionsWML|debug_message]],
[[AnimationWML|defend]],
[[StatisticalScenarioWML|defends]],
[[UnitTypeWML|defense]],
[[InterfaceActionsWML|delay]],
[[ReplayWML|destination]],
[[DirectActionsWML|disallow_recruit]],
[[ConditionalActionsWML#.5Bwhile.5D|do]];
|-
|''E:''
[[EditorWML|editor_group]],
[[EditorWML|editor_music]],
[[EditorWML|editor_times]],
[[EditorWML|editor_tool_hint]],
[[EffectWML|effect]],
[[ConditionalActionsWML#Conditional_Actions|else]],
[[DirectActionsWML|endlevel]],
end_turn ([[DirectActionsWML|action]], [[ReplayWML|replay]]),
[[EraWML|era]],
[[EventWML|event]],
[[ThemeWML|expenses]];
|-
|''F:''
[[EventWML#.5Bfilter.5D|filter]],
[[FilterWML|filter]],
[[AnimationWML|filter_attack]],
[[EventWML#.5Bfilter_attack.5D|filter_attack]],
[[FilterWML|filter_location]],
[[EventWML#.5Bfilter_second.5D|filter_second]],
[[FilterWML|filter_second]],
[[AnimationWML|filter_second_attack]],
[[EventWML#.5Bfilter_second_attack.5D|filter_second_attack]],
[[FilterWML|filter_vision]],
[[StandardUnitFilter|filter_wml]],
[[InternalActionsWML|fire_event]],
[[HelpWML|format]],
[[AnimationWML|frame]];
|-
|''G:''
[[GameConfigWML|game_config]],
[[ScenarioWML|generator]],
[[DirectActionsWML|gold]],
[[ThemeWML|gold]];
|-
|''H:''
[[ConditionalActionsWML#Condition_Tags|have_location]],
[[ConditionalActionsWML#Condition_Tags|have_unit]],
[[HelpWML|header]],
[[DirectActionsWML|heal_unit]],
[[UnitsWML|hide_help]],
[[InterfaceActionsWML|hide_unit]];
|-
|''I:''
[[ConditionalActionsWML#.5Bif.5D|if]],
[[TimeWML|illuminated_time]],
[[TerrainGraphicsWML|image]],
[[HelpWML|img]],
[[ThemeWML|income]],
[[ReplayWML|init_side]],
[[InternalActionsWML|insert_tag]],
[[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]],
[[LuaWML|lua]];
|-
|''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]],
[[UnitTypeWML|movement costs]],
[[UnitsWML|movetype]],
[[ScenarioWML|multiplayer]],
[[EraWML|multiplayer_side]],
[[InterfaceActionsWML|music]];
|-
|''N:''
[[AnimationWML|neighbour_unit_filter]],
[[ConditionalActionsWML#Meta_Condition_Tags|not]],
[[FilterWML|not]],
[[ThemeWML|num_units]];
|-
|''O:''
[[DirectActionsWML|object]],
[[InterfaceActionsWML|objectives]],
[[InterfaceActionsWML|objective]],
[[ThemeWML|observers]],
[[InterfaceActionsWML|open_help]],
[[InterfaceActionsWML|option]],
[[ConditionalActionsWML#Meta_Condition_Tags|or]];
|-
|''P:''
[[ThemeWML|panel]], [[IntroWML|part]], [[DirectActionsWML|place_shroud]], [[ThemeWML|position]],
[[InterfaceActionsWML|print]], [[AiWML|protect_location]], [[AiWML|protect_unit]];
|-
|''R:''
[[UnitsWML|race]], [[ReplayWML|random]], recall ([[DirectActionsWML|action]],
[[ReplayWML|replay]]), [[StatisticalScenarioWML|recalls]],
[[ReplayWML|recruit]], [[StatisticalScenarioWML|recruits]], [[InterfaceActionsWML|redraw]],
[[HelpWML|ref]], [[DirectActionsWML|remove_shroud]], [[InterfaceActionsWML|remove_unit_overlay]],
[[InterfaceActionsWML|removeitem]], [[InterfaceActionsWML|remove_sound_source]],
[[ReplaceMapWML|replace_map]] [[SavefileWML|replay]], [[SavefileWML|replay_start]],
[[UnitTypeWML|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]], [[InterfaceActionsWML|show_objectives]],
[[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_side]], [[InternalActionsWML|store_starting_location]], [[InternalActionsWML|store_time_of_day]], [[InternalActionsWML|store_unit]], [[InternalActionsWML|store_villages]] [[IntroWML|story]],
[[ConditionalActionsWML#.5Bswitch.5D|switch]];
|-
|''T:''
[[AiWML|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
[[DirectActionsWML|teleport]], [[AnimationWML|teleport_anim]],
terrain([[TerrainWML|define]], [[DirectActionsWML|create]]), [[TerrainGraphicsWML|terrain_graphics]], [[TerrainMaskWML|terrain_mask]], [[ScenarioWML#Test_scenario|test]],
[[WesCamp|textdomain]], [[InterfaceActionsWML|text_input]], [[ThemeWML|theme]], [[ConditionalActionsWML#.5Bif.5D|then]],
[[TerrainGraphicsWML|tile]], [[TimeWML|time]], time_area ([[DirectActionsWML|action]], [[ScenarioWML|scenario]]),
[[ThemeWML|time_of_day]],
[[HelpWML|topic]], [[HelpWML|toplevel]], [[SingleUnitWML|trait]], [[ThemeWML|turn]], [[ScenarioWML|tutorial]];
|-
|''U:''
[[InterfaceActionsWML|unhide_unit]], unit ([[UnitTypeWML|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]], [[UnitTypeWML|unit_type]], [[ThemeWML|unit_weapons]], [[ThemeWML|unit_xp]],
[[UnitsWML|units]], [[DirectActionsWML|unstone]], [[DirectActionsWML|unstore_unit]], [[ThemeWML|upkeep]];
|-
| ''V:''
[[ConditionalActionsWML#Condition_Tags|variable]],
[[VariablesWML|variables]],
[[SideWML|village]],
[[ThemeWML|villages]];
|-
| ''W:''
[[ConditionalActionsWML#.5Bwhile.5D|while]],
[[InterfaceActionsWML|wml_message]];
|}

Download

2007-11-27T20:16:53Z

Luther: /* Source code */ Words "current" and "previous" were switched

Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.2_branch.29|Stable Branch]] | [[Download#Development_.281.3_branch.29|Development Branch]]

== Stable (1.2 branch) ==

==== Source code ====
* [http://downloads.sourceforge.net/wesnoth/wesnoth-1.2.8.tar.bz2?download Current stable version] (1.2.8, 69.7 MB)
* [http://downloads.sourceforge.net/wesnoth/wesnoth-1.2.7.tar.bz2?download Previous stable version] (1.2.7, 69.7 MB)
* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== [[BeOS]] ====
* The current version (1.2.8) is not available yet.
* [http://zeta-games.com/index.php?option=com_remository&Itemid=28&func=fileinfo&id=24 Previous stable version] (1.2.1, 70.11 MB)
* [http://downloads.sourceforge.net/wesnoth/Wesnoth-1.0.2-BeOS-x86.pkg.zip?download Older stable version, not compatible with 1.2] (1.0.2, 42.3 MB)

==== GNU/Linux ====
* There are specific binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more informations about the binaries for your Distribution.

==== OpenBSD ====
'''Note:''' OpenBSD-current is required to play with these binaries:
* The current version (1.2.8) is not available yet.
* [http://downloads.sourceforge.net/wesnoth/wesnoth-openbsd--1.2.7.tgz?download Previous stable version ] (1.2.7, 75.0 MiB)
* [ftp://pkg@ftp.enqlave.net/wesnoth-1.2.7.tgz Previous stable version (mirror @ Enqlave) ] (1.2.7, 75.0 MiB)

==== OS/2 & eComStation ====
* The current version (1.2.8) not available yet.
* [http://download.smedley.info/wesnoth-1.2.5-os2.zip Previous stable version (1.2.5)] (1.2.5, 70 MB)

==== Mac OS X ====
Be aware that OSX 10.3.9+ is required to play with these binaries.
* [http://downloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.2.8a.dmg?download Current stable version] (1.2.8, Universal, 81.0 MB)
* [http://downloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.2.8_lite.dmg?download Current stable version - lite] (1.2.8, Universal, no art or music, 51.9 MB)
* [http://downloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.2.7.dmg?download Previous stable version] (1.2.7, Universal, 80.8 MB)
* [http://downloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.2.7_lite.dmg?download Previous stable version - lite] (1.2.7, Universal, no art or music, 51.5 MB)

==== MS Windows ====
* [http://downloads.sourceforge.net/wesnoth/wesnoth-1.2.8-windows.exe?download Current version] (1.2.8, 63.0 MB)
* [http://downloads.sourceforge.net/wesnoth/wesnoth-1.2.7-windows.exe?download Previous version] (1.2.7, 63.1 MB)

==== AmigaOS4 ====
* The current version (1.2.8) is not available yet.
* [http://os4depot.net/index.php?function=showfile&file=game/strategy/wesnoth.lha Previous stable version ] (1.2.5, 63 MB)

==== Syllable ====
* The current version (1.2.8) is not available yet.
* [http://www.syllable-software.info/download.php?view.28 Previous stable version] (1.2.6, 60.8 MB)

==== Miscellaneous ====
* [http://downloads.sourceforge.net/wesnoth/wesnoth-1.2.8.tar.bz2.md5?download Source code md5sum]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Source_code Xdelta for the source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#MS_Windows Xdelta for the Windows binary]

== Development (1.3 branch) ==

Version 1.3.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.2.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth.

==== Source code ====
* [http://downloads.sourceforge.net/wesnoth/wesnoth-1.3.11.tar.bz2?download Current Version] (1.3.11, 98.2 MB)
* [http://downloads.sourceforge.net/wesnoth/wesnoth-1.3.10.tar.bz2?download Previous Version] (1.3.10, 98.2 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://downloads.sourceforge.net/wesnoth/wesnoth-1.3.11-windows.exe?download Current version] (1.3.11, 89.8 MB)
* [http://downloads.sourceforge.net/wesnoth/wesnoth-1.3.10-windows.exe?download Previous Version] (1.3.10, 89.8 MB)
* [http://www.exong.net/builds/index.php?dir=&sort=date&order=desc Daily SVN snapshots] (only the .exe, in addition you need an SVN checkout to use it)

==== Mac OS X ====
* [http://downloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.3.11.dmg?download Current Version] (1.3.11, Universal, 109.5 MB)
* [http://downloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.3.11_lite.dmg?download Current Version - lite] (1.3.11, Universal, no art or music, 63.4 MB)
* [http://downloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.3.10.dmg?download Previous Version] (1.3.10, Universal, 109.3 MB)
* [http://downloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.3.10_lite.dmg?download Previous Version - lite] (1.3.10, Universal, no art or music, 63.2 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== (Open)Solaris ====
* The current version (1.3.11) is not available yet.
* [http://downloads.sourceforge.net/wesnoth/wesnoth-solaris-1.3.8.i386.pkg.bz2?download Older version for x86] (1.3.8, Solaris package for x86, 77.6 MB)

==== AmigaOS4 ====
* [http://os4depot.net/index.php?function=showfile&file=game/strategy/wesnoth-devel.lha Current Version] (1.3.11, 93 MB)

==== OS/2 & eComStation ====
* The current version not available.
* [http://download.smedley.info/wesnoth-1.1.8-os2.zip Older Version] (1.1.8, 66 MB)

==== Syllable ====
* The current version (1.3.11) is not available yet.
* [http://www.syllable-software.info/download.php?view.32 Older Version] (1.3.8, 82.2 MB)

==== Miscellaneous ====
* [http://downloads.sourceforge.net/wesnoth/wesnoth-1.3.11.tar.bz2.md5?download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Source_code Xdelta for the source code]
* [http://sourceforge.net/project/showfiles.php?group_id=89495 SourceForge page for current and all previous versions]

== License ==
This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org/ Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothSVN]] - bleeding edge version from SVN

BasicStrategy

2006-10-06T16:38:03Z

Luther: /* Don't waste units */

The following basic combat principles and tips are intended to help starting off your career as a wesnothian battle veteran. The minor concrete examples are somewhat tied to the "Heir to the Throne" campaign.

=== Don't waste units ===

Do not send wounded units to a sure death. Once a unit loses more than half of its hit points (HP), you should seriously consider retreating it to safety and either station it in a village for healing or give him to the care of a healer (like Elvish Shamans or White Mages). Healers are very useful!

This is for practical reasons: a heavily wounded unit cannot hold back or kill the enemy. During attack and counterattack, it most often will perish. Further, by sending it to its sure death, its gathered experience points (XP) are lost. Recruiting a replacement may be impossible because the leader is not in its keep or because funds are running low. Even if you can recruit a replacement, it is most often far away from the battle front. So don't waste your units.

=== Out of the enemy's reach ===

How do you guard wounded units? They are best guarded by being out of the adversary's reach. No enemy can attack them if enemies cannot even come near them. The next section about zone of control (ZOC) shows how to restrict the enemy's moves.

In the Action menu, you can select "Show Enemy Moves" to highlight all possible hexes your adversary can actually move to. This takes your zone of control into account. Thus you can check that your near death unit, which is behind, indeed cannot be attacked as the enemy cannot move close to it.

When your armies meet, you may want to try to be the first to attack. So try to end your move out of striking range of the enemy army. He cannot attack but most likely will close into your striking range.

=== Shield with your zone of control (ZOC) ===

Every unit of level 1 or higher maintains a zone of control (ZOC) covering all 6 neighboring hexes. This means that once an enemy moves into one of the six neighboring tiles, it is forced to halt and its movement phase ends (only enemies with the rare skirmisher ability ignore this).

Because of ZOC, an enemy may not slip between two units which are aligned on a north-south or diagonal line and have exactly 1 or 2 hexes between them. By combining these pairs into a long wall or using them in different directions, you can prevent the enemy from reaching a wounded unit behind. He has to defeat the units imposing the ZOC first. If the enemy can barely reach it, even a single unit may shield a small region behind itself.

=== Maintain a defensive line ===

By lining up many units directly adjacent or with at most 1 hex space between them, you can build up a powerful defensive line. Note that, because Wesnoth uses hexes, a east-to-west "line" is not a straight line but a zig-zag curve. The north south line and the diagonals are the "real" lines.

Coming from one side, the enemy may attack any single of your units in the line with only 2 of his units at a time. As a rule of thumb, a healthy unit without particular weakness can withstand an attack from two normal enemy units without getting killed.

Unfortunately, your line often has to bend to form a wedge or to fit the terrain. At these corner points, 3 enemy units may attack. This also happens at the ends of a line if the line is too short. Use units with high hit point on proper terrain or with proper resistances to hold these weak points. These are the most likely to be killed, so use units with no or few experience points (XP) for this purpose.

Lining your troops up also prevents the enemy from surrounding any one of them. For ZOC reasons, a unit with one enemy behind and in front is trapped.

=== Rotate your troops ===

When a unit in the front line is heavily damaged you can move him safely behind your defensive line. To hold up the line, you will most likely have to replace him with a reserve, so hold a couple of units in back of the front line. If you have healers, damaged units in the second line will quickly recover.

Note that your units ''can'' pass through hexes containing your own troops.

=== Use the terrain ===

Try to position your troops so that they are attacking from a hex with high defense against an enemy in a hex with low terrain. Note that different units work better on different terrains. This way, terrain often dictates where you line up your units.

For example, you may position your elves at the end of the forest so that attacking orcs must stand on grassland while your elves enjoy the high forest defenses.

=== Attacking and choosing your targets ===

Advancing and attacking is of course the most interesting part of your way to victory. Kill or weaken enemies in your path and move your defensive line forward. This can become tricky as the enemy gets to attack back on his turn.

Often, you will throw several units at a single enemy unit to finish him off, but these were forming your defensive line which is now partly broken. Maybe this doesn't matter because you are out of reach of the next enemy unit. Maybe it does because you only managed to weaken a very strong enemy and next turn, he is going to strike back. Perhaps a Horseman can deliver the killing blow.

Striking first is an advantage because it allows you the choice of which units will face off. Take advantage of enemy weakness: e.g. direct your ranged attacks against foes without ranged weapons. Take advantage of weaknesses like Horsemen's vulnerability to pierce. But remember that they get to attack back on their turn, so you might have weaknesses he may exploit.

For example, Horsemen can hold up the line against Orcish Grunts and Troll Whelps very well because they have some resistances against blade and impact. But your Horseman may quite quickly fall to Orcish Archers and Orcish Pikemen.

It usually pays off if you can definitively kill (or almost kill) the faced unit. If you are unsure of finishing off the enemy in one turn, ensure that your unit can weather the return attacks, or that you're willing to lose that unit. To withstand the enemies strikes next turn, it is often wise to attack with the weapon that deals the least damage to you. So use your ranged weapons if the enemy has no ranged attack. The computers default choice only looks for the most damage you deal out.

=== Time of Day ===

Remember that Lawful units like humans fight better at daytime and Chaotic units like orcs or undead fight better at night. Ideally you want to first meet the enemy when you are strong and/or he is weak. When the enemy has its strong time, it often pays off to strengthen your lines and hold a favorable defensive position. When its weak time is about to arise, your advance will push forth.

For example, elves might hold out a forest during a nightly orcish onslaught and advance on sunrise. You may even note that the computer AI actively retreats his orcs during day.

=== Experience ===

Over the course of a campaign, it is critical that you build up a seasoned force. Later scenarios will assume you have level 2 and 3 units available for recall.

Your units gain most experience points (XP) from killing an enemy unit (8XP per level of the unit killed). As such, it often makes sense to have your higher level units weaken an enemy, but cede the kill to a unit more in need of the XP. Healers in particular are often weak in combat and often need to 'steal' kills in this way to advance levels.

At the beginning (when you probably have no high level units), try to give most kills to a small handful of your units. This will fast-track them to becoming Level 2 units, and they can then shepherd others.

Don't neglect to earn your leader experience. You need to keep him safe, but if you coddle him too much he will be too low level to survive future scenarios anyway.

BasicStrategy

2006-10-06T16:33:56Z

Luther: /* Shield with your zone of control (ZOC) */

The following basic combat principles and tips are intended to help starting off your career as a wesnothian battle veteran. The minor concrete examples are somewhat tied to the "Heir to the Throne" campaign.

=== Don't waste units ===

Do not send wounded units to a sure death. Once a unit loses more than half of its hit points, you should seriously consider retreating it to safety and either station it in a village for healing or give him to the care of a healer (like Elvish Shamans or White Mages). Healers are very useful!

This is for practical reasons: a heavily wounded unit cannot hold back or kill the enemy. During attack and counterattack, it most often will perish. Further, by sending it to its sure death, its gathered experience points (XP) are lost. Recruiting a replacement may be impossible because the leader is not in its keep or because funds are running low. Even if you can recruit a replacement, it is most often far away from the battle front. So don't waste your units.

=== Out of the enemy's reach ===

How do you guard wounded units? They are best guarded by being out of the adversary's reach. No enemy can attack them if enemies cannot even come near them. The next section about zone of control (ZOC) shows how to restrict the enemy's moves.

In the Action menu, you can select "Show Enemy Moves" to highlight all possible hexes your adversary can actually move to. This takes your zone of control into account. Thus you can check that your near death unit, which is behind, indeed cannot be attacked as the enemy cannot move close to it.

When your armies meet, you may want to try to be the first to attack. So try to end your move out of striking range of the enemy army. He cannot attack but most likely will close into your striking range.

=== Shield with your zone of control (ZOC) ===

Every unit of level 1 or higher maintains a zone of control (ZOC) covering all 6 neighboring hexes. This means that once an enemy moves into one of the six neighboring tiles, it is forced to halt and its movement phase ends (only enemies with the rare skirmisher ability ignore this).

Because of ZOC, an enemy may not slip between two units which are aligned on a north-south or diagonal line and have exactly 1 or 2 hexes between them. By combining these pairs into a long wall or using them in different directions, you can prevent the enemy from reaching a wounded unit behind. He has to defeat the units imposing the ZOC first. If the enemy can barely reach it, even a single unit may shield a small region behind itself.

=== Maintain a defensive line ===

By lining up many units directly adjacent or with at most 1 hex space between them, you can build up a powerful defensive line. Note that, because Wesnoth uses hexes, a east-to-west "line" is not a straight line but a zig-zag curve. The north south line and the diagonals are the "real" lines.

Coming from one side, the enemy may attack any single of your units in the line with only 2 of his units at a time. As a rule of thumb, a healthy unit without particular weakness can withstand an attack from two normal enemy units without getting killed.

Unfortunately, your line often has to bend to form a wedge or to fit the terrain. At these corner points, 3 enemy units may attack. This also happens at the ends of a line if the line is too short. Use units with high hit point on proper terrain or with proper resistances to hold these weak points. These are the most likely to be killed, so use units with no or few experience points (XP) for this purpose.

Lining your troops up also prevents the enemy from surrounding any one of them. For ZOC reasons, a unit with one enemy behind and in front is trapped.

=== Rotate your troops ===

When a unit in the front line is heavily damaged you can move him safely behind your defensive line. To hold up the line, you will most likely have to replace him with a reserve, so hold a couple of units in back of the front line. If you have healers, damaged units in the second line will quickly recover.

Note that your units ''can'' pass through hexes containing your own troops.

=== Use the terrain ===

Try to position your troops so that they are attacking from a hex with high defense against an enemy in a hex with low terrain. Note that different units work better on different terrains. This way, terrain often dictates where you line up your units.

For example, you may position your elves at the end of the forest so that attacking orcs must stand on grassland while your elves enjoy the high forest defenses.

=== Attacking and choosing your targets ===

Advancing and attacking is of course the most interesting part of your way to victory. Kill or weaken enemies in your path and move your defensive line forward. This can become tricky as the enemy gets to attack back on his turn.

Often, you will throw several units at a single enemy unit to finish him off, but these were forming your defensive line which is now partly broken. Maybe this doesn't matter because you are out of reach of the next enemy unit. Maybe it does because you only managed to weaken a very strong enemy and next turn, he is going to strike back. Perhaps a Horseman can deliver the killing blow.

Striking first is an advantage because it allows you the choice of which units will face off. Take advantage of enemy weakness: e.g. direct your ranged attacks against foes without ranged weapons. Take advantage of weaknesses like Horsemen's vulnerability to pierce. But remember that they get to attack back on their turn, so you might have weaknesses he may exploit.

For example, Horsemen can hold up the line against Orcish Grunts and Troll Whelps very well because they have some resistances against blade and impact. But your Horseman may quite quickly fall to Orcish Archers and Orcish Pikemen.

It usually pays off if you can definitively kill (or almost kill) the faced unit. If you are unsure of finishing off the enemy in one turn, ensure that your unit can weather the return attacks, or that you're willing to lose that unit. To withstand the enemies strikes next turn, it is often wise to attack with the weapon that deals the least damage to you. So use your ranged weapons if the enemy has no ranged attack. The computers default choice only looks for the most damage you deal out.

=== Time of Day ===

Remember that Lawful units like humans fight better at daytime and Chaotic units like orcs or undead fight better at night. Ideally you want to first meet the enemy when you are strong and/or he is weak. When the enemy has its strong time, it often pays off to strengthen your lines and hold a favorable defensive position. When its weak time is about to arise, your advance will push forth.

For example, elves might hold out a forest during a nightly orcish onslaught and advance on sunrise. You may even note that the computer AI actively retreats his orcs during day.

=== Experience ===

Over the course of a campaign, it is critical that you build up a seasoned force. Later scenarios will assume you have level 2 and 3 units available for recall.

Your units gain most experience points (XP) from killing an enemy unit (8XP per level of the unit killed). As such, it often makes sense to have your higher level units weaken an enemy, but cede the kill to a unit more in need of the XP. Healers in particular are often weak in combat and often need to 'steal' kills in this way to advance levels.

At the beginning (when you probably have no high level units), try to give most kills to a small handful of your units. This will fast-track them to becoming Level 2 units, and they can then shepherd others.

Don't neglect to earn your leader experience. You need to keep him safe, but if you coddle him too much he will be too low level to survive future scenarios anyway.

BasicStrategy

2006-10-06T16:08:26Z

Luther: /* Out of the enemy's reach */

The following basic combat principles and tips are intended to help starting off your career as a wesnothian battle veteran. The minor concrete examples are somewhat tied to the "Heir to the Throne" campaign.

=== Don't waste units ===

Do not send wounded units to a sure death. Once a unit loses more than half of its hit points, you should seriously consider retreating it to safety and either station it in a village for healing or give him to the care of a healer (like Elvish Shamans or White Mages). Healers are very useful!

This is for practical reasons: a heavily wounded unit cannot hold back or kill the enemy. During attack and counterattack, it most often will perish. Further, by sending it to its sure death, its gathered experience points (XP) are lost. Recruiting a replacement may be impossible because the leader is not in its keep or because funds are running low. Even if you can recruit a replacement, it is most often far away from the battle front. So don't waste your units.

=== Out of the enemy's reach ===

How do you guard wounded units? They are best guarded by being out of the adversary's reach. No enemy can attack them if enemies cannot even come near them. The next section about zone of control (ZOC) shows how to restrict the enemy's moves.

In the Action menu, you can select "Show Enemy Moves" to highlight all possible hexes your adversary can actually move to. This takes your zone of control into account. Thus you can check that your near death unit, which is behind, indeed cannot be attacked as the enemy cannot move close to it.

When your armies meet, you may want to try to be the first to attack. So try to end your move out of striking range of the enemy army. He cannot attack but most likely will close into your striking range.

=== Shield with your zone of control (ZOC) ===

Every hex tile a unit stands on has 6 neighbors. On these, every unit of level 1 or higher maintains a zone of control (ZOC). This means that once an enemy moves into one of the six aforementioned tiles, it is forced to halt and its movement phase ends (only enemies with the rare skirmisher ability ignore this).

Because of ZOC, an enemy may not slip between two units which are aligned on a north-south or a diagonal line and have exactly 1 or 2 hexes between them. By combining these pairs to a long wall or using them in different directions, you can be prevent the enemy reaching a wounded unit behind. He has to defeat the ZOC imposing units first. If the enemy can barely reach it, even a single unit may shield a small region behind itself.

=== Maintain a defensive line ===

By lining up many units directly adjacent or with at most 1 hex space between them, you can build up a powerful defensive line. Note that, because Wesnoth uses hexes, a east-to-west "line" is not a straight line but a zig-zag curve. The north south line and the diagonals are the "real" lines.

Coming from one side, the enemy may attack any single of your units in the line with only 2 of his units at a time. As a rule of thumb, a healthy unit without particular weakness can withstand an attack from two normal enemy units without getting killed.

Unfortunately, your line often has to bend to form a wedge or to fit the terrain. At these corner points, 3 enemy units may attack. This also happens at the ends of a line if the line is too short. Use units with high hit point on proper terrain or with proper resistances to hold these weak points. These are the most likely to be killed, so use units with no or few experience points (XP) for this purpose.

Lining your troops up also prevents the enemy from surrounding any one of them. For ZOC reasons, a unit with one enemy behind and in front is trapped.

=== Rotate your troops ===

When a unit in the front line is heavily damaged you can move him safely behind your defensive line. To hold up the line, you will most likely have to replace him with a reserve, so hold a couple of units in back of the front line. If you have healers, damaged units in the second line will quickly recover.

Note that your units ''can'' pass through hexes containing your own troops.

=== Use the terrain ===

Try to position your troops so that they are attacking from a hex with high defense against an enemy in a hex with low terrain. Note that different units work better on different terrains. This way, terrain often dictates where you line up your units.

For example, you may position your elves at the end of the forest so that attacking orcs must stand on grassland while your elves enjoy the high forest defenses.

=== Attacking and choosing your targets ===

Advancing and attacking is of course the most interesting part of your way to victory. Kill or weaken enemies in your path and move your defensive line forward. This can become tricky as the enemy gets to attack back on his turn.

Often, you will throw several units at a single enemy unit to finish him off, but these were forming your defensive line which is now partly broken. Maybe this doesn't matter because you are out of reach of the next enemy unit. Maybe it does because you only managed to weaken a very strong enemy and next turn, he is going to strike back. Perhaps a Horseman can deliver the killing blow.

Striking first is an advantage because it allows you the choice of which units will face off. Take advantage of enemy weakness: e.g. direct your ranged attacks against foes without ranged weapons. Take advantage of weaknesses like Horsemen's vulnerability to pierce. But remember that they get to attack back on their turn, so you might have weaknesses he may exploit.

For example, Horsemen can hold up the line against Orcish Grunts and Troll Whelps very well because they have some resistances against blade and impact. But your Horseman may quite quickly fall to Orcish Archers and Orcish Pikemen.

It usually pays off if you can definitively kill (or almost kill) the faced unit. If you are unsure of finishing off the enemy in one turn, ensure that your unit can weather the return attacks, or that you're willing to lose that unit. To withstand the enemies strikes next turn, it is often wise to attack with the weapon that deals the least damage to you. So use your ranged weapons if the enemy has no ranged attack. The computers default choice only looks for the most damage you deal out.

=== Time of Day ===

Remember that Lawful units like humans fight better at daytime and Chaotic units like orcs or undead fight better at night. Ideally you want to first meet the enemy when you are strong and/or he is weak. When the enemy has its strong time, it often pays off to strengthen your lines and hold a favorable defensive position. When its weak time is about to arise, your advance will push forth.

For example, elves might hold out a forest during a nightly orcish onslaught and advance on sunrise. You may even note that the computer AI actively retreats his orcs during day.

=== Experience ===

Over the course of a campaign, it is critical that you build up a seasoned force. Later scenarios will assume you have level 2 and 3 units available for recall.

Your units gain most experience points (XP) from killing an enemy unit (8XP per level of the unit killed). As such, it often makes sense to have your higher level units weaken an enemy, but cede the kill to a unit more in need of the XP. Healers in particular are often weak in combat and often need to 'steal' kills in this way to advance levels.

At the beginning (when you probably have no high level units), try to give most kills to a small handful of your units. This will fast-track them to becoming Level 2 units, and they can then shepherd others.

Don't neglect to earn your leader experience. You need to keep him safe, but if you coddle him too much he will be too low level to survive future scenarios anyway.

BasicStrategy

2006-10-06T15:55:54Z

Luther: /* Don't waste units */

The following basic combat principles and tips are intended to help starting off your career as a wesnothian battle veteran. The minor concrete examples are somewhat tied to the "Heir to the Throne" campaign.

=== Don't waste units ===

Do not send wounded units to a sure death. Once a unit loses more than half of its hit points, you should seriously consider retreating it to safety and either station it in a village for healing or give him to the care of a healer (like Elvish Shamans or White Mages). Healers are very useful!

This is for practical reasons: a heavily wounded unit cannot hold back or kill the enemy. During attack and counterattack, it most often will perish. Further, by sending it to its sure death, its gathered experience points (XP) are lost. Recruiting a replacement may be impossible because the leader is not in its keep or because funds are running low. Even if you can recruit a replacement, it is most often far away from the battle front. So don't waste your units.

=== Out of the enemy's reach ===

How do you guard wounded units? They are best guarded by being out of the adversary's reach. No enemy can attack them, just because no enemy cannot even come near to them. The next paragraph about zone of control (ZOC) will shows how to restrict the enemy's moves.

In the Action menu, you can select "Show Enemy Moves" to highlight all possible hexes your adversary can actually move to and which takes your zone of control into account. Thus you can check that your near death unit behind indeed cannot be attacked as the enemy may not move close to it.

When your armies meet, you may want to try to be the first to attack. So try to end your move out of the striking range of the enemy army. He cannot attack but most likely will close in into your striking range.

=== Shield with your zone of control (ZOC) ===

Every hex tile a unit stands on has 6 neighbors. On these, every unit of level 1 or higher maintains a zone of control (ZOC). This means that once an enemy moves into one of the six aforementioned tiles, it is forced to halt and its movement phase ends (only enemies with the rare skirmisher ability ignore this).

Because of ZOC, an enemy may not slip between two units which are aligned on a north-south or a diagonal line and have exactly 1 or 2 hexes between them. By combining these pairs to a long wall or using them in different directions, you can be prevent the enemy reaching a wounded unit behind. He has to defeat the ZOC imposing units first. If the enemy can barely reach it, even a single unit may shield a small region behind itself.

=== Maintain a defensive line ===

By lining up many units directly adjacent or with at most 1 hex space between them, you can build up a powerful defensive line. Note that, because Wesnoth uses hexes, a east-to-west "line" is not a straight line but a zig-zag curve. The north south line and the diagonals are the "real" lines.

Coming from one side, the enemy may attack any single of your units in the line with only 2 of his units at a time. As a rule of thumb, a healthy unit without particular weakness can withstand an attack from two normal enemy units without getting killed.

Unfortunately, your line often has to bend to form a wedge or to fit the terrain. At these corner points, 3 enemy units may attack. This also happens at the ends of a line if the line is too short. Use units with high hit point on proper terrain or with proper resistances to hold these weak points. These are the most likely to be killed, so use units with no or few experience points (XP) for this purpose.

Lining your troops up also prevents the enemy from surrounding any one of them. For ZOC reasons, a unit with one enemy behind and in front is trapped.

=== Rotate your troops ===

When a unit in the front line is heavily damaged you can move him safely behind your defensive line. To hold up the line, you will most likely have to replace him with a reserve, so hold a couple of units in back of the front line. If you have healers, damaged units in the second line will quickly recover.

Note that your units ''can'' pass through hexes containing your own troops.

=== Use the terrain ===

Try to position your troops so that they are attacking from a hex with high defense against an enemy in a hex with low terrain. Note that different units work better on different terrains. This way, terrain often dictates where you line up your units.

For example, you may position your elves at the end of the forest so that attacking orcs must stand on grassland while your elves enjoy the high forest defenses.

=== Attacking and choosing your targets ===

Advancing and attacking is of course the most interesting part of your way to victory. Kill or weaken enemies in your path and move your defensive line forward. This can become tricky as the enemy gets to attack back on his turn.

Often, you will throw several units at a single enemy unit to finish him off, but these were forming your defensive line which is now partly broken. Maybe this doesn't matter because you are out of reach of the next enemy unit. Maybe it does because you only managed to weaken a very strong enemy and next turn, he is going to strike back. Perhaps a Horseman can deliver the killing blow.

Striking first is an advantage because it allows you the choice of which units will face off. Take advantage of enemy weakness: e.g. direct your ranged attacks against foes without ranged weapons. Take advantage of weaknesses like Horsemen's vulnerability to pierce. But remember that they get to attack back on their turn, so you might have weaknesses he may exploit.

For example, Horsemen can hold up the line against Orcish Grunts and Troll Whelps very well because they have some resistances against blade and impact. But your Horseman may quite quickly fall to Orcish Archers and Orcish Pikemen.

It usually pays off if you can definitively kill (or almost kill) the faced unit. If you are unsure of finishing off the enemy in one turn, ensure that your unit can weather the return attacks, or that you're willing to lose that unit. To withstand the enemies strikes next turn, it is often wise to attack with the weapon that deals the least damage to you. So use your ranged weapons if the enemy has no ranged attack. The computers default choice only looks for the most damage you deal out.

=== Time of Day ===

Remember that Lawful units like humans fight better at daytime and Chaotic units like orcs or undead fight better at night. Ideally you want to first meet the enemy when you are strong and/or he is weak. When the enemy has its strong time, it often pays off to strengthen your lines and hold a favorable defensive position. When its weak time is about to arise, your advance will push forth.

For example, elves might hold out a forest during a nightly orcish onslaught and advance on sunrise. You may even note that the computer AI actively retreats his orcs during day.

=== Experience ===

Over the course of a campaign, it is critical that you build up a seasoned force. Later scenarios will assume you have level 2 and 3 units available for recall.

Your units gain most experience points (XP) from killing an enemy unit (8XP per level of the unit killed). As such, it often makes sense to have your higher level units weaken an enemy, but cede the kill to a unit more in need of the XP. Healers in particular are often weak in combat and often need to 'steal' kills in this way to advance levels.

At the beginning (when you probably have no high level units), try to give most kills to a small handful of your units. This will fast-track them to becoming Level 2 units, and they can then shepherd others.

Don't neglect to earn your leader experience. You need to keep him safe, but if you coddle him too much he will be too low level to survive future scenarios anyway.

FAQ

2006-08-15T18:47:12Z

Luther: /* There's too much luck in this game! */

=Frequently Asked Questions=

== General ==

===What is Battle for Wesnoth?===
Battle for Wesnoth is a fantasy turn-based strategy game.

===What license is the game distributed under?===
The project is distributed under the [http://www.fsf.org/copyleft/gpl.html GPL]. All contributors retain copyright on the portions of the project that they contribute.

===How to get informed about new releases?===
Subscribe to new releases at [http://freshmeat.net/subscribe/38720/?url=%2Fprojects%2Fwesnoth%2F Freshmeat].

===A new version is out, but where is the download for [Windows, Mac OS, etc.]?===
The downloads are NOT part of the official project. The BFW team only releases the game's source code. Binary executables or applications are always contributed by community volunteers. If not for these volunteers, there would never be any downloads for us to enjoy. The volunteers compile the game and upload it on their own time, and sometimes they cannot do this in a timely fashion (or at all, at times) Although there are usual packagers designated for each operating system, there are times when other members of the community are asked to step in and contribute when the usual people cannot.

Every time a new version is released, the usual volunteers are always notified by the project leaders. '''Please refrain from making forum posts asking where your download is''' because it doesn't help anything - the packagers already know, and they will get to it as soon as they can. In the past, the Windows and Mac communities have come together to produce home-grown unofficial builds for the community to use, and the renewed interest in community and learning how to compile is generally a good thing.

===Why doesn't Wesnoth have my favorite feature?===
Because we are building this game for ourselves, to suit our own preferences. We're not building the game for you, in large part because this is our hobby, not our job; whether you like it or not is immaterial to us.
You may wonder, then, what the point is of soliciting ideas, as we do on the forum. We, the developers, have certainly come up with many good ideas on our own, but our players often do as well, and generally ones we don't think of ourselves. If a player comes up with an idea we like, we might implement it. Not because they asked for it, but because of its own merits as an addition to our game.

The beautiful thing about the license our game is distributed under, as compared to closed-source, commercial games, is that if you want that feature badly enough, you can take the code and art of our game and modify it yourself; you are free to re-use any work in Wesnoth, as long as you follow the rules of the [http://www.fsf.org/copyleft/gpl.html GPL]. From this, you can build a game exactly the way that you like. Just don't expect us to build that game for you. Building this game is our hobby, not our profession, and you did not pay us to make it; rather, we are the ones who have paid for it, in time and labor.

===Do you want help making this game? How can I help?===
Yes, we want your help. Whether you're a programmer, artist, musician, writer, translator, level designer, playtester, or just have some great suggestions, you're welcome to contribute. How? You can:
* join the [http://www.wesnoth.org/wiki/Project Project]
* share your point of view at the [http://www.wesnoth.org/forum/ Forum]
* talk with us on [irc://irc.wesnoth.org/wesnoth IRC]
* report bugs you find at [[ReportingBugs]]
* update the wiki
* play against us via the Multiplayer menu
* vote for Wesnoth at your favorite gaming web site
* Spread the word!

=== What are the system requirements? ===

We are not completely certain, but an x86 running at 333MHz with 128MB RAM should be adequate. Slower machines will have trouble scrolling large maps or processing AI turns with many units. See the [http://www.wesnoth.org/forum/viewtopic.php?t=7384 forum thread] about minimum and recommended system requirements.

=== I'm bored; how do I speed the game up? ===

There are several preferences you can change to shorten the time that the AI takes to make its moves. "Accelerated Speed" will make units move and fight faster. "Skip AI Moves" will not show the AI's units moving from hex to hex. Finally, you can turn off all combat animations via the "Show Combat" option on the Advanced tab.

=== My computer is too slow; how do I speed the game up? ===

First, turn off the music and sound effects. Turning off the color cursors will make your cursor respond faster. If scrolling the map is slow, run the game in "Full Screen" mode, not in a window. Turn off combat animations via the "Show Combat" option on the Advanced tab. You can try turning off halos and combat results, but this might make gameplay more difficult.

== Gameplay and Controls ==

=== How do I learn to play? ===

If you just want to jump right in, start the game and play the tutorial. If you like reading documentation, see [[WesnothManual]], which is also distributed as a PDF file. At any time while playing, you can select help from the menu button (or hit F1). The online help is quite extensive and provides information on terrains, weapons, traits, abilities, units and a good overview of how to play.

=== My unit leveled up but didn't improve. What happened? ===

This is called "After Maximum Level Advancement" or AMLA for short. While most level 0, 1, and 2 units can advance, some cannot. However, some level 3 units can advance to level 4, or even 5. You can see whether a unit can advance further by right clicking and selecting "description."

After a unit reaches the highest level it can get, every time it gains 100 experience it gains 3 hitpoints. It does not heal when this happens. This is a minor bonus so that experience gained by maxed out units is not altogether wasted. It is generally better to give experience to lower level units, rather than continue to advanced units that have reached their maximum level.

If the unit in question is the Necrophage, this is not a bug. The Necrophage eats the corpses of the dead, allowing it to periodically completely heal. Leveling into itself is how this is carried out.

=== I tried to trap an enemy with several weak units, but it still escaped. What happened? ===

Most units exert a zone of control (or ZOC). IF an enemy moves into one of the six adjacent hexes, the zone of control will prevent it from moving any farther. However some weak units are level 0, meaning they are so weak that they do not have a ZOC. You can still surround an enemy unit entirely with level 0 units to keep it from escaping, but if there is any gap in your ranks, it could escape.

Also, some units have the "skirmish" ability, which allows them to ignore ZOCs.

=== How can I see where an enemy unit can move next turn? ===

During you turn you can click on an enemy unit. Wesnoth will highlight all the hexes the unit can move to in the next turn. This is useful when trying to arrange your units to block an enemy's movement.

=== There's too much luck in this game! ===

Sooner or later, you will become frustrated when your archmage with four 70% attacks misses all four times. This does not mean that the AI is cheating or the random number generator is futzed. It means you are noticing random negative events more than positive ones. During the development of the game, many mathematicians have done sophisticated statistical analysis of the combat system. Likewise, programmers have examined the random number generator. Wesnoth has been deliberately designed so that the streaks of "bad" and "good" luck are a part of the gameplay.

Since Wesnoth is GPLed, it is possible that a new development team will someday "fork" the source and produce a version more like Heroes of Might & Magic, with no randomness. Until then, don't charge with your horsemen against rock trolls at night...

=== The (random unit) is overpowered/underpowered! ===

The development team has spent years tweaking the units in the game. Each unit has had its gold cost, attack types, combat damage, defensive values, resistances, upgrade paths, and other stats carefully scrutinized and loudly discussed in the forum. However, the game code and the units were being modified right up until the 1.0 release, so some unbalanced units may have slipped through.

If you have evidence to back up your claim, search the forum for past discussions about this unit, and then try posting.

=== The (random scenario) is too hard/easy! ===

See above answer about random units.

=== What do the different difficulty levels do? ===

That depends on the scenario. Usually, the opponent will get more money and be able to recruit higher-level units at higher difficulty levels, and you will have fewer turns available.

== Maps, Scenarios and Campaigns ==

=== How do I beat scenario _______ ? ===

If you are stuck on a scenario in a campaign, you'll probably find a walkthrough at [[MainlineScenarios]]. Or check out the "Strategies and Tips" forum at http://www.wesnoth.org/forum/viewforum.php?f=3

=== Are there any tools to help me create maps and scenarios? ===
Yes, there is a tool called wesnoth_editor. It is a normal map-editor that should be a good help for creating the plain maps. For creating the scenarios there already is a scenario-editor included in the mac build. But this editor is rather outdated and it exists only for MacOS X. At the moment some community members are working on creating a nice and working scenario editor. You can have a look at the [http://www.wesnoth.org/forum/viewtopic.php?t=6925 forum post] about this tool. You will also find more info at [[CampGen]].

=== How do I download user campaigns? ===
Choose "Campaigns" in the main Wesnoth menu. Then scroll down to the bottom and choose "Get More Campaigns..." or since 1.1.5 there is a "Get add-ons" button in the main menu. This connects you to the campaign server. In the campaign server you can view a list of all available campaigns and download them, as well as posting or deleting your own campaigns.

If you are behind a firewall you may not be able to connect to the campaign server. In this case try to download the campaign directly from the campaign server through the web interface at http://campaigns.wesnoth.org. If you know how to change your firewall settings, then you should open port 15003 (version 1.1.1 and up) or port 15002 (versions 1.1.0 and lower). For added security, you can restrict traffic over those ports to the campaign server's IP address (currently 129.241.104.165).

=== I already created a campaign and published it on the campaign server. How can I get translations for the campaign? ===
Just have a look at [[WesCamp]]. This project is the easiest way to get translations for your campaign. All the info you need you can find at [[WesCamp]].

===How do I place an object or unit on my map with the map editor?===
You can't. You need to make a multiplayer scenario file. There are more details on the [[BuildingMaps|maps]] page.

== Multiplayer ==

===How do i connect to a multiplayer server, when i sit behind a restrictive Firewall?===
You have to open port 14999 to play multiplayer games over the internet. For added security, you can restrict access to the server's IP address (currently 84.207.24.9 for the official server).

===How to find players for multiplayer game?===
Hang around for a while on multiplayer servers and you might find someone to play with. If you observe other people playing you will get informed when someone joins the servers. Maybe you find someone willing to play in the irc channel dedicated to mp: #wesnoth-mp at irc.freenode.net.
You can also join #wesnoth at irc.freenode.net.

===How can I make my computer into a dedicated Wesnoth server?===

To setup a dedicated Wesnoth server, you have to compile the game with the "--enable-server" flag, and after you install, simply run wesnothd from the console. This will start the server, listening on TCP port 15000. To compile the server only you can use the flags "--disable-game --enable server". If you aren't using a linux or mac operating system, there are a few ways you can compile on Windows...here is one way http://www.wesnoth.org/wiki/CompilingWesnoth/CrossCompiling

===Which versions of Wesnoth can play together?===

I'm on a MAC, and my friends are on XP. I would like to play together with them. Is this currently possible?

YES! All you need is to have the same version number.

For a list of Mac-XP-compatible games (including BfW) see: http://www.insidemacgames.com/forum/index.php?showtopic=21818

== Translations ==

===I selected an asian translation and am not able to see the letters correctly. What happened?===

Since the size of the necessary fonts is too large, you'll need to download them separately (if you don't already have them). After that, simply copy the font to the '''fonts/''' directory in your wesnoth installation.
* Chinese font: [ftp://cle.linux.org.tw/pub/fonts/ttf/unicode/Arphic/gkai00mp.ttf gkai00mp.ttf]
* Japanese font: [http://cvs.sourceforge.jp/cgi-bin/viewcvs.cgi/sqs-xml/sqs-font/sazanami-gothic.ttf sazanami-gothic.ttf]

If you have futher questions have a look at [[WesnothAsianLanguages|this]] page.

== Other Questions You Have ==

The best way to get answers to less-frequently asked questions is by visiting the [http://www.wesnoth.org/forum BFW forum]. There are plenty of people willing to help. Make sure you read ALL of the forum sticky notes and announcements before posting.