https://wiki.wesnoth.org/api.php?action=feedcontributions&user=Vultraz&feedformat=atomThe Battle for Wesnoth Wiki - User contributions [en]2024-03-29T09:34:27ZUser contributionsMediaWiki 1.31.16https://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=69442SpellingMistakes2022-03-17T13:43:54Z<p>Vultraz: </p>
<hr />
<div>'''Note:''' If you have a GitHub account, please submit typo reports [https://github.com/wesnoth/wesnoth/issues/new/choose on GitHub], rather than here. Thanks for your contribution!<br />
<br />
(If you don't already have an account, see https://github.com/wesnoth/wesnoth/blob/master/.github/ISSUE_TEMPLATE/text-typos-or-improvements.yml.)<br />
<br />
[[Category:Writing]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=CampaignWML&diff=66099CampaignWML2020-10-06T03:52:22Z<p>Vultraz: </p>
<hr />
<div>{{WML Tags}}<br />
<br />
<!--<br />
<br />
Dacyn and/or Invisible Philosopher -- please be careful<br />
you don't reduce the signal-to-noise ratio on the WML pages<br />
when editing! Eg. knowing that a tag is translatable is _important_<br />
for the 29 translations we have in progress. -- ott<br />
<br />
--><br />
<br />
This page describes how the campaign is displayed in the "Campaign" menu, and how it starts.<br />
<br />
==The [campaign] Tag==<br />
<br />
The following keys and tags are recognized in '''[campaign]''' tags:<br />
* '''id''': the internal campaign identifier used to classify saved games<br />
* '''icon''': the image displayed in the campaign selection menu<br />
* '''name''': (translatable) name displayed in the campaign selection menu<br />
* '''abbrev''': (translatable) abbreviation used as a prefix for savefile names made from this campaign<br />
* '''image''': the image shown in the information pane when this campaign is selected in the campaign selection menu (typically a transparent, 350×350 pixels portrait)<br />
* '''description''': (translatable) text shown in the information pane when this campaign is selected in the campaign selection menu<br />
* '''description_alignment''': {{DevFeature1.13|3}} The text alignment of the description. Choose between "left" (default), "center", or "right".<br />
* '''type''': campaign's type to specify if it should be visible in singleplayer, multiplayer or both. Possible values are "sp", "mp" and "hybrid". Defaults to "sp".<br />
* '''define'''='''''CAMPAIGN_SYMBOL''''' when this campaign is started, the preprocessor symbol '''''CAMPAIGN_SYMBOL''''' will be defined. See '''#ifdef''' in [[PreprocessorRef]] for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags '''[campaign]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''CAMPAIGN_SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Important note: starting with 1.7.13, [binary_path] does no longer need to be outside of the '''#ifdef ''CAMPAIGN_SYMBOL''''' block to make custom binary data available, which could easily cause overwrites. E.g. icon=data/add-ons/whatever/something.png is supposed to work. This seems to have been a bug since at least BfW 1.0 which means that practically all available examples of user made add-ons are wrong in this aspect.<br />
* '''extra_defines''': a comma(''',''') separated list of preprocessor symbols. Those symbols will be defined ''before'' any .cfg is preprocessed. Currently supported extra_defines are:<br />
<ul><br />
;ENABLE_ARMAGEDDON_DRAKE<br />
:allows the advancement ''Inferno Drake'' -> ''Armageddon Drake''<br />
;ENABLE_DWARVISH_ARCANISTER<br />
:allows the advancement ''Dwarvish Runemaster'' -> ''Dwarvish Arcanister''<br />
;ENABLE_DWARVISH_RUNESMITH<br />
:allows the advancement ''Dwarvish Fighter'' -> ''Dwarvish Runesmith''<br />
;DISABLE_GRAND_MARSHAL<br />
:disallows the advancement ''General'' -> ''Grand Marshal''<br />
;ENABLE_ANCIENT_LICH<br />
:allows the advancement ''Lich'' -> ''Ancient Lich''<br />
;ENABLE_DEATH_KNIGHT<br />
:allows the advancement ''Revenant'' -> ''Death Knight'<br />
;ENABLE_TROLL_SHAMAN<br />
:allows the advancement ''Troll Whelp'' -> ''Troll Shaman''<br />
;ENABLE_WOLF_ADVANCEMENT<br />
:allows the advancements ''Wolf'' -> ''Great Wolf'' -> ''Direwolf''<br />
;ENABLE_NIGHTBLADE {{DevFeature1.13|0}}<br />
:allows the advancement ''Orcish Slayer'' -> ''Orcish Nightblade''<br />
;ENABLE_PARAGON {{DevFeature1.15|1}}<br />
:allows the advancement ''Dune Blademaster'' -> ''Dune Paragon''<br />
;ENABLE_WOSE_SHAMAN {{DevFeature1.15|1}}<br />
:allows the advancement ''Wose'' -> ''Wose Shaman''<br />
</ul><br />
* '''difficulties''': a comma(''',''') separated list of preprocessor symbols, exactly one of which will be stored depending on the difficulty setting chosen when the campaign is started. The symbols '''EASY''', '''NORMAL''', and '''HARD''' are usually used, and there are several macros in utils.cfg (see [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg| Macro Reference]) which check for these values to set WML keys to different values depending on difficulty. If you use different difficulty symbols, you may need to define your own versions of these macros. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=.<br />
* '''difficulty_descriptions''': the menu of difficulties; this is a list of descriptions (see [[DescriptionWML]]) that correspond to different difficulty levels. Since each description is a menu option for a difficulty level, this must provide the same number of descriptions as there are levels in the ''difficulties'' list. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=<br />
* '''[difficulty]''': {{DevFeature1.13|2}} specifies a single campaign difficulty. The following keys are accepted:<br />
** '''define''': the preprocessor symbol defined when this difficulty is selected. Uses the same format as an entry in the old ''difficulties'' list.<br />
** '''image''': the image to display for this difficulty in the selection menu<br />
** '''label''': a flavor label describing this difficulty. Displayed second after the image<br />
** '''description''': a description of the difficulty, usually along the lines of "Beginner" or "Challenging". Displayed third after the image.<br />
** '''default''': whether this is the difficulty which will be selected by default when the difficulty selection menu is displayed.<br />
** '''auto_markup''': {{DevFeature1.15|0}} By default, the description is shown in small, gray text within parentheses. Setting '''auto_markup=no''' disables these, so no markup will be applied implicitly. Any markup in '''description''' will be honored regardless of this setting.<br />
* '''allow_difficulty_change''': Allows difficulty switching during an ongoing campaign. Default:yes<br />
* '''first_scenario''': the ID of the first scenario in the campaign; see ''id'' in [[ScenarioWML]]<br />
* '''[options]''': {{DevFeature1.13|1}} Allows configuration options to be displayed to the user, see [[OptionWML]]<br />
* '''rank''': a number that determines the order of campaigns in the campaign selection menu. Lower ''rank'' campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 10 from 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400. (Note: This replaces an older convention that topped out at 50.) {{DevFeature1.14|6}} a number that determines the order of campaigns in the campaign selection menu. Lower rank campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 5 from 0 to 249, with 0-49 for Rookie campaigns, 50-99 for Novice campaigns, 100-149 for Intermediate campaigns, 150-199 for Hard campaigns, and 200-249 for Expert campaigns; if you specify this, it should not be less than 300.<br />
* '''start_year''': a string that determines the order of campaigns when the campaign selection menu is sorted by date. The date needs a year number and an epoch, for example '''20 BW''', '''20 YW''', '''20 BF''' or '''20 AF'''. In Wesnoth 1.14, this is the only place in which this date-parsing is used.<br />
* '''end_year''': a string that helps determine the order of campaigns when two campaigns have the same '''start_year'''. Ignored if '''start_year''' is not set.<br />
* '''year''': shortcut for specifying both '''start_year''' and '''end_year''', for campaigns that happen inside a single calendar year. Ignored if '''start_year''' is given. <br />
* '''[about]''': inserts your own credits into the game's list of credits. See below for syntax.<br />
* '''end_credits''': Whether to display the credits screen at the end of the campaign. Defaults to ''yes''.<br />
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End".<br />
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. {{DevFeature1.15|6}} This value is capped at 5000 (5 seconds).<br />
* '''[event]''': {{DevFeature1.13|2}} events placed here will be automatically inserted into all scenarios of the campaign.<br />
<br />
The following keys are additionally recognized in multiplayer:<br />
* '''min_players''': Minimum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to 2.<br />
* '''max_players''': Maximum number of players which the campaign supports. This only serves to inform users when choosing a campaign. Defaults to either '''min_players''' or 2, whichever is higher.<br />
* '''allow_era_choice''': Whether to allow era selection (when set to ''yes'') or hide it and use a default one when creating a game (when set to ''no''). Defaults to ''yes''.<br />
* '''require_campaign''': Whether clients are required to have this campaign installed beforehand to be allowed join a game using this campaign. Possible values 'yes' (the default) and 'no'.<br />
<br />
== Campaign credits ==<br />
<br />
The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs. There can be any number of '''[about]''' tags inside a '''[campaign]''' tag. The '''[about]''' tag has the following keys:<br />
* '''title''': (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits<br />
* '''text''': (translatable, but you probably won't want to make it such) smaller text which is displayed before the contributor names<br />
* '''[entry]''': Contains information about a single contributor. Only the ''name'' key will be used in-game, the other three keys are for display on the [[Credits]] page ('''note:''' the values of these keys will only display on the Credits page for mainline campaigns; they will not display for UMC campaigns)<br />
** '''name''': The name of the contributor<br />
** '''comment''': Optional short note about what that person did<br />
** '''email''': Optional email address<br />
** '''wikiuser''': Optional, the user name on the wiki<br />
<br />
== See Also ==<br />
<br />
* [[PreprocessorRef]]<br />
* [[ScenarioWML]]<br />
* [[ReferenceWML]]<br />
* [[PblWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=64970SpellingMistakes2019-10-19T22:54:38Z<p>Vultraz: </p>
<hr />
<div>'''Note:''' If you have a GitHub account, please submit typo reports [https://github.com/wesnoth/wesnoth/issues/new/choose on GitHub], rather than here. Thanks for your contribution!<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
[[Category:Writing]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=64241Template:DevDownload2019-09-04T10:31:27Z<p>Vultraz: </p>
<hr />
<div><noinclude><br />
== Development (1.15 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Previous Version}}} | group=wesnoth | version=1.15.0 | filename=wesnoth-1.15.0.tar.bz2 | size=458.1 MB | hash=685257c7d31ff7ebe026c3b8e8c381d9b05a72a754640028755436210e06fefc}}<br />
* {{DownloadItem | label={{{2|Current Version}}} | group=wesnoth | version=1.15.1 | filename=wesnoth-1.15.1.tar.bz2 | size=458.1 MB | hash=854726ec68dcb26f78f65b01a90b3bc51fd985598e59c7cc2ef72999ff2366e8}}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Previous Version}}} | group=wesnoth | version=1.15.0 | filename=wesnoth-1.15.0-win32.exe | size=422.9 MB | hash=17b8c1a1cea8742bca17b734c15d81b454d95a8a9e8cc72979316eb4e5c5d957}}<br />
* {{DownloadItem | label={{{2|Current Version}}} | group=wesnoth | version=1.15.1 | filename=wesnoth-1.15.1-win32.exe | size=423.0 MB | hash=b201177a6501c125e173c473f3061054849f79151b46808a3e6cabd41515ad7b}}<br />
<br />
==== macOS (10.8 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Previous Version}}} | group=wesnoth | version=1.15.0 | filename=Wesnoth_1.15.0.dmg | size=471.5 MB | hash=85ede0eae3bc2f04b81baf458697bd8c017bdffaa5aaa5674654ad51e6c89343}}<br />
* {{DownloadItem | label={{{2|Current Version}}} | group=wesnoth | version=1.15.1 | filename=Wesnoth_1.15.1.dmg | size=471.3 MB | hash=710ddbf03c979f6c3aa64e39a8062fd540cf42c95a30fd18c0d69c607733915e}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:StableDownload&diff=60964Template:StableDownload2019-04-22T20:09:48Z<p>Vultraz: </p>
<hr />
<div><noinclude><br />
== Stable (1.14 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.7 | filename=wesnoth-1.14.7.tar.bz2 | size=452.7 MB | hash=475e6ce3720edf76cfc3a9b9ac015067d473a46d164dcc4406b3c8f7d8dc5e48}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.6 | filename=wesnoth-1.14.6.tar.bz2 | size=451.8 MB | hash=45d2a05320e145b0b1bc9d16d68391945a98375c910a0ea7720e613bf867832b}}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.7 | filename=wesnoth-1.14.7-win32.exe | size=408.2 MB | hash=31b2acfa65cb383012c04c8adbe903b6c3a6ef6a7a32d02a5c49e2e8fcd8ca26}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.6 | filename=wesnoth-1.14.6-win32.exe | size=408.3 MB | hash=0741a229e1a7da84392b7ce6424fdca3ccb0d84588ac86233d64f4102dfb973e}}<br />
<br />
==== macOS (10.8 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.7 | filename=Wesnoth_1.14.7a.dmg | size=466.0 | hash=9f72b882d7db103280c796a92fb23ae65278a4fcaf9353738baa9e3514746755}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.6 | filename=Wesnoth_1.14.6.dmg | size=465.2 | hash=da59233f1e3648fc2aa8931dd8d472a6097a09c3bf2fe45895c2cad62f107fc0}}</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=ImagePathFunctionWML&diff=60500ImagePathFunctionWML2019-03-10T14:52:37Z<p>Vultraz: Vultraz moved page ImagePathFunctionWML to ImagePathFunctions</p>
<hr />
<div>#REDIRECT [[ImagePathFunctions]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=ImagePathFunctions&diff=60499ImagePathFunctions2019-03-10T14:52:36Z<p>Vultraz: Vultraz moved page ImagePathFunctionWML to ImagePathFunctions</p>
<hr />
<div>Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).<br />
<br />
If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester''. It is available on the 1.9, 1.10, 1.11, and 1.12 add-on servers.<br />
<br />
All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.<br />
That is, stuff like "units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)" would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.<br />
<br />
== Changing the colors ==<br />
<br />
=== BLEND: Color-blend function ===<br />
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.<br />
<br />
'''~BLEND(r,g,b,o)'''<br />
<br />
The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.<br />
<br />
=== BW: Black and White Function ===<br />
{{devfeature1.13|1}}<br />
May be used to convert the image to pure black and white, without grey pixels. <br />
<br />
'''~BW(threshold)'''<br />
* ''threshold'': a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.<br />
<br />
=== CS: Color-shift function ===<br />
Performs simple per-channel color shifts by adding the arguments to the respective color channels.<br />
<br />
''Multi-channel:'' '''~CS(r,g,b)'''<br />
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''<br />
<br />
The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.<br />
<br />
The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.<br />
<br />
=== GS: Greyscale Function ===<br />
May be used to greyscale the image (turn to black and white)<br />
<br />
'''~GS( )'''<br />
<br />
=== L: Lightmap color-shift function ===<br />
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.<br />
<br />
'''~L(lightmap)'''<br />
<br />
For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.<br />
<br />
The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully grey image (RGB = 128,128,128) and any non-grey pixel will shift the colors of the original.<br />
<br />
Note that the lightmap will be scaled to the same dimensions as the original image.<br />
<br />
=== NEG: Negative Function ===<br />
{{devfeature1.13|0}}<br />
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.<br />
<br />
'''~NEG( )'''<br />
<br />
Inverts the image, giving it an effect like a photographic negative.<br />
<br />
{{devfeature1.13|1}} '''~NEG(''' ''threshold'' ''')'''<br />
<br />
If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as ''solarization''.<br />
Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.<br />
<br />
{{devfeature1.13|1}} '''~NEG(''' ''threshold_red, threshold_green, threshold_blue'' ''')'''<br />
<br />
If a channel has a value greater than the corresponding threshold, the channel will be inverted.<br />
Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.<br />
<br />
=== PAL: Palette-switch Function ===<br />
May be used to change colors in an image following the specifications of a source and target (new) palette.<br />
<br />
'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''<br />
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.<br />
*''target color palette'' - the new palette to take the place of the source colors in the image.<br />
<br />
=== RC: Re-Color Function ===<br />
May be used to change some colors in an image.<br />
<br />
'''~RC(''' ''source color palette'' '''>''' ''color range ID'' ''')'''<br />
*''source color palette'' - the first parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.<br />
*''color range ID'' - this is the second parameter, signifying the ID of a color range defined in the file ''data/core/team-colors.cfg'' (or it may be a custom ID for a color range defined locally). <br />
<br />
==== Example ====<br />
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:<br />
<br />
[message]<br />
speaker=narrator<br />
image=units/elves-wood/captain.png~RC(magenta>green)<br />
message=_ "Now I am on the green team."<br />
[/message]<br />
<br />
The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.<br />
<br />
=== SEPIA: Sepia Function ===<br />
{{devfeature1.13|0}}<br />
May be used to give to the image a sepia tint (like in old pictures).<br />
<br />
'''~SEPIA()'''<br />
<br />
=== SWAP: Channel Swap Function ===<br />
{{devfeature1.13|1}}<br />
May be used to swap the RGBA channels of an image.<br />
<br />
'''~SWAP(''' ''r, g, b'' ''')'''<br />
'''~SWAP(''' ''r, g, b, a'' ''')'''<br />
* ''r'', ''g'', ''b'', ''a'': each of these arguments may have a value equal to ''red'', ''green'', ''blue'' or ''alpha''. The RGBA channels of the original image will be exchanged accordingly (for example, <tt>~SWAP(blue,green,red)</tt> swaps the blue and red channels).<br />
<br />
=== TC: Team-Color Function ===<br />
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''<br />
<br />
'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''<br />
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).<br />
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.<br />
<br />
== Transformations ==<br />
<br />
=== FL: Flip Function ===<br />
May be used to flip an image horizontally and/or vertically.<br />
<br />
'''~FL(''' ''optional argument list'' ''')'''<br />
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.<br />
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizantally.<br />
*if the argument list is empty, the image will only be flipped horizontally.<br />
<br />
=== ROTATE: Rotate Function ===<br />
May be used to rotate an image by a multiple of 90 degrees.<br />
<br />
'''~ROTATE(''' ''degrees'' ''')'''<br />
* ''degrees'' - The number of degrees by which the image will be rotated. This must be a multiple of 90. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)<br />
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.<br />
<br />
=== SCALE: Image-scaling function ===<br />
Scales a graphic up or down.<br />
<br />
'''~SCALE( ''new_width'', ''new_height'' )<br />
<br />
The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.<br />
<br />
=== SCALE_INTO function ===<br />
{{DevFeature1.13|5}}<br />
<br />
Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.<br />
<br />
=== SCALE_SHARP function ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)<br />
<br />
'''~SCALE_SHARP(200,300)'''<br />
<br />
=== SCALE_INTO_SHARP function ===<br />
{{DevFeature1.13|5}}<br />
<br />
Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear intorpolation.<br />
<br />
=== XBRZ function ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.<br />
<br />
'''~XBRZ(n)'''<br />
<br />
== Cut-and-paste ==<br />
<br />
=== BLIT: Blit Function ===<br />
Blit the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)<br />
<br />
'''~BLIT(src,x,y)'''<br />
* ''src'': an image file used as source for the blit, other image path functions can be used there.<br />
* ''x'',''y'': top-left corner coordinates where to blit. Must be greater or equal than zero. If missing assume (0,0).<br />
<br />
=== CROP: Crop Function ===<br />
Extracts a rectangular section of an image file.<br />
<br />
'''~CROP(x,y,width,height)'''<br />
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.<br />
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.<br />
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.<br />
<br />
=== MASK: Mask Function ===<br />
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.<br />
<br />
'''~MASK(mask,x,y)'''<br />
* ''mask'': an image file used as mask, other image path functions can be used there.<br />
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).<br />
<br />
Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image. <br />
<br />
== Opacity ==<br />
<br />
=== ADJUST_ALPHA ===<br />
<br />
{{DevFeature1.13|?}}<br />
<br />
Alters the alpha of the image according to a WFL formula. The formula must output an integer from 0 to 255 giving the alpha across the canvas. It is evaluated for every pixel and may use the following variables: x, y, red, green, blue, alpha, width, height. {{DevFeature1.15|0}} The variables u and v are also supported now, evaluating to normalized texture coordinates (in the range 0..1); these are equivalent to <tt>x/width</tt> and <tt>y/height</tt> respectively.<br />
<br />
'''~ADJUST_ALPHA(formula)'''.<br />
<br />
=== O: Opacity modifying function ===<br />
Changes an image's opacity at render time.<br />
<br />
'''~O( ''factor or percentage%'' )'''<br />
<br />
If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).<br />
<br />
Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.<br />
<br />
=== PLOT_ALPHA ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.<br />
<br />
'''~PLOT_ALPHA()'''<br />
<br />
=== WIPE_ALPHA ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.<br />
<br />
'''~WIPE_ALPHA()'''<br />
<br />
=== Background coloring function ===<br />
Sets the color of all the (semi-)transparent pixels of the image.<br />
<br />
'''~BG(r,g,b)'''<br />
<br />
== Miscellaneous ==<br />
<br />
=== BL: Blurring function ===<br />
Blurs a graphic at render time using the same algorithm used for in-game dialogs.<br />
<br />
'''~BL( ''radius'' )'''<br />
<br />
=== DARKEN: Overlay function ===<br />
{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-dark.png) call instead.<br />
<br />
Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.<br />
<br />
'''~DARKEN()'''<br />
<br />
=== BRIGHTEN: Overlay function ===<br />
{{DevFeature1.13|7}} This function has been removed. Use a ~BLIT(misc/tod-bright.png) call instead.<br />
<br />
Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.<br />
<br />
'''~BRIGHTEN()'''<br />
<br />
=== CHAN: General function ===<br />
<br />
{{DevFeature1.13|?}}<br />
<br />
This function allows you to do pretty much anything. It takes up to four comma-separated formulas, one each for the red, green, blue, and alpha channels. Each formula functions exactly the same as the formula for '''ADJUST_ALPHA''', but the output integer is used for the corresponding channel rather than always the alpha channel.<br />
<br />
'''~CHAN(formula, formula, formula)'''<br />
<br />
=== NOP: Null function ===<br />
Does nothing.<br />
<br />
'''~NOP()'''<br />
<br />
== See Also ==<br />
<br />
* [[FancyAddonIcons]] - Tips and tricks for advanced Image Path Function manipulation<br />
* [[DataURI]] - An image path may also contain the image directly, as a Base64 encoded string<br />
<br />
[[Category:WML Reference]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:StableDownload&diff=60330Template:StableDownload2019-02-26T23:56:57Z<p>Vultraz: </p>
<hr />
<div><noinclude><br />
== Stable (1.14 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.6 | filename=wesnoth-1.14.6.tar.bz2 | size=451.8 MB | hash=45d2a05320e145b0b1bc9d16d68391945a98375c910a0ea7720e613bf867832b}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.5 | filename=wesnoth-1.14.5.tar.bz2 | size=450.8 MB | hash=05317594b1072b6cf9f955e3a7951a28096f8b1e3afed07825dd5a219c90f7cd}}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.6 | filename=wesnoth-1.14.6-win32.exe | size=408.3 MB | hash=0741a229e1a7da84392b7ce6424fdca3ccb0d84588ac86233d64f4102dfb973e}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.5 | filename=wesnoth-1.14.5-win32.exe | size=408.4 MB | hash=8cc97ce344b07179df210ba6139124b53134d11e8ab24efe7121be88db8f5543}}<br />
<br />
==== macOS (10.8 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.6 | filename=Wesnoth_1.14.6.dmg | size=465.2 | hash=da59233f1e3648fc2aa8931dd8d472a6097a09c3bf2fe45895c2cad62f107fc0}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.5 | filename=Wesnoth_1.14.5.dmg | size=472.7 | hash=df4b728c896e0927f5e1caa0fb07da701830205f1c01682b90ac14927019a965}}</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:StableDownload&diff=60329Template:StableDownload2019-02-26T23:54:22Z<p>Vultraz: /* Stable (1.14 branch) */</p>
<hr />
<div><noinclude><br />
== Stable (1.14 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.6 | filename=wesnoth-1.14.6.tar.bz2 | size=450.8 MB | hash=45d2a05320e145b0b1bc9d16d68391945a98375c910a0ea7720e613bf867832b}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.5 | filename=wesnoth-1.14.5.tar.bz2 | size=450.8 MB | hash=05317594b1072b6cf9f955e3a7951a28096f8b1e3afed07825dd5a219c90f7cd}}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.6 | filename=wesnoth-1.14.6-win32.exe | size=408.4 MB | hash=0741a229e1a7da84392b7ce6424fdca3ccb0d84588ac86233d64f4102dfb973e}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.5 | filename=wesnoth-1.14.5-win32.exe | size=408.4 MB | hash=8cc97ce344b07179df210ba6139124b53134d11e8ab24efe7121be88db8f5543}}<br />
<br />
==== macOS (10.8 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.6 | filename=Wesnoth_1.14.6.dmg | size=472.7 | hash=da59233f1e3648fc2aa8931dd8d472a6097a09c3bf2fe45895c2cad62f107fc0}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.5 | filename=Wesnoth_1.14.5.dmg | size=472.7 | hash=df4b728c896e0927f5e1caa0fb07da701830205f1c01682b90ac14927019a965}}</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=LuaMapGenerator&diff=60092LuaMapGenerator2018-12-12T01:06:50Z<p>Vultraz: Vultraz moved page LuaMapGeneratorWML to LuaMapGenerator without leaving a redirect: We shouldn't call this "WML"</p>
<hr />
<div>{{DevFeature1.15}} The page describes the api available for lua map generators that is differnt from the ingame lua api.<br />
<br />
<br />
<br />
==== wesnoth.find_path ====<br />
* '''wesnoth.find_path(''src'', ''dst'', ''cost_function'', ''mapsize_x'', ''mapsize_y'', ''include_border'')'''<br />
<br />
Behaves slightly differntly than in the ingame lua api with the same name in particular it no longer accepts unit arguments and explicitly nees the map size.<br />
<br />
<br />
==== wesnoth.create_map ====<br />
* '''wesnoth.create_map (''map_data'')'''<br />
* '''wesnoth.find_path(''width'', ''height'', ''terrain'')'''<br />
<br />
Creates a gamemap object, which has the following functions and properties<br />
* '''get_terrain(loc)'''<br />
* '''set_terrain(loc, terrain)'''<br />
* '''get_locations(filter, locs_to_check)'''<br />
* '''get_tiles_radius(locations, filter_radius)'''<br />
* '''terrain_mask(x_offset, y_offset, data, optional_argeument_table)'''<br />
* '''width''' number<br />
* '''height''' number<br />
* '''data''' string<br />
<br />
The filters about use custom lua filter objects that can be constructed via wesnoth.create_filter<br />
<br />
==== wesnoth.create_filter ====<br />
creates a lua filter object from a table describing a lua terrainfilter, this is similar but not the same as wml filters, compiling these into lua objects makes it much faster. A lua filtertable is a table which at index 1 has the type of the filter and the rest depends on the type of the filter, for example ''wesnoth.create_filter { "terrain", "K*"} " will create a filter that matches keeps. THe follwing types of theilter are known:<br />
* '''{ "terrain", terraincode }''' matches for terrain terraincode<br />
* '''{ "all", <filter1>, <filter2>, <filter3>, ... }''' matches when all the subfilters match<br />
* '''{ "any", <filter1>, <filter2>, <filter3>, ... }''' matches when any the subfilters match<br />
* '''{ "none", <filter1>, <filter2>, <filter3>, ... }''' matches when none the subfilters match<br />
* '''{ "notall", <filter1>, <filter2>, <filter3>, ... }''' matches when not all the subfilters match<br />
* '''{ "adjacent", <subfilter>, [count = <count>], [adjacent = <adjacent>]}''' matches when count adjacent tiles matchthe subfilter ('adjacent=' defaults to 'n,nw,sw,s,se,ne')<br />
* '''{ "radius", <radius>, <subfilter>, filter_radius = <filter_radius> }''' radius: number, filter_radius: subfilter.<br />
<br />
It is reccomended to create a helper function for filter construction for example:<br />
<br />
<syntaxhighlight lang='lua'><br />
f = {<br />
terrain = function(terrain)<br />
return { "terrain", terrain }<br />
end,<br />
all = function(...)<br />
return { "all", ... }<br />
end,<br />
any = function(...)<br />
return { "any", ... }<br />
end,<br />
none = function(...)<br />
return { "none", ... }<br />
end,<br />
adjacent = function(f, ad, count)<br />
return { "adjacent", f, adjacent = ad, count = count }<br />
end,<br />
radius = function(r, f, f_r)<br />
return { "radius", r, f, filter_radius = f_r}<br />
end,<br />
}<br />
<br />
wesnoth.create_filter(<br />
f.all(<br />
f.terrain("K*"),<br />
f.radius(4, f.terrain("^V*"))<br />
)<br />
)<br />
</syntaxhighlight><br />
for a filter that matches keepos that are at most distance 4 to a village<br />
<br />
==== wesnoth.generate_default_map ====<br />
'''wesnoth.generate_default_map(''width'', ''height'', ''cfg'')'''<br />
''cfg'' is a wml table similar to the default map generators argument it supports the wml subtables as the defautl map generator and the following attributes:<br />
<br />
<br />
* '''nplayers''' the number of players-<br />
* '''nvillages''' the prefered number of villgaes on the map, unlike the default mapgen this is not 'per thousand'<br />
* '''iterations''' like the [generator] attribute the with same name, note that unliek the original value this is not divided by 10 for island maps.<br />
* '''hill_size''' like the [generator] attribute the with same name. <br />
* '''castle_size''' like the [generator] attribute the with same name.<br />
* '''island_size''' The size of the island usually up to half the width of the map.<br />
* '''island_off_center''' offset to place the island, used in particular for coastal maps.<br />
* '''max_lakes''' like the [generator] attribute the with same name, note that unliek the original value this is not divided by 10 for island maps.<br />
* '''link_castles''' whether to connect castles by roads<br />
* '''show_labels''' whether to generate labels.<br />
* '''seed''' the random seed.</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=LuaWML&diff=59855LuaWML2018-07-07T08:26:09Z<p>Vultraz: We use Lua 5.3 now</p>
<hr />
<div>{{WML Tags}}<br />
<br />
== The '''[lua]''' tag ==<br />
<br />
This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.3] language.<br />
<br />
It is also possible to put this tag inside a [scenario] [[ScenarioWML]], those tags will be executed immediately when the lua engine loads which is even before the scenario preload event is fired.<br />
<br />
{{DevFeature1.13|0}}<br />
[lua] is now also allowed in [era] and [modification] those [lua] tags are then copied into the [scenario]/[multiplayer] when it is played just like [event]s inside [era] or [modification]<br />
<br />
The tag supports only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.<br />
<br />
<syntaxhighlight lang='wml'><br />
[lua]<br />
code = << wesnoth.message "Hello World!" >><br />
[/lua]<br />
</syntaxhighlight><br />
<br />
The Lua kernel can also be accessed from the [[CommandMode|command mode]]:<br />
<br />
:lua local u = wesnoth.get_units({ id = "Konrad" })[1]; u.moves = 5<br />
<br />
The '''[args]''' sub-tag can be used to pass a WML object to the script via its variadic local variable "'''...'''".<br />
<br />
<syntaxhighlight lang='wml'><br />
[lua]<br />
code = << local t = ...; wesnoth.message(tostring(t.text)) >><br />
[args]<br />
text = _ "Hello world!"<br />
[/args]<br />
[/lua]<br />
</syntaxhighlight><br />
<br />
== Global environment ==<br />
<br />
All the Lua scripts of a scenario share the same global environment (aka Lua state). For instance, a function defined in an event can be used in all the events that happen after it.<br />
<br />
<syntaxhighlight lang='wml'><br />
[event]<br />
name = preload<br />
first_time_only = no<br />
[lua]<br />
code = <<<br />
function narrator(t)<br />
-- Behave like the [message] tag.<br />
wesnoth.fire("message",<br />
{ speaker = "narrator", message = t.sentence })<br />
end<br />
>><br />
[/lua]<br />
[/event]<br />
<br />
[event]<br />
name = turn 1<br />
[lua]<br />
code = << narrator(...) >><br />
[args]<br />
sentence = _ "Hello world!"<br />
[/args]<br />
[/lua]<br />
[lua]<br />
code = << narrator(...) >><br />
[args]<br />
sentence = _ "How are you today?"<br />
[/args]<br />
[/lua]<br />
[/event]<br />
</syntaxhighlight><br />
<br />
In the example above, the redundant structure could be hidden behind macros. But it may be better to simply define a new WML tag.<br />
<br />
<syntaxhighlight lang='wml'><br />
[event]<br />
name = preload<br />
first_time_only = no<br />
[lua]<br />
code = <<<br />
-- The function is now placed in the wesnoth.wml_actions table<br />
-- The tag is [narrator], same as the function name<br />
function wesnoth.wml_actions.narrator(t)<br />
-- Behave like the [message] tag.<br />
wesnoth.fire("message",<br />
{ speaker = "narrator", message = t.sentence })<br />
end<br />
>><br />
[/lua]<br />
[/event]<br />
<br />
[event]<br />
name = turn 1<br />
[narrator]<br />
sentence = _ "Hello world!"<br />
[/narrator]<br />
[narrator]<br />
sentence = _ "How are you today?"<br />
[/narrator]<br />
[/event]<br />
</syntaxhighlight><br />
<br />
The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea. The only time assigning global variables (including function definitions) makes sense is in a [lua] block directly in [scenario] or during a [[EventWML#Predefined 'name' Key Values|preload]] event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.<br />
<br />
The global environment initially contains the following modules: [http://www.lua.org/manual/5.1/manual.html#5.1 basic] (no name), [http://www.lua.org/manual/5.1/manual.html#5.4 string], [http://www.lua.org/manual/5.1/manual.html#5.5 table], and [http://www.lua.org/manual/5.1/manual.html#5.6 math]. A '''wesnoth''' module is also available, it provides access to the [[#Interface to the C++ engine|C++ engine]]. Additionally, the functions clock, date, time and difftime from the [http://www.lua.org/manual/5.1/manual.html#5.8 os] library (keep in mind that they aren't multiplayer- and replay-safe), as well as traceback from the [http://www.lua.org/manual/5.1/manual.html#5.9 debug] library are also available.<br />
<br />
At the start of a script, the variadic local variable '''...''' (three dots) is a proxy table representing [[#Encoding WML objects into Lua tables|WML data]]. This table is the content of the '''[args]''' sub-tag of the '''[lua]''' tag, if any.<br />
<br />
== Examples ==<br />
<br />
The following WML event is taken from Wesnoth' tutorial. It will serve as an example to present how Lua scripts are embedded into Wesnoth. The event is fired whenever a unit from side 1 (that is, the hero controlled by the user) moves to a tile that is not the one set in the WML variable ''target_hex''.<br />
<br />
<syntaxhighlight lang='wml'><br />
# General catch for them moving to the wrong place.<br />
[event]<br />
name=moveto<br />
first_time_only=no<br />
[allow_undo][/allow_undo]<br />
[filter]<br />
side=1<br />
[/filter]<br />
<br />
[if]<br />
[variable]<br />
name=target_hex.is_set<br />
equals=yes<br />
[/variable]<br />
[then]<br />
[if]<br />
[variable]<br />
name=x1<br />
equals=$target_hex.x<br />
[/variable]<br />
[variable]<br />
name=y1<br />
equals=$target_hex.y<br />
[/variable]<br />
[then]<br />
[/then]<br />
[else]<br />
[redraw][/redraw]<br />
[message]<br />
speaker=narrator<br />
message=_ "*Oops!<br />
You moved to the wrong place! After this message, you can press 'u' to undo, then try again." +<br />
_ "<br />
*Left click or press spacebar to continue..."<br />
[/message]<br />
[/else]<br />
[/if]<br />
[/then]<br />
[/if]<br />
[/event]<br />
</syntaxhighlight><br />
<br />
A Lua script that performs the same action is presented below.<br />
<br />
<syntaxhighlight lang='wml'><br />
[event]<br />
name=moveto<br />
first_time_only=no<br />
[allow_undo][/allow_undo]<br />
[filter]<br />
side=1<br />
[/filter]<br />
<br />
[lua]<br />
code = <<<br />
local event_data = wesnoth.current.event_context<br />
if V.target_hex.is_set and<br />
(event_data.x1 ~= V.target_hex.x or event_data.y1 ~= V.target_hex.y)<br />
then<br />
W.redraw()<br />
narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")<br />
end<br />
>><br />
[/lua]<br />
[/event]<br />
</syntaxhighlight><br />
<br />
Here is a more detailed explanation of the Lua code. Its first line<br />
<br />
<syntaxhighlight lang='lua'><br />
local event_data = wesnoth.current.event_context<br />
</syntaxhighlight><br />
<br />
puts the event data into the ''event_data'' local variable. Since it is a ''moveto'' event, the ''event_data'' table contains the destination of the unit in the ''x1'' and ''y1'' fields.<br />
<br />
The next two lines then test<br />
<br />
<syntaxhighlight lang='lua'><br />
if V.target_hex.is_set and<br />
(event_data.x1 ~= V.target_hex.x or event_data.y1 ~= V.target_hex.y)<br />
</syntaxhighlight><br />
<br />
whether the variable ''V.target_hex'' matches the event parameters. Since ''V'' is not a local variable, it is taken from the global environment. Usually, variables from the global environment are not persistent (they get lost on reloading), so it shouldn't be used to store data. In order to have an easy way to access the usual persistent Wml variables, the global variable ''V'' was mapped to the storage of WML variables by the following ''preload'' event.<br />
<br />
<syntaxhighlight lang='wml'><br />
[event]<br />
name=preload<br />
first_time_only=no<br />
[lua]<br />
code = <<<br />
H = wesnoth.require "lua/helper.lua"<br />
-- skipping some other initializations<br />
-- ...<br />
V = H.set_wml_var_metatable {}<br />
>><br />
[/lua]<br />
[/event]<br />
</syntaxhighlight><br />
<br />
Without a prelude redirecting ''V'', the conditional would have been written<br />
<br />
<syntaxhighlight lang='lua'><br />
if wesnoth.get_variable("target_hex.is_set") and<br />
(event_data.x1 ~= wesnoth.get_variable("target_hex.x") or event_data.y1 ~= wesnoth.get_variable("target_hex.y")<br />
</syntaxhighlight><br />
<br />
The body of the conditional then performs the [[InterfaceActionsWML#Other interface tags|[redraw]]] action.<br />
<br />
<syntaxhighlight lang='lua'><br />
W.redraw()<br />
</syntaxhighlight><br />
<br />
Again, this short syntax is made possible by a line of the prelude that makes ''W'' a proxy for performing WML actions.<br />
<br />
<syntaxhighlight lang='lua'><br />
W = H.set_wml_action_metatable {}<br />
</syntaxhighlight><br />
<br />
Without this shortcut, the first statement would have been written<br />
<br />
<syntaxhighlight lang='lua'><br />
wesnoth.fire("redraw")<br />
</syntaxhighlight><br />
<br />
Finally the script displays a message by<br />
<br />
<syntaxhighlight lang='lua'><br />
narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")<br />
</syntaxhighlight><br />
<br />
The ''narrator_says'' function is defined in the prelude too, since the construct behind it occurs several times in the tutorial. In plain WML, macros would have been used instead. The definition of the function is<br />
<br />
<syntaxhighlight lang='lua'><br />
function narrator_says(m)<br />
W.message { speaker="narrator",<br />
message = m .. _ "\n*Left click or press spacebar to continue..." }<br />
end<br />
</syntaxhighlight><br />
<br />
The function fires a [[InterfaceActionsWML#.5Bmessage.5D|[message]]] action and passes a WML object containing the usual two fields to it. The second field is initialized by concatenating the function argument with another string. Both strings are prefixed by the ''_'' symbol to mark them as translatable. (Note that ''_'' is just a unary function, not a keyword.) Again, this is made possible by a specific line of the prelude:<br />
<br />
<syntaxhighlight lang='lua'><br />
_ = wesnoth.textdomain "wesnoth-tutorial"<br />
</syntaxhighlight><br />
<br />
A longer translation of the tutorial is available at [https://gna.org/patch/download.php?file_id=5483].<br />
<br />
== Interface to the engine and helper functions ==<br />
<br />
Functionalities of the game engine are available through the functions contained in the '''wesnoth''' global table. Some of these functions return proxy tables. Writes to fields marked "read-only" are ignored. The '''__cfg''' fields return plain tables; in particular, writes do not modify the original object, and reads return the values from the time the dump was performed.<br />
<br />
Some helper functions are provided by the '''lua/helper.lua''' library. They are stored inside a table that is returned when loading the library with [[LuaWML:Files#wesnoth.require|wesnoth.require]].<br />
<br />
<syntaxhighlight lang='lua'><br />
helper = wesnoth.require "lua/helper.lua"<br />
</syntaxhighlight><br />
<br />
=== WML variables ===<br />
<br />
* [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]]<br />
* [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]]<br />
* [[LuaWML:Variables#wesnoth.get_all_vars|wesnoth.get_all_vars]] {{DevFeature1.13|0}}<br />
* [[LuaWML:Variables#wesnoth.wml_matches_filter|wesnoth.wml_matches_filter]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Variables#helper.set_wml_var_metatable|helper.set_wml_var_metatable]]<br />
* [[LuaWML:Variables#helper.get_child|helper.get_child]]<br />
* [[LuaWML:Variables#helper.get_nth_child|helper.get_nth_child]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Variables#helper.child_count|helper.child_count]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Variables#helper.child_range|helper.child_range]]<br />
* [[LuaWML:Variables#helper.child_array|helper.child_array]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Variables#helper.get_variable_array|helper.get_variable_array]]<br />
* [[LuaWML:Variables#helper.get_variable_proxy_array|helper.get_variable_proxy_array]]<br />
* [[LuaWML:Variables#helper.set_variable_array|helper.set_variable_array]]<br />
<br />
=== Events and WML actions ===<br />
<br />
* [[LuaWML:Events#wesnoth.fire|wesnoth.fire]]<br />
* [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]]<br />
* [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_conditionals]] {{DevFeature1.13|0}}<br />
* [[LuaWML:Events#wesnoth.game_events|wesnoth.game_events]]<br />
* [[LuaWML:Events#wesnoth.persistent_tags|wesnoth.persistent_tags]] {{DevFeature1.13|12}}<br />
* [[LuaWML:Events#wesnoth.fire_event|wesnoth.fire_event]]<br />
* [[LuaWML:Events#wesnoth.fire_event_by_id|wesnoth.fire_event_by_id]] {{DevFeature1.13|6}}<br />
* [[LuaWML:Events#wesnoth.add_event_handler|wesnoth.add_event_handler]] {{DevFeature1.13|0}}<br />
* [[LuaWML:Events#wesnoth.remove_event_handler|wesnoth.remove_event_handler]] {{DevFeature1.13|0}}<br />
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]<br />
* [[LuaWML:Events#wesnoth.tovconfig|wesnoth.tovconfig]]<br />
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]<br />
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]<br />
* [[LuaWML:Events#helper.literal|helper.literal]]<br />
* [[LuaWML:Events#helper.parsed|helper.parsed]]<br />
* [[LuaWML:Events#helper.shallow_literal|helper.shallow_literal]]<br />
* [[LuaWML:Events#helper.shallow_parsed|helper.shallow_parsed]]<br />
* [[LuaWML:Events#on_event.lua|on_event.on_event]] {{DevFeature1.13|6}}<br />
<br />
=== User interface ===<br />
* [[LuaWML:Display#wesnoth.get_viewing_side|wesnoth.get_viewing_side]] {{DevFeature1.13|?}}<br />
* [[LuaWML:Display#wesnoth.message|wesnoth.message]]<br />
* [[LuaWML:Display#wesnoth.clear_messages|wesnoth.clear_messages]]<br />
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]<br />
* [[LuaWML:Display#wesnoth.delay|wesnoth.delay]]<br />
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]<br />
* [[LuaWML:Display#wesnoth.select_unit|wesnoth.select_hex]]<br />
* [[LuaWML:Display#wesnoth.select_unit|wesnoth.select_unit]]<br />
* [[LuaWML:Display#wesnoth.highlight_hex|wesnoth.highlight_hex]]<br />
* [[LuaWML:Display#wesnoth.deselect_hex|wesnoth.deselect_hex]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Display#wesnoth.scroll_to_tile|wesnoth.scroll_to_tile]]<br />
* [[LuaWML:Display#wesnoth.lock_view|wesnoth.lock_view]]<br />
* [[LuaWML:Display#wesnoth.view_locked|wesnoth.view_locked]]<br />
* [[LuaWML:Display#wesnoth.play_sound|wesnoth.play_sound]]<br />
* [[LuaWML:Display#wesnoth.set_music|wesnoth.set_music]]<br />
* [[LuaWML:Display#wesnoth.music_list|wesnoth.music_list]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Display#wesnoth.sound_volume|wesnoth.sound_volume]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Display#wesnoth.show_message_dialog|wesnoth.show_message_dialog]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Display#wesnoth.show_popup_dialog|wesnoth.show_popup_dialog]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Display#wesnoth.show_story|wesnoth.show_story]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Display#wesnoth.show_message_box|wesnoth.show_message_box]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Display#wesnoth.show_menu|wesnoth.show_menu]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Display#wesnoth.show_message_box|wesnoth.alert]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Display#wesnoth.show_message_box|wesnoth.confirm]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Display#wesnoth.show_dialog|wesnoth.show_dialog]]<br />
* [[LuaWML:Display#wesnoth.set_dialog_value|wesnoth.set_dialog_value]]<br />
* [[LuaWML:Display#wesnoth.get_dialog_value|wesnoth.get_dialog_value]]<br />
* [[LuaWML:Display#wesnoth.set_dialog_active|wesnoth.set_dialog_active]]<br />
* [[LuaWML:Display#wesnoth.set_dialog_callback|wesnoth.set_dialog_callback]]<br />
* [[LuaWML:Display#wesnoth.set_dialog_markup|wesnoth.set_dialog_markup]]<br />
* [[LuaWML:Display#wesnoth.set_dialog_focus|wesnoth.set_dialog_focus]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Display#wesnoth.set_dialog_visible|wesnoth.set_dialog_visible]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]]<br />
* [[LuaWML:Display#wesnoth.add_dialog_tree_node|wesnoth.add_dialog_tree_node]] {{DevFeature1.13|0}}<br />
* [[LuaWML:Display#wesnoth.remove_dialog_item|wesnoth.remove_dialog_item]] {{DevFeature1.13|1}}<br />
* [[LuaWML:Display#wesnoth.get_displayed_unit|wesnoth.get_displayed_unit]]<br />
* [[LuaWML:Display#wesnoth.theme_items|wesnoth.theme_items]]<br />
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]<br />
* [[LuaWML:Display#wesnoth.is_skipping_messages|wesnoth.is_skipping_messages]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Display#wesnoth.skip_messages|wesnoth.skip_messages]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Display#wesnoth.log|wesnoth.log]] {{DevFeature1.13|5}}<br />
* [[LuaWML:Display#wesnoth.zoom|wesnoth.zoom]] {{DevFeature1.13|8}}<br />
<br />
=== Map and terrains ===<br />
<br />
* [[LuaWML:Tiles#wesnoth.get_map_size|wesnoth.get_map_size]]<br />
* [[LuaWML:Tiles#wesnoth.get_terrain|wesnoth.get_terrain]]<br />
* [[LuaWML:Tiles#wesnoth.set_terrain|wesnoth.set_terrain]]<br />
* [[LuaWML:Tiles#wesnoth.get_terrain_info|wesnoth.get_terrain_info]]<br />
* [[LuaWML:Tiles#wesnoth.get_selected_tile|wesnoth.get_selected_tile]]<br />
* [[LuaWML:Tiles#wesnoth.get_locations|wesnoth.get_locations]]<br />
* [[LuaWML:Tiles#wesnoth.get_villages|wesnoth.get_villages]]<br />
* [[LuaWML:Tiles#wesnoth.match_location|wesnoth.match_location]]<br />
* [[LuaWML:Tiles#wesnoth.add_tile_overlay|wesnoth.add_tile_overlay]]<br />
* [[LuaWML:Tiles#wesnoth.remove_tile_overlay|wesnoth.remove_tile_overlay]]<br />
* [[LuaWML:Tiles#wesnoth.add_fog|wesnoth.add_fog]] {{DevFeature1.13|5}}<br />
* [[LuaWML:Tiles#wesnoth.remove_fog|wesnoth.remove_fog]] {{DevFeature1.13|5}}<br />
* [[LuaWML:Tiles#wesnoth.add_sound_source|wesnoth.add_sound_source]] {{DevFeature1.13|5}}<br />
* [[LuaWML:Tiles#wesnoth.remove_sound_source|wesnoth.remove_sound_source]] {{DevFeature1.13|5}}<br />
* [[LuaWML:Tiles#wesnoth.get_sound_source|wesnoth.get_sound_source]] {{DevFeature1.13|5}}<br />
* [[LuaWML:Tiles#wesnoth.map.get_direction|wesnoth.map.get_direction]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Tiles#wesnoth.map.get_relative_dir|wesnoth.map.get_relative_dir]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Tiles#wesnoth.map.rotate_right_around_center|wesnoth.map.rotate_right_around_center]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Tiles#wesnoth.map.get_adjacent_tiles|wesnoth.map.get_adjacent_tiles]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Tiles#wesnoth.map.tiles_adjacent|wesnoth.map.tiles_adjacent]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Tiles#wesnoth.map.distance_between|wesnoth.map.distance_between]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Tiles#wesnoth.label|wesnoth.label]] {{DevFeature1.13|0}}<br />
* [[LuaWML:Tiles#wesnoth.special_locations|wesnoth.special_locations]] {{DevFeature1.13|12}}<br />
* [[LuaWML:Tiles#items.place_image|items.place_image]]<br />
* [[LuaWML:Tiles#items.place_halo|items.place_halo]]<br />
* [[LuaWML:Tiles#items.remove|items.remove]]<br />
<br />
=== Time of day schedule ===<br />
<br />
* [[LuaWML:Time#wesnoth.get_time_of_day|wesnoth.get_time_of_day]]<br />
* [[LuaWML:Time#wesnoth.add_time_area|wesnoth.add_time_area]] {{DevFeature1.13|0}}<br />
* [[LuaWML:Time#wesnoth.remove_time_area|wesnoth.remove_time_area]] {{DevFeature1.13|0}}<br />
<br />
=== Units ===<br />
<br />
* [[LuaWML:Units#wesnoth.get_units|wesnoth.get_units]]<br />
* [[LuaWML:Units#wesnoth.get_unit|wesnoth.get_unit]]<br />
* [[LuaWML:Units#wesnoth.match_unit|wesnoth.match_unit]]<br />
* [[LuaWML:Units#wesnoth.put_unit|wesnoth.put_unit]]<br />
* [[LuaWML:Units#wesnoth.erase_unit|wesnoth.erase_unit]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Units#wesnoth.get_recall_units|wesnoth.get_recall_units]]<br />
* [[LuaWML:Units#wesnoth.put_recall_unit|wesnoth.put_recall_unit]]<br />
* [[LuaWML:Units#wesnoth.create_unit|wesnoth.create_unit]]<br />
* [[LuaWML:Units#wesnoth.copy_unit|wesnoth.copy_unit]]<br />
* [[LuaWML:Units#wesnoth.extract_unit|wesnoth.extract_unit]]<br />
* [[LuaWML:Units#wesnoth.add_modification|wesnoth.add_modification]]<br />
* [[LuaWML:Units#wesnoth.remove_modifications|wesnoth.remove_modifications]] {{DevFeature1.13|?}}<br />
* [[LuaWML:Units#wesnoth.unit_resistance|wesnoth.unit_resistance]]<br />
* [[LuaWML:Units#wesnoth.unit_defense|wesnoth.unit_defense]]<br />
* [[LuaWML:Units#wesnoth.unit_movement_cost|wesnoth.unit_movement_cost]]<br />
* [[LuaWML:Units#wesnoth.unit_vision_cost|wesnoth.unit_vision_cost]]<br />
* [[LuaWML:Units#wesnoth.unit_jamming_cost|wesnoth.unit_jamming_cost]]<br />
* [[LuaWML:Units#wesnoth.unit_ability|wesnoth.unit_ability]]<br />
* [[LuaWML:Units#wesnoth.unit_types|wesnoth.unit_types]]<br />
* [[LuaWML:Units#wesnoth.races|wesnoth.races]]<br />
* [[LuaWML:Units#wesnoth.get_traits|wesnoth.get_traits]]<br />
* [[LuaWML:Units#wesnoth.advance_unit|wesnoth.advance_unit]] {{DevFeature1.13|?}}<br />
* [[LuaWML:Units#wesnoth.add_known_unit|wesnoth.add_known_unit]] {{DevFeature1.13|?}}<br />
* [[LuaWML:Units#wesnoth.simulate_combat|wesnoth.simulate_combat]]<br />
* [[LuaWML:Units#wesnoth.transform_unit|wesnoth.transform_unit]]<br />
* [[LuaWML:Units#wesnoth.create_animator|wesnoth.create_animator]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Units#wesnoth.effects|wesnoth.effects]] {{DevFeature1.13|2}}<br />
<br />
=== Sides ===<br />
<br />
* [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]]<br />
* [[LuaWML:Sides#wesnoth.get_sides|wesnoth.get_sides]]<br />
* [[LuaWML:Sides#wesnoth.get_village_owner|wesnoth.get_village_owner]]<br />
* [[LuaWML:Sides#wesnoth.set_village_owner|wesnoth.set_village_owner]]<br />
* [[LuaWML:Sides#wesnoth.is_enemy|wesnoth.is_enemy]]<br />
* [[LuaWML:Sides#wesnoth.match_side|wesnoth.match_side]]<br />
* [[LuaWML:Sides#wesnoth.get_starting_location|wesnoth.get_starting_location]]<br />
* [[LuaWML:Sides#wesnoth.set_side_id|wesnoth.set_side_id]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Sides#wesnoth.place_shroud|wesnoth.place_shroud]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Sides#wesnoth.remove_shroud|wesnoth.remove_shroud]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Sides#wesnoth.is_fogged|wesnoth.is_fogged]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Sides#wesnoth.is_shrouded|wesnoth.is_shrouded]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Sides#wesnoth.switch_ai|wesnoth.switch_ai]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Sides#wesnoth.append_ai|wesnoth.append_ai]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Sides#wesnoth.add_ai_component|wesnoth.add_ai_component]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Sides#wesnoth.change_ai_component|wesnoth.change_ai_component]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Sides#wesnoth.delete_ai_component|wesnoth.delete_ai_component]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Sides#helper.all_teams|helper.all_teams]]<br />
* [[LuaWML:Sides#helper.get_side_variable|helper.get_side_variable]] {{DevFeature1.13|?}}<br />
* [[LuaWML:Sides#helper.set_side_variable|helper.set_side_variable]] {{DevFeature1.13|?}}<br />
<br />
=== Pathfinder ===<br />
<br />
* [[LuaWML:Pathfinder#wesnoth.find_path|wesnoth.find_path]]<br />
* [[LuaWML:Pathfinder#wesnoth.find_vacant_tile|wesnoth.find_vacant_tile]]<br />
* [[LuaWML:Pathfinder#wesnoth.find_reach|wesnoth.find_reach]]<br />
* [[LuaWML:Pathfinder#wesnoth.find_cost_map|wesnoth.find_cost_map]]<br />
* [[LuaWML:Pathfinder#helper.distance_between|helper.distance_between]]<br />
* [[LuaWML:Pathfinder#helper.adjacent_tiles|helper.adjacent_tiles]]<br />
<br />
=== Lua files ===<br />
<br />
* [[LuaWML:Files#wesnoth.dofile|wesnoth.dofile]]<br />
* [[LuaWML:Files#wesnoth.require|wesnoth.require]]<br />
* [[LuaWML:Files#wesnoth.have_file|wesnoth.have_file]] {{DevFeature1.13|5}}<br />
* [[LuaWML:Files#wesnoth.read_file|wesnoth.read_file]] {{DevFeature1.13|5}}<br />
<br />
=== Location sets ===<br />
<br />
* [[LuaWML:Location_set#location_set.create|location_set.create]]<br />
* [[LuaWML:Location_set#location_set.of_pairs|location_set.of_pairs]]<br />
* [[LuaWML:Location_set#location_set.of_wml_var|location_set.of_wml_var]]<br />
* [[LuaWML:Location_set#location_set:empty|location_set:empty]]<br />
* [[LuaWML:Location_set#location_set:size|location_set:size]]<br />
* [[LuaWML:Location_set#location_set:clear|location_set:clear]]<br />
* [[LuaWML:Location_set#location_set:get|location_set:get]]<br />
* [[LuaWML:Location_set#location_set:insert|location_set:insert]]<br />
* [[LuaWML:Location_set#location_set:remove|location_set:remove]]<br />
* [[LuaWML:Location_set#location_set:of_pairs|location_set:of_pairs]]<br />
* [[LuaWML:Location_set#location_set:of_wml_var|location_set:of_wml_var]]<br />
* [[LuaWML:Location_set#location_set:to_pairs|location_set:to_pairs]]<br />
* [[LuaWML:Location_set#location_set:to_stable_pairs|location_set:to_stable_pairs]]<br />
* [[LuaWML:Location_set#location_set:to_wml_var|location_set:to_wml_var]]<br />
* [[LuaWML:Location_set#location_set:union|location_set:union]]<br />
* [[LuaWML:Location_set#location_set:inter|location_set:inter]]<br />
* [[LuaWML:Location_set#location_set:iter|location_set:iter]]<br />
* [[LuaWML:Location_set#location_set:stable_iter|location_set:stable_iter]]<br />
* [[LuaWML:Location_set#location_set:filter|location_set:filter]]<br />
* [[LuaWML:Location_set#location_set:union_merge|location_set:union_merge]]<br />
* [[LuaWML:Location_set#location_set:inter_merge|location_set:inter_merge]]<br />
<br />
=== Miscellaneous ===<br />
<br />
* [[LuaWML:Misc#wesnoth.game_config|wesnoth.game_config]]<br />
* [[LuaWML:Misc#wesnoth.get_era|wesnoth.get_era]]<br />
* [[LuaWML:Misc#wesnoth.current|wesnoth.current]]<br />
* [[LuaWML:Misc#wesnoth.synchronize_choice|wesnoth.synchronize_choice]]<br />
* [[LuaWML:Misc#wesnoth.synchronize_choices|wesnoth.synchronize_choices]] {{DevFeature1.13|?}}<br />
* [[LuaWML:Misc#wesnoth.unsynced|wesnoth.unsynced]] {{DevFeature1.13|?}}<br />
* [[LuaWML:Misc#wesnoth.get_image_size|wesnoth.get_image_size]]<br />
* [[LuaWML:Misc#wesnoth.compare_versions|wesnoth.compare_versions]]<br />
* [[LuaWML:Misc#wesnoth.have_file|wesnoth.have_file]]<br />
* [[LuaWML:Misc#wesnoth.debug|wesnoth.debug]]<br />
* [[LuaWML:Misc#wesnoth.get_time_stamp|wesnoth.get_time_stamp]]<br />
* [[LuaWML:Misc#wesnoth.random|wesnoth.random]] {{DevFeature1.13|2}}<br />
* [[LuaWML:Misc#wesnoth.eval_formula|wesnoth.eval_formula]] {{DevFeature1.13|5}}<br />
* [[LuaWML:Misc#wesnoth.compile_formula|wesnoth.compile_formula]] {{DevFeature1.13|5}}<br />
* [[LuaWML:Misc#wesnoth.name_generator|wesnoth.name_generator]] {{DevFeature1.13|5}}<br />
* [[LuaWML:Misc#wesnoth.set_next_scenario|wesnoth.set_next_scenario]] {{DevFeature1.13|5}}<br />
* [[LuaWML:Misc#wesnoth.format|wesnoth.format]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Misc#wesnoth.format_conjunct_list|wesnoth.format_conjunct_list]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Misc#wesnoth.format_disjunct_list|wesnoth.format_disjunct_list]] {{DevFeature1.13|8}}<br />
* [[LuaWML:Misc#wesnoth.wesnoth.end_turn|wesnoth.end_turn]] {{DevFeature1.13|ß}}<br />
* [[LuaWML:Misc#helper.set_wml_tag_metatable|helper.set_wml_tag_metatable]]<br />
* [[LuaWML:Misc#helper.modify_unit|helper.modify_unit]]<br />
* [[LuaWML:Misc#helper.move_unit_fake|helper.move_unit_fake]]<br />
* [[LuaWML:Misc#helper.rand|helper.rand]]<br />
* [[LuaWML:Misc#helper.round|helper.round]]<br />
* [[LuaWML:Misc#helper.shuffle|helper.shuffle]]<br />
<br />
=== Functions that should not be used ===<br />
<br />
If you take a look at Wesnoth's own lua files, you might find some undocumented functions use in the implementations of WML tags. Where possible, you should avoid using them, as they might be changed or removed with no compatibility for further releases. Instead, use the corresponding wml tags (in lua you can use <tt>wesnoth.wml_actions.tag_name(cfg)</tt>, though keep in mind that this won't substitute variables in the config).<br />
<br />
If uncertain whether an undocumented feature is safe to use, ask on the forums, Discord, or IRC. It may turn out that someone simply forgot to add it to the wiki.<br />
<br />
* wesnoth.redraw<br />
* wesnoth.set_menu_item<br />
* wesnoth.clear_menu_item<br />
* wesnoth.modify_ai<br />
* wesnoth.print<br />
* wesnoth.end_level<br />
<br />
== Encoding WML objects into Lua tables ==<br />
<br />
Function [[LuaWML:Events#wesnoth.fire|wesnoth.fire]] expects a table representing a WML object as its second argument (if needed). Function [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]] allows to modify whole WML objects, again by passing it a table. Function [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]] transforms a WML object into a table, if its second argument is not set to ''true''. All these tables have the same format.<br />
<br />
Scalar fields are transformed into WML attributes. For instance, the following Lua table<br />
<br />
<syntaxhighlight lang='lua'><br />
{<br />
a_bool = true,<br />
an_int = 42,<br />
a_float = 1.25,<br />
a_string = "scout",<br />
a_translation = _ "Hello World!"<br />
}<br />
</syntaxhighlight><br />
<br />
is equivalent to the content of the following WML object<br />
<br />
<syntaxhighlight lang='wml'><br />
[dummy]<br />
a_bool = "yes"<br />
an_int = "42"<br />
a_float = "1.25"<br />
a_string = "scout"<br />
a_translation = _ "Hello World!"<br />
[/dummy]<br />
</syntaxhighlight><br />
<br />
WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys. So child objects are stored as pairs string + table in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table "layer" in the corresponding WML table of the form <code>{[1] = "tag_name", [2] = {}}</code> which is equivalent to <code>{"tag_name", {}}</code>. [1] etc are the unnamed fields (as opposed to wml attributes). The table under [2] in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. For instance, the following Lua table<br />
<br />
<syntaxhighlight lang='lua'><br />
{<br />
foo = 42,<br />
{ "bar", { v = 1, w = 2 } },<br />
{ "foo", { x = false } },<br />
{ "bar", { y = "foo" } },<br />
{ "foobar", { z = 5, { "barfoo", {} } } }<br />
}<br />
</syntaxhighlight><br />
<br />
is equivalent to the content of the following WML object<br />
<br />
<syntaxhighlight lang='wml'><br />
[dummy]<br />
foo = 42<br />
[bar]<br />
v = 1<br />
w = 2<br />
[/bar]<br />
[foo]<br />
x = no<br />
[/foo]<br />
[bar]<br />
y = foo<br />
[bar]<br />
[foobar]<br />
z = 5<br />
[barfoo]<br />
[/barfoo]<br />
[/foobar]<br />
[/dummy]<br />
</syntaxhighlight><br />
<br />
Both tables above are also equivalent to this WML table, where all unnamed fields are displayed:<br />
<br />
<syntaxhighlight lang='lua'><br />
{<br />
foo = 42,<br />
[1] = { [1] = "bar", [2] = { v = 1, w = 2 } },<br />
[2] = { [1] = "foo", [2] = { x = false } },<br />
[3] = { [1] = "bar", [2] = { y = "foo" } },<br />
[4] = { [1] = "foobar", [2] = { z = 5, [1] = { [1] = "barfoo", [2] = {} } } }<br />
}<br />
</syntaxhighlight><br />
<br />
So assuming ''cfg'' contains the above WML object, the following accesses are possible:<br />
<br />
<syntaxhighlight lang=lua><br />
a_int = cfg.foo -- "dummy.foo", 42<br />
a_string = cfg[3][2].y -- "dummy.bar[1].y", "foo"<br />
a_table = cfg[4][2] -- "dummy.foobar", { z = 5, { "barfoo", {} } }<br />
</syntaxhighlight><br />
<br />
For creating valid wml table in lua it is usully easier to use ''T = helper.set_wml_tag_metatable {}'' asuming you did that you can create the above wml document with<br />
<syntaxhighlight lang=lua><br />
{<br />
foo = 42,<br />
T.bar {<br />
v = 1,<br />
w = 1,<br />
},<br />
T.foo {<br />
x = false,<br />
},<br />
T.bar {<br />
y = "foo",<br />
},<br />
T.foobar {<br />
z = 5,<br />
T.barfoo {<br />
},<br />
},<br />
}<br />
</syntaxhighlight><br />
<br />
Consider using the [[LuaWML:Variables#helper.get_child|helper.get_child]] and [[LuaWML:Variables#helper.child_range|helper.child_range]] to ease the access to subtags.<br />
<br />
{{DevFeature1.13|5}} As a convenience, attributes with array values (tables with only integer keys) are concatenated into a string when converting a Lua table into WML. For example, the following Lua code:<br />
<br />
<syntaxhighlight lang=lua><br />
{<br />
x = {1, 2, 3, 4},<br />
y = {7, 8, 9, 10}<br />
}<br />
</syntaxhighlight><br />
<br />
produces the following WML table:<br />
<br />
<syntaxhighlight lang=wml><br />
[dummy]<br />
x=1,2,3,4<br />
y=7,8,9,10<br />
[/dummy]<br />
</syntaxhighlight><br />
<br />
Functions registered in [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]] receive their data in a userdata object which has the exact same structure as above. It is read-only however. Accessing fields or children performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain tables (therefore writable). '''__literal''' returns the original text of the data (including dollar symbols in attributes and [insert_tag] children), while '''__parsed''' performs a variable substitution.<br />
<br />
For instance, if you cannot stand any longer the fact that '''first_time_only''' is set to yes by default for the '''[event]''' tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.<br />
<br />
<syntaxhighlight lang=lua><br />
local old_event_handler = wesnoth.wml_actions.event<br />
function wesnoth.wml_actions.event(cfg)<br />
-- Get the plain text from the user.<br />
local new_cfg = cfg.__literal<br />
-- The expression below is equivalent to cfg.__parsed.first_time_only,<br />
-- only faster. It is needed, since the first_time_only attribute may<br />
-- reference variables.<br />
local first = cfg.first_time_only<br />
-- Modify the default behavior of first_time_only.<br />
if first == nil then first = false end<br />
new_cfg.first_time_only = first<br />
-- Call the engine handler.<br />
old_event_handler(new_cfg)<br />
end<br />
</syntaxhighlight><br />
<br />
(Note: The above example will only affect nested events. Toplevel events will still default to ''first_time_only=yes''.)<br />
<!-- This should probably be replaced with a better example. --><br />
<br />
Note that, since the object is a userdata and not a table, '''pairs''' and '''ipairs''' are unfortunately not usable on it. So scripts have to work at a lower level. For instance, the following function returns the first sub-tag with a given name and it works both on WML tables and WML userdata:<br />
<br />
<syntaxhighlight lang=lua><br />
function get_child(cfg, name)<br />
for i = 1, #cfg do<br />
local v = cfg[i]<br />
if v[1] == name then return v[2] end<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
{{DevFeature1.13|2}} '''pairs''' and '''ipairs''' now work on vconfig objects (contrary to the above statement). However, '''pairs''' works a little differently than on plain configs (tables) - it returns only string keys (attributes in WML terms) and not integer keys (tags in WML terms).<br />
<br />
Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand:<br />
<br />
<syntaxhighlight lang=lua><br />
if getmetatable(cfg) == "wml object" then cfg = cfg.__parsed end<br />
</syntaxhighlight><br />
<br />
The WML userdata provides two other special fields: '''__shallow_parsed''' and '''__shallow_literal'''. They return a table corresponding to the WML userdata with variable substitution performed on the attributes (or not). [insert_tag] tags have also been parsed, so the number of children is faithful. But contrarily to '''__parsed''' and '''__literal''', the process is not recursive: all the children are still WML userdata and variable substitution can still happen for them. These shallow translators are meant as optimized versions of the deep ones, when only the toplevel attributes need to be writable.<br />
<br />
== Skeleton of a preload event ==<br />
<br />
The following event is a skeleton for a prelude enabling Lua in your WML events. It creates a table ''H'' containing the functions from helper.lua and a table ''W'' that serves as a proxy for firing WML actions. It sets up a table ''T'' so be used for easier creation of valid WML tables. It also sets up a table ''V'' so that any access to it is redirected to the persistent WML storage. Finally, it loads a textdomain to be accessed through the ''_'' variable.<br />
<br />
<syntaxhighlight lang='wml'><br />
[event]<br />
name=preload<br />
first_time_only=no<br />
[lua]<br />
code = <<<br />
H = wesnoth.require "lua/helper.lua"<br />
W = H.set_wml_action_metatable {}<br />
T = H.set_wml_tag_metatable {}<br />
V = H.set_wml_var_metatable {}<br />
_ = wesnoth.textdomain "my-campaign"<br />
<br />
-- Define your global constants here.<br />
-- ...<br />
<br />
<br />
-- Define your global functions here.<br />
-- ...<br />
>><br />
[/lua]<br />
[/event]<br />
</syntaxhighlight><br />
<br />
It may be worth putting the whole Lua script above inside a separate file and having the ''preload'' event load it:<br />
<br />
<syntaxhighlight lang='wml'><br />
[event]<br />
name=preload<br />
first_time_only=no<br />
[lua]<br />
code = << wesnoth.dofile "~add-ons/Whatever/file.lua" >><br />
[/lua]<br />
[/event]<br />
</syntaxhighlight><br />
<br />
== Remarks on Random Numbers ==<br />
<br />
The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should use the [[LuaWML:Misc#helper.rand|helper.rand()]] function to synchronize random values. It takes the same argument in the same format as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] rand=.<br />
<br />
<syntaxhighlight lang='lua'><br />
local random_variable = helper.rand("1,2,3")<br />
</syntaxhighlight><br />
<br />
Also available is [[LuaWML:Misc#wesnoth.random|wesnoth.random]], which has the same interface as math.random but is multiplayer-safe.<br />
<br />
== Random Lua table iteration ==<br />
<br />
Table iteration order ('''pairs''') is not strictly defined in Lua. If your code depends on the order of iteration, different clients may have different data in a multiplayer game. For example:<br />
<br />
<syntaxhighlight lang='lua'><br />
local table = { ["Mage"] = true, ["Wose"] = true }<br />
local concat = ""<br />
local bad_usage = next(table) -- wrong, leads to OOS<br />
for k, _ in pairs(table) do -- wrong, leads to OOS<br />
concat = concat .. k<br />
end<br />
</syntaxhighlight><br />
<br />
To avoid the problem, sort the table keys before iterating. Or alternatively, use Lua "arrays" and the '''ipairs''' function, which have a strictly defined order and never lead to OOS. Example of correct code:<br />
<br />
<syntaxhighlight lang='lua'><br />
local array = { "Mage", "Wose" }<br />
local good_usage = table[1] -- correct<br />
local concat = ""<br />
for _, v in ipairs(array) do -- correct<br />
concat = concat .. v<br />
end<br />
</syntaxhighlight><br />
<br />
[[Category: Lua Reference|*]]<br />
[[Category: WML Reference]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=LuaAPI/wml&diff=59795LuaAPI/wml2018-06-19T01:38:01Z<p>Vultraz: /* wml.tovconfig */</p>
<hr />
<div>The <tt>wml</tt> module contains functions for working with WML tables. This module is available starting in 1.14.0.<br />
<br />
==== wml.child_array ====<br />
<br />
* '''wml.child_array(''config'', ''child_tag_name'')''' &rarr; ''array''<br />
<br />
Like [[#wml.child_range]], but returns an array instead of an iterator. Useful if you need random access to the children.<br />
<br />
==== wml.child_count ====<br />
<br />
* '''wml.child_count(''config'', ''child_tag_name'')''' &rarr; ''count''<br />
<br />
Returns the number of children in the config with the given tag name.<br />
<br />
==== wml.child_range ====<br />
<br />
* '''wml.child_range(''config'', ''child_tag_name'')''' &rarr; ''iterator''<br />
<br />
Returns an iterator over all the sub-tags of a WML object with the given name.<br />
<br />
<syntaxhighlight lang=lua><br />
local u = wesnoth.get_units({ id = "Delfador" })[1]<br />
for att in wml.child_range(u.__cfg, "attack") do<br />
wesnoth.message(tostring(att.description))<br />
end<br />
</syntaxhighlight><br />
<br />
==== wml.get_child ====<br />
<br />
* '''wml.get_child(''config'', ''child_tag_name'' [, ''id''])''' &rarr; ''child_table''<br />
<br />
Returns the first sub-tag of a WML object with the given name.<br />
<br />
<syntaxhighlight lang=lua><br />
local u = wesnoth.get_units({ id = "Delfador" })[1]<br />
local costs = wml.get_child(u.__cfg, "movement_costs")<br />
wesnoth.message(string.format("Delfador needs %d points to move through a forest.", costs.forest))<br />
</syntaxhighlight><br />
<br />
If a third parameter is passed, only children having a ''id'' attribute equal to it are considered.<br />
<br />
==== wml.get_nth_child ====<br />
<br />
* '''wml.get_nth_child(''config'', ''child_tag_name'', ''n'')''' &rarr; ''child_table''<br />
<br />
Returns the ''n''th sub-tag of a WML object with the given name.<br />
<br />
==== wml.remove_child ====<br />
<br />
* '''wml.remove_child(''config'', ''child_tag_name'')'''<br />
<br />
Deletes the first child tag with the given name. This does not work on vconfig objects, however.<br />
<br />
==== wml.remove_children ====<br />
<br />
* '''wml.remove_children(''config'', ''child_tag_name'')'''<br />
<br />
Deletes all child tags with the given name. This does not work on vconfig objects, however.<br />
<br />
==== wml.tag ====<br />
<br />
* '''wml.tag.''tag_name''(''contents'')''' &rarr; ''tag_table''<br />
<br />
Returns a table representing a tag within a WML table; can be used to create subtags with less brackets. It's common to use direct-table invocation for this, omitting the function parentheses.<br />
<br />
<syntaxhighlight lang=lua><br />
wesnoth.wml_actions.event { name = "new turn", wml.tag.message { speaker = "narrator", message = "?" } }<br />
</syntaxhighlight><br />
<br />
==== wml.tostring ====<br />
<br />
* '''wml.tostring(''wml_table'')''' &rarr; ''string''<br />
<br />
Takes a userdata with metatable wml object or a wml table and dumps its content into a pretty string.<br />
<br />
<syntaxhighlight lang=lua><br />
wml.variables["number"] = 100<br />
local vconfig = wml.tovconfig({ key = "$number", another_key = true,<br />
{"a_subtag", { a_key_in_the_subtag = "foo" }}<br />
})<br />
wesnoth.message(wml.tostring(vconfig))<br />
wesnoth.message(wml.tostring(vconfig.__literal))<br />
</syntaxhighlight><br />
<br />
==== wml.tovconfig ====<br />
<br />
* '''wml.tovconfig(''config'')''' &rarr; ''vconfig''<br />
<br />
Converts a WML table into a proxy object which performs variable substitution on the fly.<br />
<br />
<syntaxhighlight lang=lua><br />
wml.variables["varname"] = "to_be_deleted"<br />
<br />
-- correct<br />
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" }<br />
-- error: try to delete a variable literally called "$varname"<br />
wesnoth.wml_actions.clear_variable { name = "$varname" }<br />
-- correct: "$varname" is replaced by "to_be_deleted" at the right time<br />
wesnoth.wml_actions.clear_variable(wml.tovconfig { name = "$varname" })<br />
</syntaxhighlight><br />
<br />
==== wml.literal ====<br />
<br />
* '''wml.literal(''config'')''' &rarr; ''wml_table''<br />
<br />
Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. If the argument is ''nil'', it returns an empty table. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).<br />
<br />
<syntaxhighlight lang=lua><br />
function wml_actions.display_literal_value(cfg)<br />
cfg = wml.literal(cfg)<br />
wesnoth.message(tostring(cfg.value)) <br />
end<br />
</syntaxhighlight><br />
<br />
Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.<br />
<br />
==== wml.parsed ====<br />
<br />
* '''wml.parsed(''config'')''' &rarr; ''wml_table''<br />
<br />
Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#wml.literal]].<br />
<br />
==== wml.shallow_literal ====<br />
<br />
* '''wml.shallow_literal(''config'')''' &rarr; ''wml_table''<br />
<br />
Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#wml.literal]].<br />
<br />
==== wml.shallow_parsed ====<br />
<br />
* '''wml.shallow_parsed(''config'')''' &rarr; ''wml_table''<br />
<br />
Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#wml.literal]].<br />
<br />
==== wml.all_variables ====<br />
<br />
* (game only) '''wml.all_variables''' &rarr; ''table''<br />
<br />
Returns a copy of all the WML variables currently set in the form of a WML table.<br />
<br />
<syntaxhighlight lang=lua><br />
for key, value in pairs(wml.all_variables) do<br />
if type(value) == "table" then<br />
print(key, value[1], value[2])<br />
else<br />
print(key, value)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==== wml.variables ====<br />
<br />
* (game only) '''wml.variables.''variable''''' &harr; ''variable_contents''<br />
* (game only) '''wml.variables[''variable_path'']''' &harr; ''variable_contents''<br />
<br />
This table grants read-write access to the WML variables by their fully-qualified name. Looking up a non-existent variable yields nil; otherwise, it returns a scalar for a WML attribute and a table for a WML object. The format of the table is described in [[LuaWML#Encoding WML objects into Lua tables]].<br />
<br />
<syntaxhighlight lang=lua><br />
wesnoth.fire("store_unit", { variable="my_unit", { "filter", { id="hero" } } })<br />
local heros_hp = wml.variables["my_unit[0].hitpoints"]<br />
wesnoth.message(string.format("The 'hero' unit has %d hitpoints.", heros_hp))<br />
</syntaxhighlight><br />
<br />
Note that, if the variable name happens to designate a sequence of WML objects, only the first one (index 0) is fetched. If all the WML objects with this name should have been returned, use [[#wml.get_variable_array]] instead. If you need a specific one, include the index in the lookup key.<br />
<br />
Assigning to a key in this table converts the Lua object to a WML variable if possible. For a table, a WML object is created; otherwise, an attribute is created. Note that you cannot assign a simple array as it will be mistaken for a WML table and give an error. Assigning nil clears the variable.<br />
<br />
<syntaxhighlight lang=lua><br />
wml.variables["my_unit.hitpoints"] = heros_hp + 10<br />
</syntaxhighlight><br />
<br />
==== wml.variables_proxy ====<br />
<br />
* (game only) '''wml.variables_proxy.''variable''''' &harr; ''proxy''<br />
* (game only) '''wml.variables_proxy[''variable_path'']''' &harr; ''proxy''<br />
<br />
Similar to <tt>wml.variables</tt>, but if the variable is a container, then the fields of the returned table are then proxies to the WML objects with the same names; reading/writing to them will directly access the WML sub-variables. Note that this is still somewhat experimental and doesn't allow you to fully treat variables as if they were standard Lua tables.<br />
<br />
==== wml.array_access.get ====<br />
<br />
* (game only) '''wml.array_access.get(''var_name''[, ''context''])''' &rarr; ''array of variable_contents''<br />
<br />
Fetches all the WML container variables with given name and returns a table containing them (starting at index 1). The context specifies where to get variables from. You can pass either a unit or a side as the context in order to get an array from the unit variables or side variables, respectively.<br />
<br />
<syntaxhighlight lang=lua><br />
function get_recall_list(side)<br />
wesnoth.fire("store_unit", { x = "recall", variable = "LUA_recall_list })<br />
local l = wml.array_access.get "LUA_recall_list"<br />
wml.variables.LUA_recall_list = nil<br />
return l<br />
end<br />
</syntaxhighlight><br />
<br />
==== wml.array_access.get_proxy ====<br />
<br />
* (game only) '''wml.array_access.get_proxy(''var_name'')''' &rarr; ''array of proxies''<br />
<br />
Creates proxies for all the WML container variables with given name and returns a table containing them (starting at index 1). This function is similar to [[#wml.array_access.get]], except that the proxies can be used for modifying WML containers. Note that changes to the returned array itself will not be reflected in the variable, however; only changes to the array elements.<br />
<br />
==== wml.array_access.set ====<br />
<br />
* (game only) '''wml.array_access.set(''varname'', ''array'' [, ''context''])'''<br />
<br />
Creates WML container variables with given name from given table. The context specifies where to put the variables. You can pass either a unit or a side as the context in order to set an array in the unit variables or side variables, respectively.<br />
<br />
<syntaxhighlight lang=lua><br />
wml.array_access.set("target", { {t=t1}, {t=t2}, {t=t3} })<br />
-- target[0].t <- t1; target[1].t <- t2; target[2].t <- t3<br />
</syntaxhighlight><br />
<br />
[[Category: Lua Reference]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=LuaAPI/wml&diff=59794LuaAPI/wml2018-06-19T01:37:18Z<p>Vultraz: /* wml.tovconfig */</p>
<hr />
<div>The <tt>wml</tt> module contains functions for working with WML tables. This module is available starting in 1.14.0.<br />
<br />
==== wml.child_array ====<br />
<br />
* '''wml.child_array(''config'', ''child_tag_name'')''' &rarr; ''array''<br />
<br />
Like [[#wml.child_range]], but returns an array instead of an iterator. Useful if you need random access to the children.<br />
<br />
==== wml.child_count ====<br />
<br />
* '''wml.child_count(''config'', ''child_tag_name'')''' &rarr; ''count''<br />
<br />
Returns the number of children in the config with the given tag name.<br />
<br />
==== wml.child_range ====<br />
<br />
* '''wml.child_range(''config'', ''child_tag_name'')''' &rarr; ''iterator''<br />
<br />
Returns an iterator over all the sub-tags of a WML object with the given name.<br />
<br />
<syntaxhighlight lang=lua><br />
local u = wesnoth.get_units({ id = "Delfador" })[1]<br />
for att in wml.child_range(u.__cfg, "attack") do<br />
wesnoth.message(tostring(att.description))<br />
end<br />
</syntaxhighlight><br />
<br />
==== wml.get_child ====<br />
<br />
* '''wml.get_child(''config'', ''child_tag_name'' [, ''id''])''' &rarr; ''child_table''<br />
<br />
Returns the first sub-tag of a WML object with the given name.<br />
<br />
<syntaxhighlight lang=lua><br />
local u = wesnoth.get_units({ id = "Delfador" })[1]<br />
local costs = wml.get_child(u.__cfg, "movement_costs")<br />
wesnoth.message(string.format("Delfador needs %d points to move through a forest.", costs.forest))<br />
</syntaxhighlight><br />
<br />
If a third parameter is passed, only children having a ''id'' attribute equal to it are considered.<br />
<br />
==== wml.get_nth_child ====<br />
<br />
* '''wml.get_nth_child(''config'', ''child_tag_name'', ''n'')''' &rarr; ''child_table''<br />
<br />
Returns the ''n''th sub-tag of a WML object with the given name.<br />
<br />
==== wml.remove_child ====<br />
<br />
* '''wml.remove_child(''config'', ''child_tag_name'')'''<br />
<br />
Deletes the first child tag with the given name. This does not work on vconfig objects, however.<br />
<br />
==== wml.remove_children ====<br />
<br />
* '''wml.remove_children(''config'', ''child_tag_name'')'''<br />
<br />
Deletes all child tags with the given name. This does not work on vconfig objects, however.<br />
<br />
==== wml.tag ====<br />
<br />
* '''wml.tag.''tag_name''(''contents'')''' &rarr; ''tag_table''<br />
<br />
Returns a table representing a tag within a WML table; can be used to create subtags with less brackets. It's common to use direct-table invocation for this, omitting the function parentheses.<br />
<br />
<syntaxhighlight lang=lua><br />
wesnoth.wml_actions.event { name = "new turn", wml.tag.message { speaker = "narrator", message = "?" } }<br />
</syntaxhighlight><br />
<br />
==== wml.tostring ====<br />
<br />
* '''wml.tostring(''wml_table'')''' &rarr; ''string''<br />
<br />
Takes a userdata with metatable wml object or a wml table and dumps its content into a pretty string.<br />
<br />
<syntaxhighlight lang=lua><br />
wml.variables["number"] = 100<br />
local vconfig = wml.tovconfig({ key = "$number", another_key = true,<br />
{"a_subtag", { a_key_in_the_subtag = "foo" }}<br />
})<br />
wesnoth.message(wml.tostring(vconfig))<br />
wesnoth.message(wml.tostring(vconfig.__literal))<br />
</syntaxhighlight><br />
<br />
==== wml.tovconfig ====<br />
<br />
* '''wml.tovconfig(''config'')''' &rarr; ''vconfig''<br />
<br />
Converts a WML table into a proxy object which performs variable substitution on the fly.<br />
<br />
<syntaxhighlight lang=lua><br />
wml.variables["varname"] = "to_be_deleted"<br />
<br />
-- correct<br />
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" }<br />
<br />
-- error: try to delete a variable literally called "$varname"<br />
wesnoth.wml_actions.clear_variable { name = "$varname" }<br />
<br />
-- correct: "$varname" is replaced by "to_be_deleted" at the right time<br />
wesnoth.wml_actions.clear_variable(wml.tovconfig { name = "$varname" })<br />
</syntaxhighlight><br />
<br />
==== wml.literal ====<br />
<br />
* '''wml.literal(''config'')''' &rarr; ''wml_table''<br />
<br />
Returns the ''__literal'' field of its argument if it is a userdata, the argument itself otherwise. If the argument is ''nil'', it returns an empty table. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).<br />
<br />
<syntaxhighlight lang=lua><br />
function wml_actions.display_literal_value(cfg)<br />
cfg = wml.literal(cfg)<br />
wesnoth.message(tostring(cfg.value)) <br />
end<br />
</syntaxhighlight><br />
<br />
Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.<br />
<br />
==== wml.parsed ====<br />
<br />
* '''wml.parsed(''config'')''' &rarr; ''wml_table''<br />
<br />
Returns the ''__parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#wml.literal]].<br />
<br />
==== wml.shallow_literal ====<br />
<br />
* '''wml.shallow_literal(''config'')''' &rarr; ''wml_table''<br />
<br />
Returns the ''__shallow_literal'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#wml.literal]].<br />
<br />
==== wml.shallow_parsed ====<br />
<br />
* '''wml.shallow_parsed(''config'')''' &rarr; ''wml_table''<br />
<br />
Returns the ''__shallow_parsed'' field of its argument if it is a userdata, the argument itself otherwise. See also [[#wml.literal]].<br />
<br />
==== wml.all_variables ====<br />
<br />
* (game only) '''wml.all_variables''' &rarr; ''table''<br />
<br />
Returns a copy of all the WML variables currently set in the form of a WML table.<br />
<br />
<syntaxhighlight lang=lua><br />
for key, value in pairs(wml.all_variables) do<br />
if type(value) == "table" then<br />
print(key, value[1], value[2])<br />
else<br />
print(key, value)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==== wml.variables ====<br />
<br />
* (game only) '''wml.variables.''variable''''' &harr; ''variable_contents''<br />
* (game only) '''wml.variables[''variable_path'']''' &harr; ''variable_contents''<br />
<br />
This table grants read-write access to the WML variables by their fully-qualified name. Looking up a non-existent variable yields nil; otherwise, it returns a scalar for a WML attribute and a table for a WML object. The format of the table is described in [[LuaWML#Encoding WML objects into Lua tables]].<br />
<br />
<syntaxhighlight lang=lua><br />
wesnoth.fire("store_unit", { variable="my_unit", { "filter", { id="hero" } } })<br />
local heros_hp = wml.variables["my_unit[0].hitpoints"]<br />
wesnoth.message(string.format("The 'hero' unit has %d hitpoints.", heros_hp))<br />
</syntaxhighlight><br />
<br />
Note that, if the variable name happens to designate a sequence of WML objects, only the first one (index 0) is fetched. If all the WML objects with this name should have been returned, use [[#wml.get_variable_array]] instead. If you need a specific one, include the index in the lookup key.<br />
<br />
Assigning to a key in this table converts the Lua object to a WML variable if possible. For a table, a WML object is created; otherwise, an attribute is created. Note that you cannot assign a simple array as it will be mistaken for a WML table and give an error. Assigning nil clears the variable.<br />
<br />
<syntaxhighlight lang=lua><br />
wml.variables["my_unit.hitpoints"] = heros_hp + 10<br />
</syntaxhighlight><br />
<br />
==== wml.variables_proxy ====<br />
<br />
* (game only) '''wml.variables_proxy.''variable''''' &harr; ''proxy''<br />
* (game only) '''wml.variables_proxy[''variable_path'']''' &harr; ''proxy''<br />
<br />
Similar to <tt>wml.variables</tt>, but if the variable is a container, then the fields of the returned table are then proxies to the WML objects with the same names; reading/writing to them will directly access the WML sub-variables. Note that this is still somewhat experimental and doesn't allow you to fully treat variables as if they were standard Lua tables.<br />
<br />
==== wml.array_access.get ====<br />
<br />
* (game only) '''wml.array_access.get(''var_name''[, ''context''])''' &rarr; ''array of variable_contents''<br />
<br />
Fetches all the WML container variables with given name and returns a table containing them (starting at index 1). The context specifies where to get variables from. You can pass either a unit or a side as the context in order to get an array from the unit variables or side variables, respectively.<br />
<br />
<syntaxhighlight lang=lua><br />
function get_recall_list(side)<br />
wesnoth.fire("store_unit", { x = "recall", variable = "LUA_recall_list })<br />
local l = wml.array_access.get "LUA_recall_list"<br />
wml.variables.LUA_recall_list = nil<br />
return l<br />
end<br />
</syntaxhighlight><br />
<br />
==== wml.array_access.get_proxy ====<br />
<br />
* (game only) '''wml.array_access.get_proxy(''var_name'')''' &rarr; ''array of proxies''<br />
<br />
Creates proxies for all the WML container variables with given name and returns a table containing them (starting at index 1). This function is similar to [[#wml.array_access.get]], except that the proxies can be used for modifying WML containers. Note that changes to the returned array itself will not be reflected in the variable, however; only changes to the array elements.<br />
<br />
==== wml.array_access.set ====<br />
<br />
* (game only) '''wml.array_access.set(''varname'', ''array'' [, ''context''])'''<br />
<br />
Creates WML container variables with given name from given table. The context specifies where to put the variables. You can pass either a unit or a side as the context in order to set an array in the unit variables or side variables, respectively.<br />
<br />
<syntaxhighlight lang=lua><br />
wml.array_access.set("target", { {t=t1}, {t=t2}, {t=t3} })<br />
-- target[0].t <- t1; target[1].t <- t2; target[2].t <- t3<br />
</syntaxhighlight><br />
<br />
[[Category: Lua Reference]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:StableDownload&diff=59781Template:StableDownload2018-06-11T15:21:22Z<p>Vultraz: Updated macOS link for 1.14.3a</p>
<hr />
<div><noinclude><br />
== Stable (1.14 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.3 | filename=wesnoth-1.14.3.tar.bz2 | size=450.2 MB | hash=e9f17f0245a2b7f63b28d77a1cc8854355768665f5ca93ffd3e7641b0840c418}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.2 | filename=wesnoth-1.14.2.tar.bz2 | size=449.9 MB | hash=282bb551f0e1679a2c09938c0bbae1cb13e54851cead5c7b425b7ec4648716f6}}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.3 | filename=wesnoth-1.14.3-win32.exe | size=407.9 MB | hash=81799aa26e349e55c330cc6dc95096cf0e4573c07e4215c8bbad999a66f8665b}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.2 | filename=wesnoth-1.14.2-win32.exe | size=407.7 MB | hash=1f28dba9daeec6d5473b3c8802a30dd0c840a4fd44afc0993368207978d88ff3}}<br />
<br />
==== macOS (10.8 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.3 | filename=Wesnoth_1.14.3a.dmg | size=468.2 MB | hash=eead09941d495f66e9c78d19169bbd61c5ac46f30a09ad432dd91e672ff1aee2}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.2 | filename=Wesnoth_1.14.2.dmg | size=456.4 MB | hash=fb1a07d2f9fd37a98a8d79f47256316d7fa0167d11871048c1774549b7c71f25}}</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:StableDownload&diff=59710Template:StableDownload2018-05-28T02:49:07Z<p>Vultraz: Updated links for 1.14.2</p>
<hr />
<div><noinclude><br />
== Stable (1.14 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.2 | filename=wesnoth-1.14.2.tar.bz2 | size=449.9 MB | hash=282bb551f0e1679a2c09938c0bbae1cb13e54851cead5c7b425b7ec4648716f6}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.1 | filename=wesnoth-1.14.1.tar.bz2 | size=442.4 MB | hash=6bf655b4df17098104a23078fb796c91223aca8294a15e58209aac70f6b2f9d7}}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.2 | filename=wesnoth-1.14.2-win32.exe | size=407.7 MB | hash=1f28dba9daeec6d5473b3c8802a30dd0c840a4fd44afc0993368207978d88ff3}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.1 | filename=wesnoth-1.14.1-win32.exe | size=403.2 MB | hash=38d6a3bc7b5005a78980ae4c8341ab682fc6997e7a4e56b07562844ebb6326ef}}<br />
<br />
==== macOS (10.8 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.1 | filename=Wesnoth_1.14.2.dmg | size=456.4 MB | hash=fb1a07d2f9fd37a98a8d79f47256316d7fa0167d11871048c1774549b7c71f25}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.1 | filename=Wesnoth_1.14.1a.dmg | size=450.5 MB | hash=d76d60492546877b015b6aa185c0e500e64c39a643a1137f89bf4eedd757d89c}}</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=LuaWML/Units&diff=59692LuaWML/Units2018-05-22T10:39:44Z<p>Vultraz: </p>
<hr />
<div>This page describes the [[LuaWML]] functions for handling units.<br />
<br />
A unit is a proxy table with the following fields:<br />
* '''x''', '''y''': integers (read only, read/write if the unit is not on the map. {{DevFeature1.13|11}} These are now read/write under all circumstances, including for on-map units)<br />
* '''loc''': {{DevFeature1.13|11}} shortcut to get/set both x and y at once (read/write). Setting x and y individually would result in two moves, and there's the possibility one of those might move the unit off the map.<br />
* '''side''': integer (read/write)<br />
* '''id''': string (read only)<br />
* '''type''': string (read only)<br />
* '''name''': translatable string (read only)<br />
* '''cost''' {{DevFeature1.13|10}}: integer (read)<br />
* '''max_hitpoints''', '''experience''', '''max_experience''', '''max_moves''': integers (read only)<br />
* '''max_attacks''': integer (read only)<br />
* '''attacks_left''': integer (read/write) Setting below 0 is limited to 0.<br />
* '''extra_recruit''': table (read/write)<br />
* '''advances_to''': table (read/write)<br />
* '''hitpoints''', '''experience''': integer (read/write)<br />
* '''moves''': integer (read/write)<br />
* '''level''': {{DevFeature1.13|5}} integer (read/write)<br />
* '''resting''': boolean (read/write)<br />
* '''hidden''': boolean (read/write)<br />
* '''petrified''', '''canrecruit''': booleans (read only)<br />
* '''role''', '''facing''': strings (read/write)<br />
* '''status''': proxy associative table (read only, read/write fields), provides fields like [[SingleUnitWML#Unit_State|poisoned, slowed, petrified, uncovered, guardian, unhealable, invulnerable]]<br />
* '''image_mods''': string (read only)<br />
* '''upkeep''' {{DevFeature1.13|5}}: one of 'loyal', 'full' or a number (read/writre)<br />
* '''variables''': proxy associative table (read only, read/write fields, including ''variables.__cfg''), only toplevel named fields are proxied. {{DevFeature1.13|2}} subcontainers can be accessed by using the usual variable syntax: <syntaxhighlight inline lang='lua'>unit.variables["a.b.c[6].d"]</syntaxhighlight><br />
* '''attacks''': {{DevFeature1.13|0}}an object to access the units attacks, you can use the attacks index or the attacks name to index an attack. every attack has the following members:<br />
** '''description''': translatable string (read/write)<br />
** '''name''': string (read)<br />
** '''type''': string (read/write)<br />
** '''range''': string (read/write)<br />
** '''damage''': number(read/write)<br />
** '''number''': number(read/write)<br />
** '''movement_used''': number(read/write)<br />
** '''attack_weight''': number(read/write)<br />
** '''defense_weight''': number(read/write)<br />
** '''specials''' wml table(read/write)<br />
* '''valid''': string or nil (read only)<br />
* '''advancements''': {{DevFeature1.13|2}} an array of wml tables (read/write)<br />
* '''__cfg''': WML table (dump) ([[SingleUnitWML]])<br />
* {{DevFeature1.13|2}} The following fields are unit methods synonymous to one of the functions described on this page:<br />
** '''[[#wesnoth.match_unit|matches]]'''<br />
** '''[[#wesnoth.put_recall_unit|to_recall]]'''<br />
** '''[[#wesnoth.put_unit|to_map]]'''<br />
** '''[[#wesnoth.erase_unit|erase]]'''<br />
** '''[[#wesnoth.copy_unit|clone]]'''<br />
** '''[[#wesnoth.extract_unit|extract]]'''<br />
** '''[[#wesnoth.advance_unit|advance]]'''<br />
** '''[[#wesnoth.add_modification|add_modification]]'''<br />
** '''[[#wesnoth.remove_modification|remove_modification]]'''<br />
** '''[[#wesnoth.unit_resistance|resistance]]'''<br />
** '''[[#wesnoth.unit_defense|defense]]'''<br />
** '''[[#wesnoth.unit_movement_cost|movement]]'''<br />
** '''[[#wesnoth.unit_vision_cost|vision]]'''<br />
** '''[[#wesnoth.unit_jamming_cost|jamming]]'''<br />
** '''[[#wesnoth.unit_ability|ability]]'''<br />
** '''[[#wesnoth.transform_unit|transform]]'''<br />
The metatable of these proxy tables appears as '''"unit"'''.<br />
<br />
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.<br />
<br />
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).<br />
<br />
<br />
==== wesnoth.get_units ====<br />
<br />
* '''wesnoth.get_units(''filter'')'''<br />
* {{DevFeature1.13|12}} '''wesnoth.get_units(''filter'', ''fake_location'')'''<br />
* {{DevFeature1.13|12}} '''wesnoth.get_units(''filter'', ''other_unit'')'''<br />
<br />
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. If a second unit is passed, it can be referenced via the $other_unit variable in the main filter as well as via the "other" variable in WFL formulas used in the main filter. If a location is passed, the filter is run as if the unit were at that location (rather than its real location). This affects things such as [filter_adjacent] and ability_active, and should work even for a unit on the recall list.<br />
<br />
<syntaxhighlight lang='lua'><br />
local leaders_on_side_two = wesnoth.get_units { side = 2, canrecruit = true }<br />
local name_of_leader = leaders_on_side_two[1].name<br />
</syntaxhighlight><br />
<br />
==== wesnoth.get_unit ====<br />
<br />
* '''wesnoth.get_unit(''x'', ''y'')'''<br />
* '''wesnoth.get_unit(''underlying_id'')'''<br />
<br />
Returns the unit at the given location or with the given underlying ID.<br />
<br />
<syntaxhighlight lang='lua'><br />
local args = ...<br />
local unit = wesnoth.get_unit(args.x1, args.y1)<br />
</syntaxhighlight><br />
<br />
==== wesnoth.match_unit ====<br />
<br />
* '''wesnoth.match_unit(''unit'', ''filter'')'''<br />
* {{DevFeature1.13|2}} '''wesnoth.match_unit(''unit'', ''filter'', ''other_unit'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':matches(''filter'', [''other_unit''])'''<br />
* {{DevFeature1.13|2}} '''wesnoth.match_unit(''unit'', ''filter'', ''location'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':matches(''filter'', [''location''])'''<br />
<br />
Returns true if the given unit matches the WML filter passed as the second argument. If ''other_unit'' is specified, it is used for the ''$other_unit'' auto-stored variable in the filter. Otherwise, this variable is not stored for the filter. If an extra ''location'' is specified, the filter matches as if the unit were at that location.<br />
<br />
<syntaxhighlight lang='lua'><br />
assert(unit.canrecruit == wesnoth.match_unit(unit, { canrecruit = true }))<br />
</syntaxhighlight><br />
<br />
==== wesnoth.put_unit ====<br />
<br />
* '''wesnoth.put_unit(''unit'')'''<br />
* '''wesnoth.put_unit(''x'', ''y'', ''unit'')'''<br />
* '''wesnoth.put_unit(''x'', ''y'')'''<br />
* {{DevFeature1.13|2}} '''wesnoth.put_unit(''unit'', ''x'', ''y'')''' -- The above two forms are also deprecated.<br />
* {{DevFeature1.13|2}} '''''unit'':to_map([''x'', ''y''])<br />
<br />
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. {{DevFeature1.13|2}} This use is now deprecated; use wesnoth.erase_unit instead.<br />
<br />
<syntaxhighlight lang='lua'><br />
-- create a unit with random traits, then erase it<br />
wesnoth.put_unit(17, 42, { type = "Elvish Lady" })<br />
wesnoth.put_unit(17, 42)<br />
</syntaxhighlight><br />
<br />
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.<br />
<br />
<syntaxhighlight lang='lua'><br />
-- move the leader back to the top-left corner<br />
wesnoth.put_unit(1, 1, wesnoth.get_units({ canrecruit = true })[1])<br />
</syntaxhighlight><br />
<br />
==== wesnoth.erase_unit ====<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
* '''wesnoth.erase_unit(''unit'')'''<br />
* '''wesnoth.erase_unit(''x'', ''y'')'''<br />
* '''''unit'':erase()'''<br />
<br />
Erases a unit from the map. After calling this on a unit, the unit is no longer valid.<br />
<br />
==== wesnoth.get_recall_units ====<br />
<br />
* '''wesnoth.get_recall_units()'''<br />
<br />
Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.<br />
<br />
==== wesnoth.put_recall_unit ====<br />
<br />
* '''wesnoth.put_recall_unit(''unit'', [''side''])'''<br />
* {{DevFeature1.13|2}} '''''unit'':to_recall([''side''])'''<br />
<br />
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.<br />
<br />
<syntaxhighlight lang='lua'><br />
-- put the unit at location 17,42 on the recall list for side 2<br />
wesnoth.put_recall_unit(wesnoth.get_units({ x= 17, y = 42 })[1], 2)<br />
</syntaxhighlight><br />
<br />
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.<br />
<br />
==== wesnoth.create_unit ====<br />
<br />
* '''wesnoth.create_unit(''unit_info'')'''<br />
<br />
Creates a private unit from a WML table.<br />
<br />
<syntaxhighlight lang='lua'><br />
local u = wesnoth.create_unit { type = "White Mage", gender = "female" }<br />
</syntaxhighlight><br />
<br />
==== wesnoth.copy_unit ====<br />
<br />
* '''wesnoth.copy_unit(''unit'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':clone()'''<br />
<br />
Creates a private unit from another unit.<br />
<br />
<syntaxhighlight lang='lua'><br />
-- extract a unit from the map<br />
local u = wesnoth.copy_unit(wesnoth.get_units({ type = "Thug" })[1])<br />
wesnoth.erase_unit(u.x, u.y)<br />
-- u is still valid at this point<br />
</syntaxhighlight><br />
<br />
==== wesnoth.extract_unit ====<br />
<br />
* '''wesnoth.extract_unit(''unit'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':extract()'''<br />
<br />
Removes a unit from the map or from a recall list and makes it private.<br />
<br />
<syntaxhighlight lang='lua'><br />
-- remove all the units from the recall list of side 1 and put them in a WML container<br />
local l = {}<br />
for i,u in ipairs(wesnoth.get_recall_units { side = 1 }) do<br />
wesnoth.extract_unit(u)<br />
table.insert(l, u.__cfg)<br />
end<br />
helper.set_variable_array("player_recall_list", l)<br />
</syntaxhighlight><br />
<br />
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.<br />
<br />
<br />
==== wesnoth.advance_unit ====<br />
<br />
* '''wesnoth.advance_unit(''unit'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':advance()'''<br />
<br />
{{DevFeature1.13|0}} Advances the unit (and shows the advance unit dialog if needed) if the unit has enough xp. This function should be called after modifying the units experience directly. A similar function is called by wesnoth internally after unit combat. The second argument is a boodean value that specifies whether the advancement should be animated. The third agrument is a boodean value that specifies whether advancement related events should be fired.<br />
<br />
<br />
This function only works for units on the map.<br />
<br />
This function can also trigger multiple advancements if the unit has enough xp.<br />
<br />
==== wesnoth.add_modification ====<br />
<br />
* '''wesnoth.add_modification(''unit'', ''type'', ''effects'', [''write_to_mods''])'''<br />
* {{DevFeature1.13|2}} '''''unit'':add_modification(''type'', ''effects'', [''write_to_mods''])'''<br />
<br />
Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (one of "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.<br />
<br />
{{DevFeature1.13|2}} In 1.13.2 and later, the "advance" type is replaced with "advancement", to match the equivalent tag in [[UnitTypeWML|[unit_type]]]. Also, it takes a fourth argument which, if false, causes it to not write the modification tag to the unit's [modifications] (as would be done with an [object] with no_write=true).<br />
<br />
<syntaxhighlight lang='lua'><br />
local u = wesnoth.get_units { canrecruit = true }[1]<br />
wesnoth.add_modification(u, "object", { { "effect", { apply_to = "image_mod", replace = "RC(red>blue)" } } })<br />
</syntaxhighlight><br />
<br />
==== wesnoth.remove_modifications ====<br />
<br />
* {{DevFeature1.13|?}} '''wesnoth.remove_modifications(''unit'', ''cfg'' [, ''type''])'''<br />
* {{DevFeature1.13|?}} '''''unit'':remove_modifications(''cfg'' [, ''type''])'''<br />
<br />
Modifies a given unit. The unit needs to be a proxy unit. The second argument is a filter for the modifications to remove. It takes the same syntax as [[FilterWML#Filtering_on_WML_data|[filter_wml]]]; all matching modifications will be removed. The third argument is the type (tag name) of the modifications to search for; it defaults to <tt>"object"</tt>, but you can also pass <tt>"trait"</tt> or <tt>"advancement"</tt>.<br />
<br />
<syntaxhighlight lang='lua'><br />
local u = wesnoth.get_units { canrecruit = true }[1]<br />
wesnoth.remove_modifications(u, { id = your_object_id })<br />
</syntaxhighlight><br />
<br />
==== wesnoth.unit_resistance ====<br />
<br />
* '''wesnoth.unit_resistance(''unit'', ''damage_type'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':resistance(''damage_type'')'''<br />
<br />
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).<br />
<br />
<syntaxhighlight lang='lua'><br />
local fire_resistance = 100 - wesnoth.unit_resistance(u, "fire")<br />
</syntaxhighlight><br />
<br />
==== wesnoth.unit_defense ====<br />
<br />
* '''wesnoth.unit_defense(''unit'', ''terrain_code'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':defense(''terrain_code'')'''<br />
<br />
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.)<br />
<br />
<syntaxhighlight lang='lua'><br />
local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")<br />
</syntaxhighlight><br />
<br />
==== wesnoth.unit_movement_cost ====<br />
<br />
* '''wesnoth.unit_movement_cost(''unit'', ''terrain_code'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':movement(''terrain_code'')'''<br />
<br />
Returns the movement cost of a unit on a particular terrain.<br />
<br />
<syntaxhighlight lang='lua'><br />
local move_cost = wesnoth.unit_movement_cost(u, "Gt")<br />
<syntaxhighlight><br />
<br />
==== wesnoth.unit_vision_cost ====<br />
<br />
* '''wesnoth.unit_vision_cost(''unit'', ''terrain_code'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':vision(''terrain_code'')'''<br />
<br />
Returns the vision cost of a unit on a particular terrain.<br />
<br />
<syntaxhighlight lang='lua'><br />
local see_cost = wesnoth.unit_vision_cost(u, "Gt")<br />
</syntaxhighlight><br />
<br />
==== wesnoth.unit_jamming_cost ====<br />
<br />
* '''wesnoth.unit_jamming_cost(''unit'', ''terrain_code'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':jamming(''terrain_code'')'''<br />
<br />
Returns the jamming cost of a unit on a particular terrain.<br />
<br />
<syntaxhighlight lang='lua'><br />
local jam_cost = wesnoth.unit_jamming_cost(u, "Gt")<br />
</syntaxhighlight><br />
<br />
==== wesnoth.unit_ability ====<br />
<br />
* '''wesnoth.unit_ability(''unit'', ''ability_tag'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':ability(''ability_tag'')'''<br />
<br />
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.<br />
<br />
<syntaxhighlight lang='lua'><br />
function has_teleport(u)<br />
return wesnoth.unit_ability(u, "teleport")<br />
end<br />
</syntaxhighlight><br />
<br />
==== wesnoth.unit_types ====<br />
<br />
This is not a function but a read-only table indexed by unit type ids. Its elements are proxy tables with these fields:<br />
<br />
* '''id''': string<br />
* '''name''': translatable string (read only)<br />
* '''max_moves''', '''max_experience''', '''max_hitpoints''', '''level''', '''cost''': integers (read only)<br />
* '''abilities''': array of ability keys (strings), e.g. {"curing", "regenerates"}<br />
* {{DevFeature1.13|11}} '''advances_to''': array of unit types to which unit can advance<br />
* {{DevFeature1.13|11}} '''advances_from''': array of unit types from which unit can advance. Note: this is OOS-unsafe in Multiplayer games. Different clients may have additional Era-s with units upgradable to this unit type.<br />
* '''__cfg''': WML table (dump), see [[UnitTypeWML]]<br />
<br />
The metatable of these proxy tables appears as '''"unit type"'''.<br />
<br />
<syntaxhighlight lang='lua'><br />
local lich_cost = wesnoth.unit_types["Ancient Lich"].cost<br />
</syntaxhighlight><br />
<br />
Note that different clients have different set of available units in a Multiplayer game. It is OOS-unsafe to e.g. count the number of units.<br />
Presuming correctly written add-ons, it is still safe to e.g. access any given unit or its properties.<br />
<br />
==== wesnoth.races ====<br />
<br />
This is not a function but a table indexed by race ids. Its elements are proxy tables for all races the engine knows about.<br />
known fields of each element:<br />
* '''id''': string<br />
* '''description''', '''name''', '''plural_name''' (translatable strings)<br />
* '''num_traits''' (integer)<br />
* '''ignore_global_traits''' (boolean)<br />
* '''undead_variation''' (string)<br />
(all read only)<br />
* '''__cfg''': WML table (dump)<br />
<br />
<syntaxhighlight lang='lua'><br />
wesnoth.message(tostring(wesnoth.races["lizard"].name))<br />
</syntaxhighlight><br />
<br />
==== wesnoth.get_traits ====<br />
<br />
* '''wesnoth.get_traits()'''<br />
<br />
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.<br />
Known fields and subtags of each element are the ones which were given in the wml definition of the [[SingleUnitWML|trait]].<br />
wesnoth.message(tostring(wesnoth.get_traits().strong.male_name))<br />
<br />
==== wesnoth.simulate_combat ====<br />
<br />
* '''wesnoth.simulate_combat(''attacker'', [''attacker_weapon_index''], ''defender'', [''defender_weapon_index''])'''<br />
<br />
Computes the hitpoint distribution and status chance after a combat between two units. 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.<br />
<br />
Optional integers can be passed after each unit to select a particular weapon, otherwise the "best" one is selected. When giving the weapon, the parameter is the weapon number (integer, starting at 1) and not an element from the table returned by helper.child_range(att, "attack").<br />
<br />
<syntaxhighlight lang='lua'><br />
local function display_stats(n, t)<br />
wesnoth.message(string.format(<br />
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",<br />
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))<br />
end<br />
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def, def_weapon)<br />
display_stats("attacker", att_stats)<br />
display_stats("defender", def_stats)<br />
</syntaxhighlight><br />
<br />
Returns 2 additional tables which contain information about the weapons and the effect of single hits with these keys: num_blows, damage, chance_to_hit, poisons, slows, petrifies, plagues, plague_type, backstabs, rounds, firststrike, drains, drain_constant, drain_percent, attack_num, name. <br />
Name is the wml name not the description. If there is no weapon, then name will be nil<br />
<br />
<syntaxhighlight lang='lua'><br />
local att_stats, def_stats, att_weapon, def_weapon = wesnoth.simulate_combat(attacker, att_weapon_number, defender)<br />
wesnoth.message(string.format(<br />
"The attack %s should be countered with %s, which does %d damage, has %d%% chance to hit and forces %d attack rounds due to its berserk ability.",<br />
att_weapon.name, def_weapon.name or "no weapon", def_weapon.damage, def_weapon.chance_to_hit, def_weapon.rounds))<br />
</syntaxhighlight><br />
<br />
==== wesnoth.transform_unit ====<br />
<br />
* '''wesnoth.transform_unit(''unit'', ''to_type'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':transform(''to_type'')'''<br />
<br />
Changes the type of a unit and adjust attributes accordingly. Note that hit points are only changed if necessary to accommodate the new maximum hit points. Poison is automatically removed if the transformed unit is immune.<br />
<br />
<syntaxhighlight lang='lua'><br />
local ev = wesnoth.current.event_context<br />
local u = wesnoth.get_units{x=ev.x1, y=ev.y1}[1]<br />
wesnoth.transform_unit(u, "Spearman")<br />
-- If a full heal is desired:<br />
u.hitpoints = u.max_hitpoints<br />
u.status.poisoned = false<br />
</syntaxhighlight><br />
<br />
==== wesnoth.add_known_unit ====<br />
<br />
* {{DevFeature1.13|10}} '''wesnoth.add_known_unit(''unit_type_id'')'''<br />
<br />
adds the unit type with the given id to the list of known units (so thath they appear in the help)<br />
<br />
==== wesnoth.create_animator ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.create_animator()'''<br />
<br />
Returns an object that can be used to set up and run an animation. The object has three methods:<br />
<br />
* '''animator:run()'''<br />
<br />
Runs the animation.<br />
<br />
* '''animator:clear()'''<br />
<br />
Clears any units previously added to the animation.<br />
<br />
* '''animator:add(''unit'', ''flag'', ''hits'', ''params'')'''<br />
<br />
Adds a unit to the animation. The ''flag'' specifies which animation to play, and the ''hits'' parameter is required for attack animations to specify which variant of the animation to play. Possibly keys in ''params'' are:<br />
<br />
* '''facing''': A location. The animation will be played with the unit facing that location.<br />
* '''value''': Either a number or a list of two numbers. Use this to pass ''value'' and/or ''value_second'' to default animations that use them.<br />
* '''with_bars''': Whether to show HP bars and such while the animation plays.<br />
* '''text''': Text to float as the animation plays.<br />
* '''color''': Color of the floating text - a list of red, green, blue.<br />
* '''primary''': The primary weapon to use for the animation. Must be a Lua unit attack proxy.<br />
* '''secondary''': The secondary weapon to use for the animation.<br />
<br />
Normal usage would be to create it, call '''add''' one or more times, then call '''run'''.<br />
<br />
==== wesnoth.effects ====<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
This table contains the implementation of custom [[EffectWML|[effect]]]s. Each value is a function that takes a unit and the effect config. Note that the default effects defined by the Wesnoth engine are not in this table. <br />
<br />
<syntaxhighlight lang='lua'><br />
function wesnoth.effects.min_resistance(u, cfg)<br />
local resistance_new = {}<br />
local resistance_old = helper.parsed(helper.get_child(cfg, "resistance"))<br />
for k,v in pairs(resistance_old) do<br />
if type(k) == "string" and type(v) == "number" and wesnoth.unit_resistance(u, k) >= v then<br />
resistance_new[k] = v<br />
end<br />
end<br />
--important: use wesnoth.add_modification(..., false) so that the function will only execute the effects of that object and not store the object in the unit.<br />
wesnoth.add_modification(u, "object", {<br />
T.effect {<br />
apply_to = "resistance",<br />
replace = true,<br />
T.resistance (resistance_new),<br />
},<br />
}, false)<br />
end<br />
</syntaxhighlight><br />
<br />
The code above adds a new <code>min_resistance</code> effect that will set the resistances to specific values if they are currently below that value. It can then be used like this (for example, in [[DirectActionsWML#.5Bobject.5D|[object]]]):<br />
<br />
<syntaxhighlight lang='wml'><br />
[effect]<br />
apply_to=min_resistance<br />
[resistance]<br />
cold=50<br />
[/resistance]<br />
[/effect]<br />
</syntaxhighlight><br />
<br />
Note that because currently all Lua code is executed after [unit]s in [side] are created, it is currently not possible to use these effects in [unit]s in [side]<br />
<br />
{{DevFeature1.13|5}}<br />
<br />
Built-in effects are now present in the <code>wesnoth.effects</code> table and can be called by custom effects or by other Lua code. They take the same two arguments that a custom effect function does - the unit, and the effect WML.<br />
<br />
In addition, you can now specify description modifiers to be used if a custom effect is placed in a <code>[trait]</code> tag. Instead of setting a function as the effect, you set a table with a <code>__call</code> metafunction which does what the function would have done. The table can then have an additional <code>__descr</code> metafunction which updates descriptions as necessary. The built-in effects all use this structure. This metafunction takes the same arguments as the regular effect function, but should not modify the unit. Instead, it returns a string to be appended to the trait's effect description.<br />
<br />
[[Category: Lua Reference]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:StableDownload&diff=59619Template:StableDownload2018-05-09T20:48:33Z<p>Vultraz: Updated links for 1.14.1.</p>
<hr />
<div><noinclude><br />
== Stable (1.14 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.1 | filename=wesnoth-1.14.1.tar.bz2 | size=442.4 MB | hash=6bf655b4df17098104a23078fb796c91223aca8294a15e58209aac70f6b2f9d7}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.0 | filename=wesnoth-1.14.0.tar.bz2 | size=442.2 MB | hash=7c81ca4a4896a34789514025b999daf028d846b70aa556e18fca9de047c1d126 }}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.1 | filename=wesnoth-1.14.1-win32.exe | size=403.2 MB | hash=38d6a3bc7b5005a78980ae4c8341ab682fc6997e7a4e56b07562844ebb6326ef}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.0 | filename=wesnoth-1.14.0-win32.exe | size=403.1 MB | hash=6302681505f3903dc9b52bf81acc13c32f81197c56763594373ca56f2fa624d4 }}<br />
<br />
==== macOS (10.8 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.1 | filename=Wesnoth_1.14.1a.dmg | size=450.5 MB | hash=d76d60492546877b015b6aa185c0e500e64c39a643a1137f89bf4eedd757d89c}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.14 | version=1.14.0 | filename=Wesnoth_1.14.0.dmg | size=447.0 MB | hash=a3f6e723517e6adbc997981e7c4f764448d2faa620492d75ecbd29294f162da9}}</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Download&diff=59570Download2018-05-02T00:50:44Z<p>Vultraz: </p>
<hr />
<div><!--{{Translations}}--><br />
Welcome to the ''Battle for Wesnoth'' downloads page. The BfW project team officially releases the source code and builds for Windows, macOS, and various Linux distributions.<br />
<br />
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_X.2C_etc..5D.3F|FAQ]].<br />
<br />
Wesnoth is also available for OS X from [http://brew.sh/ Homebrew] and [http://www.macports.org/ Macports]. Macports carries only the stable version. Homebrew carries stable releases, development releases, and can also build the "bleeding edge" master branch from the [[WesnothRepository|Git repository]].<br />
__NOTOC__<br />
== Stable (1.14 branch) ==<br />
<b>1.14.x</b> is the current stable branch. These releases are recommended for most players, as they provide a well-tested and balanced game experience with only occasional bug-fix updates. Each version of this branch is compatible with each other. The online player community for it is also the largest and the add-ons server has a vast selection of content.<br />
<br />
==== Source code ====<br />
* [[CompilingWesnoth|Compiling Guide]] - How to compile the source code<br />
{{StableDownload}}<br />
<br />
==== GNU/Linux ====<br />
* 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.<br />
<br />
==== Miscellaneous ====<br />
* [[Download_Xdeltas#Stable_Version_1.14.x|Xdelta for the source code]]<br />
* [https://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]<br />
<!--<br />
== Development (1.15 branch) ==<br />
<b>1.15.x</b> is the current development branch, boasting new exciting features. However, there may be occasional bugs or performance problems in these releases. Content creators, coders, and players who want to preview the future of Wesnoth may be interested in checking out our work in this branch.<br />
<br />
People familiar with version control systems and building the game from source may follow Wesnoth development even more closely using the [[WesnothRepository|Git repository]] instead.<br />
<br />
==== Source code ====<br />
* [[CompilingWesnoth|Compiling Guide]] - How to compile the source code<br />
{{DevDownload}}<br />
<br />
==== GNU/Linux ====<br />
* 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.<br />
<br />
==== Miscellaneous ====<br />
* [[Download_Xdeltas#Development_Version_1.15.x|Xdelta for the source code]]<br />
* [https://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]<br />
* [https://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.13.zip/download MacCompileStuff for 1.13]<br />
--><br />
== License ==<br />
''Main article: [[Wesnoth:Copyrights]]''<br />
<br />
This program is free software; you can redistribute it and/or modify it under the terms of the [https://www.gnu.org/licenses/gpl-2.0.html GNU General Public License version 2], as published by the [https://www.fsf.org Free Software Foundation], or at your option, any later version.<br />
<br />
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.<br />
<br />
Some assets included with the game are provided under the terms of the [https://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 license].<br />
<br />
== UMC Editor ==<br />
<br />
This is available with Wesnoth 1.9.x and greater. Details and installation steps can be found at: http://eclipse.wesnoth.org<br />
<br />
== See also ==<br />
* [https://changelog.wesnoth.org/1.14 Changelog for the stable version]<br />
* [https://changelog.wesnoth.org Changelog for the development version]<br />
* [[WesnothRepository]] - bleeding edge version from the repository<br />
<br />
[[Category:Building and Installing]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:StableDownload&diff=59569Template:StableDownload2018-05-02T00:50:28Z<p>Vultraz: </p>
<hr />
<div><noinclude><br />
== Stable (1.14 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.0 | filename=wesnoth-1.14.0.tar.bz2 | size=442.2 MB | hash=7c81ca4a4896a34789514025b999daf028d846b70aa556e18fca9de047c1d126 }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.12 | version=1.12.6 | filename=wesnoth-1.12.6.tar.bz2 | size=387.9 MB | hash=a50f384cead15f68f31cfa1a311e76a12098428702cb674d3521eb169eb92e4e }}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.0 | filename=wesnoth-1.14.0-win32.exe | size=403.1 MB | hash=6302681505f3903dc9b52bf81acc13c32f81197c56763594373ca56f2fa624d4 }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.12 | version=1.12.6 | filename=wesnoth-1.12.6-win32.exe | size=353.0 MB | hash=340a045deafcc236d2e00cb47598b4a5e8d656463270a3433ed637108916db71 }}<br />
<br />
==== macOS (10.8 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth-1.14 | version=1.14.0 | filename=Wesnoth_1.14.0.dmg | size=447.0 MB | hash=a3f6e723517e6adbc997981e7c4f764448d2faa620492d75ecbd29294f162da9 }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth-1.12 | version=1.12.6 | filename=Wesnoth_1.12.6.dmg | size=391.2 MB | hash=9b6415b04baa9bee3104b48a19c227d66b7a522be8ca60fccdb39b4653b03bc7 }}</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=59431Template:DevDownload2018-04-17T01:52:47Z<p>Vultraz: </p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.14 | filename=wesnoth-1.13.14.tar.bz2 | size=434.9 MB | hash=0d01af8499cd9eb3906d293cbfba492fadd5f9d5b8dc97a08923b7c6319ebb1b}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.13 | filename=wesnoth-1.13.13.tar.bz2 | size=430.1 MB | hash=0c5065c0f9934407b303dc68016414afb370439c172f52dbe6cda20ef87ec3ca}}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.14 | filename=wesnoth-1.13.14-win32.exe | size=395.9 MB | hash=f490f86459e6a95fc92fb44b9b0ab94245e22047f72176cc53cfb75466e04013}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.13 | filename=wesnoth-1.13.13-win32.exe | size=390.1 MB | hash=9524b5f1ccc45b043ff26f5d0535dfdf6745126bb71ee2980c4c75a9023772fe}}<br />
<br />
==== macOS (10.8 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.14 | filename=Wesnoth_1.13.14.dmg | size=439.1 MB | hash=9436fc0e9231b9bfeb06f11a4175ba573fbef42d28ec8e4f7eaa332dc8463c16}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.13 | filename=Wesnoth_1.13.13.dmg | size=435.8 MB | hash=ac38390f71500b238c0f37319ab6eed8c24f2db15fa990ae01bd84903e1221de}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=LuaWML/Units&diff=59356LuaWML/Units2018-04-02T20:47:31Z<p>Vultraz: /* wesnoth.get_units */</p>
<hr />
<div>This page describes the [[LuaWML]] functions for handling units.<br />
<br />
A unit is a proxy table with the following fields:<br />
* '''x''', '''y''': integers (read only, read/write if the unit is not on the map)<br />
* '''side''': integer (read/write)<br />
* '''id''': string (read only)<br />
* '''type''': string (read only)<br />
* '''name''': translatable string (read only)<br />
* '''cost''' {{DevFeature1.13|10}}: integer (read)<br />
* '''max_hitpoints''', '''experience''', '''max_experience''', '''max_moves''': integers (read only)<br />
* '''max_attacks''': integer (read only)<br />
* '''attacks_left''': integer (read/write) Setting below 0 is limited to 0.<br />
* '''extra_recruit''': table (read/write)<br />
* '''advances_to''': table (read/write)<br />
* '''hitpoints''', '''experience''': integer (read/write)<br />
* '''moves''': integer (read/write)<br />
* '''level''': {{DevFeature1.13|5}} integer (read/write)<br />
* '''resting''': boolean (read/write)<br />
* '''hidden''': boolean (read/write)<br />
* '''petrified''', '''canrecruit''': booleans (read only)<br />
* '''role''', '''facing''': strings (read/write)<br />
* '''status''': proxy associative table (read only, read/write fields), provides fields like [[SingleUnitWML#Unit_State|poisoned, slowed, petrified, uncovered, guardian, unhealable, invulnerable]]<br />
* '''image_mods''': string (read only)<br />
* '''upkeep''' {{DevFeature1.13|5}}: one of 'loyal', 'full' or a number (read/writre)<br />
* '''variables''': proxy associative table (read only, read/write fields, including ''variables.__cfg''), only toplevel named fields are proxied. {{DevFeature1.13|2}} subcontainers can be accessed by using the usual variable syntax: <syntaxhighlight inline lang='lua'>unit.variables["a.b.c[6].d"]</syntaxhighlight><br />
* '''attacks''': {{DevFeature1.13|0}}an object to access the units attacks, you can use the attacks index or the attacks name to index an attack. every attack has the following members:<br />
** '''description''': translatable string (read/write)<br />
** '''name''': string (read)<br />
** '''type''': string (read/write)<br />
** '''range''': string (read/write)<br />
** '''damage''': number(read/write)<br />
** '''number''': number(read/write)<br />
** '''movement_used''': number(read/write)<br />
** '''attack_weight''': number(read/write)<br />
** '''defense_weight''': number(read/write)<br />
** '''specials''' wml table(read/write)<br />
* '''valid''': string or nil (read only)<br />
* '''advancements''': {{DevFeature1.13|2}} an array of wml tables (read/write)<br />
* '''__cfg''': WML table (dump) ([[SingleUnitWML]])<br />
* {{DevFeature1.13|2}} The following fields are unit methods synonymous to one of the functions described on this page:<br />
** '''[[#wesnoth.match_unit|matches]]'''<br />
** '''[[#wesnoth.put_recall_unit|to_recall]]'''<br />
** '''[[#wesnoth.put_unit|to_map]]'''<br />
** '''[[#wesnoth.erase_unit|erase]]'''<br />
** '''[[#wesnoth.copy_unit|clone]]'''<br />
** '''[[#wesnoth.extract_unit|extract]]'''<br />
** '''[[#wesnoth.advance_unit|advance]]'''<br />
** '''[[#wesnoth.add_modification|add_modification]]'''<br />
** '''[[#wesnoth.unit_resistance|resistance]]'''<br />
** '''[[#wesnoth.unit_defense|defense]]'''<br />
** '''[[#wesnoth.unit_movement_cost|movement]]'''<br />
** '''[[#wesnoth.unit_vision_cost|vision]]'''<br />
** '''[[#wesnoth.unit_jamming_cost|jamming]]'''<br />
** '''[[#wesnoth.unit_ability|ability]]'''<br />
** '''[[#wesnoth.transform_unit|transform]]'''<br />
The metatable of these proxy tables appears as '''"unit"'''.<br />
<br />
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.<br />
<br />
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).<br />
<br />
<br />
==== wesnoth.get_units ====<br />
<br />
* '''wesnoth.get_units(''filter'')'''<br />
<br />
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.<br />
<br />
local leaders_on_side_two = wesnoth.get_units { side = 2, canrecruit = true }<br />
local name_of_leader = leaders_on_side_two[1].name<br />
<br />
==== wesnoth.get_unit ====<br />
<br />
* '''wesnoth.get_unit(''x'', ''y'')'''<br />
* '''wesnoth.get_unit(''underlying_id'')'''<br />
<br />
Returns the unit at the given location or with the given underlying ID.<br />
<br />
local args = ...<br />
local unit = wesnoth.get_unit(args.x1, args.y1)<br />
<br />
==== wesnoth.match_unit ====<br />
<br />
* '''wesnoth.match_unit(''unit'', ''filter'')'''<br />
* {{DevFeature1.13|2}} '''wesnoth.match_unit(''unit'', ''filter'', ''other_unit'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':matches(''filter'', [''other_unit''])'''<br />
* {{DevFeature1.13|2}} '''wesnoth.match_unit(''unit'', ''filter'', ''location'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':matches(''filter'', [''location''])'''<br />
<br />
Returns true if the given unit matches the WML filter passed as the second argument. If ''other_unit'' is specified, it is used for the ''$other_unit'' auto-stored variable in the filter. Otherwise, this variable is not stored for the filter. If an extra ''location'' is specified, the filter matches as if the unit were at that location.<br />
<br />
assert(unit.canrecruit == wesnoth.match_unit(unit, { canrecruit = true }))<br />
<br />
==== wesnoth.put_unit ====<br />
<br />
* '''wesnoth.put_unit(''unit'')'''<br />
* '''wesnoth.put_unit(''x'', ''y'', ''unit'')'''<br />
* '''wesnoth.put_unit(''x'', ''y'')'''<br />
* {{DevFeature1.13|2}} '''wesnoth.put_unit(''unit'', ''x'', ''y'')''' -- The above two forms are also deprecated.<br />
* {{DevFeature1.13|2}} '''''unit'':to_map([''x'', ''y''])<br />
<br />
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. {{DevFeature1.13|2}} This use is now deprecated; use wesnoth.erase_unit instead.<br />
<br />
-- create a unit with random traits, then erase it<br />
wesnoth.put_unit(17, 42, { type = "Elvish Lady" })<br />
wesnoth.put_unit(17, 42)<br />
<br />
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.<br />
<br />
-- move the leader back to the top-left corner<br />
wesnoth.put_unit(1, 1, wesnoth.get_units({ canrecruit = true })[1])<br />
<br />
==== wesnoth.erase_unit ====<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
* '''wesnoth.erase_unit(''unit'')'''<br />
* '''wesnoth.erase_unit(''x'', ''y'')'''<br />
* '''''unit'':erase()'''<br />
<br />
Erases a unit from the map. After calling this on a unit, the unit is no longer valid.<br />
<br />
==== wesnoth.get_recall_units ====<br />
<br />
* '''wesnoth.get_recall_units()'''<br />
<br />
Returns an array of all the units on the recall lists matching the WML filter passed as the first argument.<br />
<br />
==== wesnoth.put_recall_unit ====<br />
<br />
* '''wesnoth.put_recall_unit(''unit'', [''side''])'''<br />
* {{DevFeature1.13|2}} '''''unit'':to_recall([''side''])'''<br />
<br />
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.<br />
<br />
-- put the unit at location 17,42 on the recall list for side 2<br />
wesnoth.put_recall_unit(wesnoth.get_units({ x= 17, y = 42 })[1], 2)<br />
<br />
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.<br />
<br />
==== wesnoth.create_unit ====<br />
<br />
* '''wesnoth.create_unit(''unit_info'')'''<br />
<br />
Creates a private unit from a WML table.<br />
<br />
local u = wesnoth.create_unit { type = "White Mage", gender = "female" }<br />
<br />
==== wesnoth.copy_unit ====<br />
<br />
* '''wesnoth.copy_unit(''unit'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':clone()'''<br />
<br />
Creates a private unit from another unit.<br />
<br />
-- extract a unit from the map<br />
local u = wesnoth.copy_unit(wesnoth.get_units({ type = "Thug" })[1])<br />
wesnoth.put_unit(u.x, u.y)<br />
-- u is still valid at this point<br />
<br />
==== wesnoth.extract_unit ====<br />
<br />
* '''wesnoth.extract_unit(''unit'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':extract()'''<br />
<br />
Removes a unit from the map or from a recall list and makes it private.<br />
<br />
-- remove all the units from the recall list of side 1 and put them in a WML container<br />
local l = {}<br />
for i,u in ipairs(wesnoth.get_recall_units { side = 1 }) do<br />
wesnoth.extract_unit(u)<br />
table.insert(l, u.__cfg)<br />
end<br />
helper.set_variable_array("player_recall_list", l)<br />
<br />
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.<br />
<br />
<br />
==== wesnoth.advance_unit ====<br />
<br />
* '''wesnoth.advance_unit(''unit'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':advance()'''<br />
<br />
{{DevFeature1.13|0}} Advances the unit (and shows the advance unit dialog if needed) if the unit has enough xp. This function should be called after modifying the units experience directly. A similar function is called by wesnoth internally after unit combat. The second argument is a boodean value that specifies whether the advancement should be animated. The third agrument is a boodean value that specifies whether advancement related events should be fired.<br />
<br />
<br />
This function only works for units on the map.<br />
<br />
This function can also trigger multiple advancements if the unit has enough xp.<br />
<br />
==== wesnoth.add_modification ====<br />
<br />
* '''wesnoth.add_modification(''unit'', ''type'', ''effects'', [''write_to_mods''])'''<br />
* {{DevFeature1.13|2}} '''''unit'':add_modification(''type'', ''effects'', [''write_to_mods''])'''<br />
<br />
Modifies a given unit. It needs to be a proxy unit. The second argument is the type of the modification (one of "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.<br />
<br />
{{DevFeature1.13|2}} In 1.13.2 and later, the "advance" type is replaced with "advancement", to match the equivalent tag in [[UnitTypeWML|[unit_type]]]. Also, it takes a fourth argument which, if false, causes it to not write the modification tag to the unit's [modifications] (as would be done with an [object] with no_write=true).<br />
<br />
local u = wesnoth.get_units { canrecruit = true }[1]<br />
wesnoth.add_modification(u, "object", { { "effect", { apply_to = "image_mod", replace = "RC(red>blue)" } } })<br />
<br />
==== wesnoth.unit_resistance ====<br />
<br />
* '''wesnoth.unit_resistance(''unit'', ''damage_type'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':resistance(''damage_type'')'''<br />
<br />
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).<br />
<br />
local fire_resistance = 100 - wesnoth.unit_resistance(u, "fire")<br />
<br />
==== wesnoth.unit_defense ====<br />
<br />
* '''wesnoth.unit_defense(''unit'', ''terrain_code'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':defense(''terrain_code'')'''<br />
<br />
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.)<br />
<br />
local flat_defense = 100 - wesnoth.unit_defense(u, "Gt")<br />
<br />
==== wesnoth.unit_movement_cost ====<br />
<br />
* '''wesnoth.unit_movement_cost(''unit'', ''terrain_code'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':movement(''terrain_code'')'''<br />
<br />
Returns the movement cost of a unit on a particular terrain.<br />
<br />
local move_cost = wesnoth.unit_movement_cost(u, "Gt")<br />
<br />
==== wesnoth.unit_vision_cost ====<br />
<br />
* '''wesnoth.unit_vision_cost(''unit'', ''terrain_code'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':vision(''terrain_code'')'''<br />
<br />
Returns the vision cost of a unit on a particular terrain.<br />
<br />
local see_cost = wesnoth.unit_vision_cost(u, "Gt")<br />
<br />
==== wesnoth.unit_jamming_cost ====<br />
<br />
* '''wesnoth.unit_jamming_cost(''unit'', ''terrain_code'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':jamming(''terrain_code'')'''<br />
<br />
Returns the jamming cost of a unit on a particular terrain.<br />
<br />
local jam_cost = wesnoth.unit_jamming_cost(u, "Gt")<br />
<br />
==== wesnoth.unit_ability ====<br />
<br />
* '''wesnoth.unit_ability(''unit'', ''ability_tag'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':ability(''ability_tag'')'''<br />
<br />
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.<br />
<br />
function has_teleport(u)<br />
return wesnoth.unit_ability(u, "teleport")<br />
end<br />
<br />
==== wesnoth.unit_types ====<br />
<br />
This is not a function but a read-only table indexed by unit type ids. Its elements are proxy tables with these fields:<br />
<br />
* '''id''': string<br />
* '''name''': translatable string (read only)<br />
* '''max_moves''', '''max_experience''', '''max_hitpoints''', '''level''', '''cost''': integers (read only)<br />
* '''abilities''': array of ability keys (strings), e.g. {"curing", "regenerates"}<br />
* {{DevFeature1.13|11}} '''advances_to''': array of unit types to which unit can advance<br />
* {{DevFeature1.13|11}} '''advances_from''': array of unit types from which unit can advance. Note: this is OOS-unsafe in Multiplayer games. Different clients may have additional Era-s with units upgradable to this unit type.<br />
* '''__cfg''': WML table (dump), see [[UnitTypeWML]]<br />
<br />
The metatable of these proxy tables appears as '''"unit type"'''.<br />
<br />
local lich_cost = wesnoth.unit_types["Ancient Lich"].cost<br />
<br />
Note that different clients have different set of available units in a Multiplayer game. It is OOS-unsafe to e.g. count the number of units.<br />
Presuming correctly written add-ons, it is still safe to e.g. access any given unit or its properties.<br />
<br />
==== wesnoth.races ====<br />
<br />
This is not a function but a table indexed by race ids. Its elements are proxy tables for all races the engine knows about.<br />
known fields of each element:<br />
* '''id''': string<br />
* '''description''', '''name''', '''plural_name''' (translatable strings)<br />
* '''num_traits''' (integer)<br />
* '''ignore_global_traits''' (boolean)<br />
* '''undead_variation''' (string)<br />
(all read only)<br />
* '''__cfg''': WML table (dump)<br />
<br />
wesnoth.message(tostring(wesnoth.races["lizard"].name))<br />
<br />
==== wesnoth.get_traits ====<br />
<br />
* '''wesnoth.get_traits()'''<br />
<br />
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.<br />
Known fields and subtags of each element are the ones which were given in the wml definition of the [[SingleUnitWML|trait]].<br />
wesnoth.message(tostring(wesnoth.get_traits().strong.male_name))<br />
<br />
==== wesnoth.simulate_combat ====<br />
<br />
* '''wesnoth.simulate_combat(''attacker'', [''attacker_weapon_index''], ''defender'', [''defender_weapon_index''])'''<br />
<br />
Computes the hitpoint distribution and status chance after a combat between two units. 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.<br />
<br />
Optional integers can be passed after each unit to select a particular weapon, otherwise the "best" one is selected. When giving the weapon, the parameter is the weapon number (integer, starting at 1) and not an element from the table returned by helper.child_range(att, "attack").<br />
<br />
local function display_stats(n, t)<br />
wesnoth.message(string.format(<br />
"Chance for the %s\n to be slowed: %f,\n to be poisoned: %f,\n to die: %f.\nAverage HP: %f.",<br />
n, t.slowed, t.poisoned, t.hp_chance[0], t.average_hp))<br />
end<br />
local att_stats, def_stats = wesnoth.simulate_combat(att, att_weapon, def, def_weapon)<br />
display_stats("attacker", att_stats)<br />
display_stats("defender", def_stats)<br />
<br />
Returns 2 additional tables which contain information about the weapons and the effect of single hits with these keys: num_blows, damage, chance_to_hit, poisons, slows, petrifies, plagues, plague_type, backstabs, rounds, firststrike, drains, drain_constant, drain_percent, attack_num, name. <br />
Name is the wml name not the description. If there is no weapon, then name will be nil<br />
<br />
local att_stats, def_stats, att_weapon, def_weapon = wesnoth.simulate_combat(attacker, att_weapon_number, defender)<br />
wesnoth.message(string.format(<br />
"The attack %s should be countered with %s, which does %d damage, has %d%% chance to hit and forces %d attack rounds due to its berserk ability.",<br />
att_weapon.name, def_weapon.name or "no weapon", def_weapon.damage, def_weapon.chance_to_hit, def_weapon.rounds))<br />
<br />
==== wesnoth.transform_unit ====<br />
<br />
* '''wesnoth.transform_unit(''unit'', ''to_type'')'''<br />
* {{DevFeature1.13|2}} '''''unit'':transform(''to_type'')'''<br />
<br />
Changes the type of a unit and adjust attributes accordingly. Note that hit points are only changed if necessary to accommodate the new maximum hit points. Poison is automatically removed if the transformed unit is immune.<br />
<br />
local ev = wesnoth.current.event_context<br />
local u = wesnoth.get_units{x=ev.x1, y=ev.y1}[1]<br />
wesnoth.transform_unit(u, "Spearman")<br />
-- If a full heal is desired:<br />
u.hitpoints = u.max_hitpoints<br />
u.status.poisoned = false<br />
<br />
==== wesnoth.add_known_unit ====<br />
<br />
* {{DevFeature1.13|10}} '''wesnoth.add_known_unit(''unit_type_id'')'''<br />
<br />
adds the unit type with the given id to the list of known units (so thath they appear in the help)<br />
<br />
==== wesnoth.create_animator ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.create_animator()'''<br />
<br />
Returns an object that can be used to set up and run an animation. The object has three methods:<br />
<br />
* '''animator:run()'''<br />
<br />
Runs the animation.<br />
<br />
* '''animator:clear()'''<br />
<br />
Clears any units previously added to the animation.<br />
<br />
* '''animator:add(''unit'', ''flag'', ''hits'', ''params'')'''<br />
<br />
Adds a unit to the animation. The ''flag'' specifies which animation to play, and the ''hits'' parameter is required for attack animations to specify which variant of the animation to play. Possibly keys in ''params'' are:<br />
<br />
* '''facing''': A location. The animation will be played with the unit facing that location.<br />
* '''value''': Either a number or a list of two numbers. Use this to pass ''value'' and/or ''value_second'' to default animations that use them.<br />
* '''with_bars''': Whether to show HP bars and such while the animation plays.<br />
* '''text''': Text to float as the animation plays.<br />
* '''color''': Color of the floating text - a list of red, green, blue.<br />
* '''primary''': The primary weapon to use for the animation. Must be a Lua unit attack proxy.<br />
* '''secondary''': The secondary weapon to use for the animation.<br />
<br />
Normal usage would be to create it, call '''add''' one or more times, then call '''run'''.<br />
<br />
==== wesnoth.effects ====<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
This table contains the implementation of custom [[EffectWML|[effect]]]s. Each value is a function that takes a unit and the effect config. Note that the default effects defined by the Wesnoth engine are not in this table. <br />
<br />
<syntaxhighlight lang='lua'><br />
function wesnoth.effects.min_resistance(u, cfg)<br />
local resistance_new = {}<br />
local resistance_old = helper.parsed(helper.get_child(cfg, "resistance"))<br />
for k,v in pairs(resistance_old) do<br />
if type(k) == "string" and type(v) == "number" and wesnoth.unit_resistance(u, k) >= v then<br />
resistance_new[k] = v<br />
end<br />
end<br />
--important: use wesnoth.add_modification(..., false) so that the function will only execute the effects of that object and not store the object in the unit.<br />
wesnoth.add_modification(u, "object", {<br />
T.effect {<br />
apply_to = "resistance",<br />
replace = true,<br />
T.resistance (resistance_new),<br />
},<br />
}, false)<br />
end<br />
</syntaxhighlight><br />
<br />
The code above adds a new <code>min_resistance</code> effect that will set the resistances to specific values if they are currently below that value. It can then be used like this (for example, in [[DirectActionsWML#.5Bobject.5D|[object]]]):<br />
<br />
<syntaxhighlight lang='wml'><br />
[effect]<br />
apply_to=min_resistance<br />
[resistance]<br />
cold=50<br />
[/resistance]<br />
[/effect]<br />
</syntaxhighlight><br />
<br />
Note that because currently all Lua code is executed after [unit]s in [side] are created, it is currently not possible to use these effects in [unit]s in [side]<br />
<br />
{{DevFeature1.13|5}}<br />
<br />
Built-in effects are now present in the <code>wesnoth.effects</code> table and can be called by custom effects or by other Lua code. They take the same two arguments that a custom effect function does - the unit, and the effect WML.<br />
<br />
In addition, you can now specify description modifiers to be used if a custom effect is placed in a <code>[trait]</code> tag. Instead of setting a function as the effect, you set a table with a <code>__call</code> metafunction which does what the function would have done. The table can then have an additional <code>__descr</code> metafunction which updates descriptions as necessary. The built-in effects all use this structure. This metafunction takes the same arguments as the regular effect function, but should not modify the unit. Instead, it returns a string to be appended to the trait's effect description.<br />
<br />
[[Category: Lua Reference]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=59351Template:DevDownload2018-04-02T06:32:07Z<p>Vultraz: Updated links for 1.13.13.</p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.13 | filename=wesnoth-1.13.13.tar.bz2 | size=430.1 MB | hash=0c5065c0f9934407b303dc68016414afb370439c172f52dbe6cda20ef87ec3ca}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.12 | filename=wesnoth-1.13.12.tar.bz2 | size=430.0 MB | hash=cb471da6d9f40eee1184827095a6d9136e32d60e09ec3a2fdb1e1c3b126d9095}}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.13 | filename=wesnoth-1.13.13-win32.exe | size=390.1 MB | hash=9524b5f1ccc45b043ff26f5d0535dfdf6745126bb71ee2980c4c75a9023772fe}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.12 | filename=wesnoth-1.13.12-win32.exe | size=389.9 MB | hash=716a7e816bc17df29be0a3d043441dd3a37c8da56e4acdb856040bbf445e6bc3}}<br />
<br />
==== macOS (10.8 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.13 | filename=Wesnoth_1.13.13.dmg | size=435.8 MB | hash=ac38390f71500b238c0f37319ab6eed8c24f2db15fa990ae01bd84903e1221de}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.12 | filename=Wesnoth_1.13.12.dmg | size=434.5 MB | hash=20a80950da50ed5311e9327e7702e072815f5dc8c07afc0cb2a2aade8557bd33}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=59297Template:DevDownload2018-03-23T19:55:02Z<p>Vultraz: Updated links for 1.13.12.</p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.12 | filename=wesnoth-1.13.12.tar.bz2 | size=430.0 MB | hash=cb471da6d9f40eee1184827095a6d9136e32d60e09ec3a2fdb1e1c3b126d9095}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.11 | filename=wesnoth-1.13.11.tar.bz2 | size=424.6 MB | hash=69b43512d58b1930340896d2796f615a2f102bf9aace0c936253db56a9180799}}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.12 | filename=wesnoth-1.13.12-win32.exe | size=389.9 MB | hash=716a7e816bc17df29be0a3d043441dd3a37c8da56e4acdb856040bbf445e6bc3}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.11 | filename=wesnoth-1.13.11-win32.exe | size=387.2 MB | hash=9c281d37486de24b606a1aed7b3034d8796f22ce645d7bee843d63f89ccff053}}<br />
<br />
==== macOS (10.8 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.12 | filename=Wesnoth_1.13.12.dmg | size=434.5 MB | hash=20a80950da50ed5311e9327e7702e072815f5dc8c07afc0cb2a2aade8557bd33}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.11 | filename=Wesnoth_1.13.11.dmg | size=424.1 MB | hash=aa5cea07f6465bf5fa41736f22f3141ea7db3c88fd3c3b08bdc3aff0c9a0cff1}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=ReportingBugs&diff=59294ReportingBugs2018-03-21T20:36:49Z<p>Vultraz: Removed whole Bug Protocol section. It didn't really say anything.</p>
<hr />
<div>== Where to report bugs ==<br />
The preferred way to report bugs is through our bug tracking system on Github, but you can also post your problem to the forums.<br />
* [https://github.com/wesnoth/wesnoth/issues/ Wesnoth bugs page on Github]<br />
* [http://www.wesnoth.org/forum/viewforum.php?f=4 Wesnoth forum - Technical Support]<br />
<br />
Note, however, that simple typos and story/flavor text errors should be reported on the [[SpellingMistakes]] wiki page.<br />
<br />
Note also, that bugs of user made content should be reported on the forum in the appropriate thread of the add-on in question. Usually those threads are in either the [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario & Campaign Development], [http://www.wesnoth.org/forum/viewforum.php?f=19 Faction & Era Development] or [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development] sub forum.<br />
<br />
== Needed information ==<br />
* What version of the game are you running?<br />
* Have you built (from sources) the game by yourself? gcc/g++ version? SDL library versions?<br />
* What operating system are you using? What version/release of that operating system?<br />
* Can you reproduce the problem? If you can please provide steps to do it.<br />
On special request another note: Use common sense! If you know the information can't be relevant to your report simply omit it. Nevertheless too much information usually doesn't hurt.<br />
* If you have push access, please remember to add the bug or enhancement label as well as at least one applicable purple label.<br />
<br />
== How to be ignored ==<br />
<br />
Your bug report is more likely to be tagged Invalid and ignored if you:<br />
<br />
* File it as anonymous so we can't ask you followup questions<br />
* Provide only the vaguest description of the problem<br />
* Don't include a savefile and a recipe for reproducing it from the savefile<br />
* Post feature requests without prior discussion at the forum or IRC<br />
<br />
If you crave being ignored, do these things. If you want your bug addressed quickly and effectively, don't do any of them.<br />
<br />
== Guidelines for suggesting features ==<br />
# First, please make sure the feature you are suggesting does not already exist (particularly in the latest development version of the game, consult the [http://changelog.wesnoth.org changelog]) by double-checking the help files and options to make sure you aren't missing something.<br />
# If it hasn't been implemented, please check that it hasn't been already submitted, by searching [http://bugs.wesnoth.org http://bugs.wesnoth.org].<br />
# If your feature request hasn't been submitted, start a topic about your feature at the [http://www.wesnoth.org/forum/ Forums] after reading [http://www.wesnoth.org/forum/viewtopic.php?t=10152 "Giving your idea the best chance of being accepted"].<br />
# If you get positive results on the forum (preferably from at least one developer) you can go ahead and submit your feature request using the [https://github.com/wesnoth/wesnoth/issues issues] tab on Github.<br />
# Please post only one feature per feature request. If you have multiple feature ideas that are related, you can cross reference them easily with "bug #123".<br />
# Be as specific as possible on how the feature should work so that anyone trying to implement it knows exactly what to do.<br />
<br />
== Guidelines for reporting bugs ==<br />
When reporting simple spelling mistakes use the [[SpellingMistakes]] page.<br />
<br />
# First, please make sure the bug you are reporting has not already been fixed (consult http://changelog.wesnoth.org/ to see the history of changes to the game).<br />
# If it hasn't been fixed yet, please check that the bug hasn't already been reported, by [http://bugs.wesnoth.org http://bugs.wesnoth.org].<br />
# If your bug hasn't been reported, please go ahead and report it.<br />
# Please post only one bug per bug report. If you have multiple bugs that are related, you can cross reference them easily with "bug #1234", where 1234 is the number of the previous bug report.<br />
<br />
Keep bug reports to the point, and make sure your bug is easily reproducible given the information you provide. Clearly written, reproducible single bug reports will get attention before those reports that mix several different bugs into one report, or that are incomprehensible.<br />
<br />
If there is already an existing bug report, do not hesitate to add a comment with your details - this way we know when some bug is getting "popular".<br />
<br />
An account at Github is free and takes very little time to set up.<br />
<br />
=== In-play problems ===<br />
If it is in-play problem that you can reproduce, save the game and send the savegame to us with details how to reproduce the problem from the savegame.<br />
<br />
=== Multiplayer out-of-sync errors ===<br />
* We need wesnoth stdout/stderr output from person who got the error (if you started wesnoth in terminal stdout/stderr is in that terminal).<br />
* We need savegame from person who got the error.<br />
* Savegame from some other player if possible.<br />
* The person who got the error should report the bug, other players can then add their savegames to that bug.<br />
<br />
=== Segfault ===<br />
* In Unix follow the instructions at [[DebuggingWesnoth]] to generate information to send to a developer.<br />
* In NT based OS's (including Win2k, XP) you enable/configure core dumps by running 'drwtsn32', the location of the dumps can be changed there.<br />
* In Mac OS X, you can enable Crash Reporter -- the output is a backtrace. Run Applications -> Utilities -> Console to see log output. See http://www.mozilla.org/mailnews/osxinfo.html for information on how to enable Crash Reporter.<br />
<br />
=== Sending savegames, screenshots, coredumps, etc ===<br />
* Please compress the files (bzip2, gzip, zip). Do not compress images or sounds, unless you're posting several in a batch. In particular, don't compress screenshots.<br />
* You can attach files if you submit your bug through Github by dragging and dropping the file onto the comment box.<br />
* You can attach files to forum posts.<br />
<br />
[[Category:Troubleshooting and Bugs]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=ReportingBugs&diff=59293ReportingBugs2018-03-21T20:33:29Z<p>Vultraz: Removed outdated protocol entries.</p>
<hr />
<div>== Where to report bugs ==<br />
The preferred way to report bugs is through our bug tracking system on Github, but you can also post your problem to the forums.<br />
* [https://github.com/wesnoth/wesnoth/issues/ Wesnoth bugs page on Github]<br />
* [http://www.wesnoth.org/forum/viewforum.php?f=4 Wesnoth forum - Technical Support]<br />
<br />
Note, however, that simple typos and story/flavor text errors should be reported on the [[SpellingMistakes]] wiki page.<br />
<br />
Note also, that bugs of user made content should be reported on the forum in the appropriate thread of the add-on in question. Usually those threads are in either the [http://www.wesnoth.org/forum/viewforum.php?f=8 Scenario & Campaign Development], [http://www.wesnoth.org/forum/viewforum.php?f=19 Faction & Era Development] or [http://www.wesnoth.org/forum/viewforum.php?f=15 Multiplayer Development] sub forum.<br />
<br />
== Needed information ==<br />
* What version of the game are you running?<br />
* Have you built (from sources) the game by yourself? gcc/g++ version? SDL library versions?<br />
* What operating system are you using? What version/release of that operating system?<br />
* Can you reproduce the problem? If you can please provide steps to do it.<br />
On special request another note: Use common sense! If you know the information can't be relevant to your report simply omit it. Nevertheless too much information usually doesn't hurt.<br />
* If you have push access, please remember to add the bug or enhancement label as well as at least one applicable purple label.<br />
<br />
== How to be ignored ==<br />
<br />
Your bug report is more likely to be tagged Invalid and ignored if you:<br />
<br />
* File it as anonymous so we can't ask you followup questions<br />
* Provide only the vaguest description of the problem<br />
* Don't include a savefile and a recipe for reproducing it from the savefile<br />
* Post feature requests without prior discussion at the forum or IRC<br />
<br />
If you crave being ignored, do these things. If you want your bug addressed quickly and effectively, don't do any of them.<br />
<br />
== Guidelines for suggesting features ==<br />
# First, please make sure the feature you are suggesting does not already exist (particularly in the latest development version of the game, consult the [http://changelog.wesnoth.org changelog]) by double-checking the help files and options to make sure you aren't missing something.<br />
# If it hasn't been implemented, please check that it hasn't been already submitted, by searching [http://bugs.wesnoth.org http://bugs.wesnoth.org].<br />
# If your feature request hasn't been submitted, start a topic about your feature at the [http://www.wesnoth.org/forum/ Forums] after reading [http://www.wesnoth.org/forum/viewtopic.php?t=10152 "Giving your idea the best chance of being accepted"].<br />
# If you get positive results on the forum (preferably from at least one developer) you can go ahead and submit your feature request using the [https://github.com/wesnoth/wesnoth/issues issues] tab on Github.<br />
# Please post only one feature per feature request. If you have multiple feature ideas that are related, you can cross reference them easily with "bug #123".<br />
# Be as specific as possible on how the feature should work so that anyone trying to implement it knows exactly what to do.<br />
<br />
== Guidelines for reporting bugs ==<br />
When reporting simple spelling mistakes use the [[SpellingMistakes]] page.<br />
<br />
# First, please make sure the bug you are reporting has not already been fixed (consult http://changelog.wesnoth.org/ to see the history of changes to the game).<br />
# If it hasn't been fixed yet, please check that the bug hasn't already been reported, by [http://bugs.wesnoth.org http://bugs.wesnoth.org].<br />
# If your bug hasn't been reported, please go ahead and report it.<br />
# Please post only one bug per bug report. If you have multiple bugs that are related, you can cross reference them easily with "bug #1234", where 1234 is the number of the previous bug report.<br />
<br />
Keep bug reports to the point, and make sure your bug is easily reproducible given the information you provide. Clearly written, reproducible single bug reports will get attention before those reports that mix several different bugs into one report, or that are incomprehensible.<br />
<br />
If there is already an existing bug report, do not hesitate to add a comment with your details - this way we know when some bug is getting "popular".<br />
<br />
An account at Github is free and takes very little time to set up.<br />
<br />
=== In-play problems ===<br />
If it is in-play problem that you can reproduce, save the game and send the savegame to us with details how to reproduce the problem from the savegame.<br />
<br />
=== Multiplayer out-of-sync errors ===<br />
* We need wesnoth stdout/stderr output from person who got the error (if you started wesnoth in terminal stdout/stderr is in that terminal).<br />
* We need savegame from person who got the error.<br />
* Savegame from some other player if possible.<br />
* The person who got the error should report the bug, other players can then add their savegames to that bug.<br />
<br />
=== Segfault ===<br />
* In Unix follow the instructions at [[DebuggingWesnoth]] to generate information to send to a developer.<br />
* In NT based OS's (including Win2k, XP) you enable/configure core dumps by running 'drwtsn32', the location of the dumps can be changed there.<br />
* In Mac OS X, you can enable Crash Reporter -- the output is a backtrace. Run Applications -> Utilities -> Console to see log output. See http://www.mozilla.org/mailnews/osxinfo.html for information on how to enable Crash Reporter.<br />
<br />
=== Sending savegames, screenshots, coredumps, etc ===<br />
* Please compress the files (bzip2, gzip, zip). Do not compress images or sounds, unless you're posting several in a batch. In particular, don't compress screenshots.<br />
* You can attach files if you submit your bug through Github by dragging and dropping the file onto the comment box.<br />
* You can attach files to forum posts.<br />
<br />
== Bug protocol ==<br />
<br />
* A bug which has been fixed is closed immediately.<br />
* If a bug has been in a named release, add a milestone for the next release when it is fixed.<br />
<br />
[[Category:Troubleshooting and Bugs]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=SpellingMistakes&diff=59247SpellingMistakes2018-03-12T17:14:10Z<p>Vultraz: </p>
<hr />
<div>This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.<br />
<br />
Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.<br />
<br />
==Mainline Campaigns==<br />
<br />
===An Orcish Incursion===<br />
<br />
===Dead Water===<br />
<br />
===Delfador’s Memoirs===<br />
<br />
===Descent into Darkness===<br />
<br />
===Eastern Invasion===<br />
<br />
===Heir to the Throne===<br />
<br />
===Liberty===<br />
<br />
===Northern Rebirth===<br />
<br />
===Sceptre of Fire===<br />
<br />
===Secrets of the Ancients===<br />
<br />
===Son of the Black Eye===<br />
<br />
===The Hammer of Thursagan===<br />
<br />
===The Legend of Wesmere===<br />
<br />
===The Rise of Wesnoth===<br />
<br />
===The South Guard===<br />
<br />
===Two Brothers===<br />
<br />
===Under the Burning Suns===<br />
<br />
==Wesnoth Game==<br />
<br />
===Editor===<br />
<br />
===Help===<br />
<br />
===Tutorial===<br />
<br />
===Manual===<br />
<br />
===Manpages===<br />
<br />
===Units===<br />
<br />
===Other (unit descriptions, ...)===<br />
<br />
===Multiplayer maps===<br />
<br />
===Translation code bugs===<br />
<br />
==Announcements==<br />
<br />
[[Category:Writing]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=59165Template:DevDownload2018-02-18T05:40:44Z<p>Vultraz: </p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.11 | filename=wesnoth-1.13.11.tar.bz2 | size=424.6 MB | hash=69b43512d58b1930340896d2796f615a2f102bf9aace0c936253db56a9180799}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.10 | filename=wesnoth-1.13.10.tar.bz2 | size=416.6 MB | hash=8fb33971384702bb932a8f401c4b9f75822dcf142c11fd8b1bcda2e03520264d}}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.11 | filename=wesnoth-1.13.11-win32.exe | size=387.2 MB | hash=9c281d37486de24b606a1aed7b3034d8796f22ce645d7bee843d63f89ccff053}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.10 | filename=wesnoth-1.13.10-win32.exe | size=379.9 MB | hash=d32e80fc824a023bd35946687ab6f613820b1451264a7ba6c091130144968036}}<br />
<br />
==== macOS (10.7 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.11 | filename=Wesnoth_1.13.11.dmg | size=424.1 MB | hash=aa5cea07f6465bf5fa41736f22f3141ea7db3c88fd3c3b08bdc3aff0c9a0cff1}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.10b | filename=Wesnoth_1.13.10b.dmg | size=418.7 MB | hash=d1ebf1547ea312426e8663a5920ad5335833676815777c827e9583074af3f872}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=59164Template:DevDownload2018-02-18T05:19:46Z<p>Vultraz: /* Development (1.13 branch) */</p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.11 | filename=wesnoth-1.13.11.tar.bz2 | size=424.6 MB | hash=69b43512d58b1930340896d2796f615a2f102bf9aace0c936253db56a9180799}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.10 | filename=wesnoth-1.13.10.tar.bz2 | size=416.6 MB | hash=8fb33971384702bb932a8f401c4b9f75822dcf142c11fd8b1bcda2e03520264d}}<br />
<br />
==== Windows (7 and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.11.10 | filename=wesnoth-1.13.11-win32.exe | size=387.2 MB | hash=9c281d37486de24b606a1aed7b3034d8796f22ce645d7bee843d63f89ccff053}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.10 | filename=wesnoth-1.13.10-win32.exe | size=379.9 MB | hash=d32e80fc824a023bd35946687ab6f613820b1451264a7ba6c091130144968036}}<br />
<br />
==== macOS (10.7 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.11 | filename=Wesnoth_1.13.11.dmg | size=424.1 MB | hash=aa5cea07f6465bf5fa41736f22f3141ea7db3c88fd3c3b08bdc3aff0c9a0cff1}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.10b | filename=Wesnoth_1.13.10b.dmg | size=418.7 MB | hash=d1ebf1547ea312426e8663a5920ad5335833676815777c827e9583074af3f872}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=PblWML&diff=59151PblWML2018-02-05T11:45:00Z<p>Vultraz: We don't allow pango markup for addon descriptions.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
To upload an add-on you have made, you need a '''_server.pbl''' file in your add-on's directory, at the same level as the '''_main.cfg''' file. When you upload the add-on, the entire directory and subdirectories containing the _server.pbl file will be published. Your add-on must be based entirely on these paths.<br />
<br />
See [[AddonStructure]] for more on setting up the add-on folder if you have not done so, and [[Distributing_content]] for more on uploading an add-on to the server with this file.<br />
<br />
<b>Note:</b> Be aware that translations in the .pbl-files are '''not''' used, so don't mark these strings as translatable.<br />
<br />
== What goes into a .pbl file? ==<br />
<br />
'''Note:''' ''You should '''not''' use special formatting or coloring in any of these keys when uploading to the official server.'''''<br />
<br />
The following keys are recognized for .pbl files:<br />
<br />
=== icon ===<br />
: An image, displayed leftmost in the add-ons download dialog. It must be a standard Wesnoth file and '''not a custom one'''. A custom file will only work for users who already have the relevant add-on installed. This is not related to the icon used for entries in the campaigns menu -- see [[CampaignWML]] for more information.<br />
<br />
: If the icon is a unit with magenta team-color bits, please use [[ImagePathFunctionWML]] to recolor it.<br />
<br />
=== title ===<br />
: Displayed to the right of the icon, it is just text. It should usually be the same as the name of your add-on when it is played.<br />
: '''This value is required'''.<br />
<br />
=== version ===<br />
: Displayed to the right of the title; it is merely text. However, starting with Wesnoth 1.6, the required format is '''x.y.z''' where '''x''', '''y''' and '''z''' are numbers — and a value for '''x''' greater than ''0'' implies the add-on is complete, feature-wise. Trailing non-numeric elements are allowed, but nothing should appear before or between these numbers. The string of numbers will be modified on the server by inserting or appending zeros as neccesary to meet the required format. All this is necessary for the “Update All” button to work correctly. ([[#Version Key Examples|See Examples]])<br />
: '''This value is required'''.<br />
<br />
=== author ===<br />
: Displayed to the right of the version; it is merely text. Put your name or nickname here. If several people have contributed significantly to the add-on you may want to list all of their names.<br />
: '''This value is required'''.<br />
<br />
=== passphrase ===<br />
: Not displayed. It prevents others from modifying the version of your add-on on the server. You do not need to input a passphrase when initially publishing a add-on; if you do not, one will be randomly generated for you and replaced in your local copy of the .pbl file.<br />
: '''SECURITY NOTE:''' If you do specify a passphrase of your own, note that it is stored in '''clear text''' form in the server; '''do NOT use a password you would normally use for any other services or web sites!'''<br />
<br />
=== description ===<br />
: This can be used to provide a brief description of your add-on, and for pre-1.0 versions, let people know how playable it is. The description can be viewed by users by clicking on the Description button in the built-in client, or by moving their mouse over the add-on's icon in the web interface.<br />
: '''This value is required'''.<br />
<br />
=== dependencies ===<br />
: An optional list of dependencies (a comma separated list of ''addon-name'' – the directory names of the needed add-ons), which should be provided if your add-on relies on other user-made content to work properly. ([[#Dependency Key Example|See Example]])<br />
<br />
=== core ===<br />
: An optional string defining the id of the core which the addon is designed for. Defaults to "''default''". Don't specify for an addon which is of type "''core''" itself. {{DevFeature1.13|0}}<br />
<br />
=== translate ===<br />
: If set to ''true'', the add-on will be sent to and updated with [[WesCamp|WesCamp-i18n]]. (NOTE: this is a new and experimental function, which will automatically update the translations in your add-on. Make sure you make backups of your add-on in case of problems.)<br />
<br />
: You should make sure your add-on complies with some very specific [[WesCamp#Preparing_your_add-on_for_WesCamp|conventions]] required to ease the process for translators as well as technical requirements.<br />
<br />
=== type ===<br />
: Indicates the type of the add-on; used to filter listings in the downloads manager dialog. Acceptable values are:<br />
<br />
:* ''core'': replaces the whole wml tree. {{DevFeature1.13|0}}<br />
:* ''campaign'': single player campaign.<br />
:* ''scenario'': single player scenario.<br />
:* ''campaign_sp_mp'': hybrid campaign.<br />
:* ''era'': multiplayer era.<br />
:* ''faction'': multiplayer stand-alone faction, or add-on for other available era.<br />
:* ''map_pack'': multiplayer map-pack.<br />
:* ''campaign_mp'': multiplayer campaign.<br />
:* ''scenario_mp'': multiplayer scenario. (See the note below.)<br />
:* ''mod_mp'': multiplayer modification.<br />
:* ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.<br />
:* ''other'': The type to use when no other type fits.<br />
: '''Note:''' If your add-on contains two or more separate multiplayer scenarios, use ''map_pack''.<br />
<br />
: '''This value is required'''.<br />
<br />
=== email ===<br />
: Hidden e-mail address used by the server administrators to contact content authors in case of major issues. Again, this will only be seen by the server administrators and it is required that you provide one in case you need to be contacted about your add-on.<br />
: '''This value is required'''.<br />
<br />
=== [feedback] ===<br />
: The [feedback] tag includes information used by the server to provide the client with a website URL for players to post feedback on an add-on and communicate with the maintainers. At this time, the official add-ons server is configured to take a single parameter described below.<br />
<br />
==== topic_id ====<br />
: Topic id from the [http://forums.wesnoth.org/ Wesnoth.org forums] for the add-on's feedback or development topic maintained by the add-on uploader or author. For existing topics, this topic_id corresponds to the series of digits in the ''t=YYYYY'' portion of a URL like <code><nowiki>http://forums.wesnoth.org/viewtopic.php?f=XX&t=YYYYY</nowiki></code>. You must take special care to ensure this information is valid before uploading if you want players to be able to reach you!<br />
<br />
<br />
The add-on server keeps track of some other information about uploaded content, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].<br />
<br />
== Examples ==<br />
<br />
=== Dependency Key Example ===<br />
<br />
The following dependency key could be used when the add-on needs the ''Imperial_Era'' and ''Era_of_Myths'' to be installed before it will work properly:<br />
<br />
dependencies=Imperial_Era,Era_of_Myths<br />
<br />
=== Version Key Examples ===<br />
<br />
The following are examples of '''good''' version values:<br />
<br />
version="1.5"<br />
version="0.11.4"<br />
version="0.1.4beta"<br />
version="1.5c"<br />
<br />
The following are examples of '''bad''' version values:<br />
<br />
version="Beta1.5"<br />
version="Incomplete (0.3.4)"<br />
<br />
In both of the above examples the version number as read by the server will be '''0.0.0Beta1.5''' and '''0.0.0Incomplete (0.3.4)'''. You can clearly see why this will not be a good thing with the ''Update add-ons'' feature.<br />
<br />
Finally, here are some example version numbers and how they will be interpreted by the ''Update add-ons'' button. The number on the left will be considered an earlier number than the number on the right in each example.<br />
<br />
0.5 < 1.0<br />
1.5 < 1.5c<br />
1.0 < 1.0.1<br />
1.0c < 1.0.1a<br />
1.0.1a < 1.0.1c<br />
1.0 Final < 1.0.1 Beta<br />
<br />
=== Example .pbl File ===<br />
<br />
title="My Campaign"<br />
type="campaign"<br />
icon="misc/ball.png"<br />
version="0.1.2"<br />
author="Me, artwork by myself"<br />
passphrase="This is like a password; see the security note in the documentation above before choosing a value of your own"<br />
description="You get to kill a lot of bad guys. But only the first map is done."<br />
email="name@example.com"<br />
# The following tag is only used by Wesnoth 1.11.8 and later!<br />
[feedback]<br />
topic_id=12345<br />
[/feedback]<br />
<br />
== See Also ==<br />
<br />
* [[IGNFileFormat]]<br />
* [[FancyAddonIcons]]<br />
* [[ReferenceWML]]<br />
* [[CampaignServerWML]]<br />
<br />
[[Category: WML Reference]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=LuaWML/Sides&diff=59021LuaWML/Sides2017-11-22T05:48:57Z<p>Vultraz: Corrected remove_shroud tag name (was clear_shroud)</p>
<hr />
<div>This page describes the [[LuaWML]] functions and helpers for handling sides and villages.<br />
<br />
==== wesnoth.sides ====<br />
<br />
This is not a function but a table indexed by side numbers. Its elements are proxy tables with these fields:<br />
* '''side''': the side number<br />
* '''gold''', '''village_gold''', '''base_income''': integers (read/write)<br />
* '''total_income''': integer (read only)<br />
* '''objectives''', '''user_team_name''': translatable strings (read/write)<br />
* '''objectives_changed''': boolean (read/write)<br />
* '''team_name''': string (read/write)<br />
* '''is_local''' {{DevFeature1.13|8}}: boolean (read). Whether the side is local. Careless use will cause OOS errors.<br />
* '''controller''': string (read/write) :<br />
:''note: In networked multiplayer, the controller attribute is ambiguous (won't be the same on all clients). Be very careful or you'll have OOS errors.''<br />
: The controller attribute has 6 possible values: human, network, ai, network_ai, null, idle. <br />
<br />
: A local human should always be "human", a local ai should always be "ai", a remote human should always be "network". and a remote ai should always be "network_ai". An empty side should be null on all clients. <br />
<br />
: An idle side should appear similarly as a "human" side for all sides that don't own the idle side, i.e. as "network".<br />
<br />
: These values may be checked using lua, or the :controller command in game.<br />
<br />
: This value can only be set to 'human', 'ai' or 'null'.<br />
* '''fog''': boolean (read {{DevFeature1.13|7}}/write)<br />
* '''shroud''': boolean (read {{DevFeature1.13|7}}/write)<br />
* '''hidden''': boolean (read/write)<br />
* '''name''': string (read)<br />
* '''faction''': {{DevFeature1.13|5}} id of the selected faction, string (multiplayer-only, read)<br />
* '''faction_name''': {{DevFeature1.13|5}} name of the selected faction, string (multiplayer-only, read)<br />
* '''color''': string (read/write)<br />
* '''recruit''': table of strings (read/write)<br />
* '''scroll_to_leader''': boolean (read/write)<br />
* '''village_support''': string (read/write)<br />
* '''flag''': string (read {{DevFeature1.13|7}}/write)<br />
* '''flag_icon''': string (read {{DevFeature1.13|7}}/write)<br />
* '''defeat_condition''': string (read/write) See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]<br />
* '''lost''': bool (read/write) If lost=true this side will be removed from the persitent list at the end of the scenario. This key can also be used to stop the engine from removing a side by setting it to false. Writing this key only works in a victory/defeat event.<br />
* '''persistent''' {{DevFeature1.13|5}}: boolean (read/write)<br />
* '''suppress_end_turn_confirmation''' {{DevFeature1.13|7}}: boolean (read/write)<br />
* '''share_vision''' {{DevFeature1.13|7}}: string (read/write)<br />
* '''share_maps''' {{DevFeature1.13|7}}: boolean (read)<br />
* '''share_view''' {{DevFeature1.13|7}}: boolean (read)<br />
* '''num_units''' {{DevFeature1.13|7}}: integer (read)<br />
* '''num_villages''' {{DevFeature1.13|7}}: integer (read)<br />
* '''total_upkeep''' {{DevFeature1.13|7}}: integer (read)<br />
* '''expenses''' {{DevFeature1.13|7}}: integer (read)<br />
* '''net_income''' {{DevFeature1.13|7}}: integer (read)<br />
* '''__cfg''': WML table (dump)<br />
<br />
The metatable of these proxy tables appears as '''"side"'''.<br />
<br />
local side = wesnoth.sides[1]<br />
side.gold = side.gold + 50<br />
wesnoth.message(string.format("%d sides", #wesnoth.sides))<br />
<br />
==== wesnoth.get_sides ====<br />
<br />
* '''wesnoth.get_sides(''filter'')'''<br />
<br />
Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]]. The output is the same format as the wesnoth.sides table, above.<br />
--set gold to 0 for all sides with a leader<br />
local sides = wesnoth.get_sides({ {"has_unit", { canrecruit = true }} })<br />
for i,v in ipairs(sides) do<br />
v.gold = 0<br />
end<br />
<br />
==== wesnoth.get_village_owner ====<br />
<br />
* '''wesnoth.get_village_owner(''x'', ''y'')'''<br />
<br />
Returns the side that owns the village at the given location.<br />
<br />
local owned_by_side_1 = wesnoth.get_village_owner(12, 15) == 1<br />
<br />
==== wesnoth.set_village_owner ====<br />
<br />
* '''wesnoth.set_village_owner(''x'', ''y'', ''side'', [''fire_events''])'''<br />
<br />
Gives ownership of the village at the given location to the given side (or remove ownership if none). Ownership is also removed if nil or 0 is passed for the third parameter, but no capture events are fired in this case.<br />
An optional 4th parameter (boolean true|false, default: false) can be passed determining whether to fire any capture events.<br />
<br />
wesnoth.set_village_owner(12, 15, 1)<br />
<br />
==== wesnoth.is_enemy ====<br />
<br />
* '''wesnoth.is_enemy(''side1'', ''side2'')'''<br />
<br />
Returns true if side A is enemy of side B, false otherwise.<br />
<br />
local enemy_flag = wesnoth.is_enemy(1, 3)<br />
<br />
==== wesnoth.match_side ====<br />
<br />
* '''wesnoth.match_side(''side'', ''filter'')'''<br />
<br />
Matches a side against a given [[StandardSideFilter]].<br />
<br />
wesnoth.message(tostring(wesnoth.match_side(1, {{"has_unit", { type = "Troll" }}})))<br />
<br />
==== wesnoth.get_starting_location ====<br />
<br />
* '''wesnoth.get_starting_location(''side'')'''<br />
<br />
Returns the starting location of the given side.<br />
<br />
local loc = wesnoth.get_starting_location(1)<br />
wesnoth.message(string.format("side 1 starts at (%u, %u)", loc[1], loc[2]))<br />
<br />
==== wesnoth.set_side_id ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.set_side_id(''side'', ''color'', ''flag'')'''<br />
<br />
Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes.<br />
<br />
==== wesnoth.place_shroud ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.place_shroud(''side'', ''shroud'')'''<br />
<br />
Shrouds the specified hexes. You can pass a shroud_data string (which will be merged with existing shroud), a list of specific locations (where each location is a two-element list of x and y coordinates), or the special string "all" to shroud all hexes.<br />
<br />
==== wesnoth.remove_shroud ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.remove_shroud(''side'', ''shroud'')'''<br />
<br />
Unshrouds the specified hexes. Hexes are specified as with place_shroud, except that a shroud_data string will not work.<br />
<br />
==== wesnoth.is_fogged ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.is_fogged(''side'', ''location'')'''<br />
<br />
Tests if the given location is under fog from the point of view of the given side.<br />
<br />
==== wesnoth.is_shrouded ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.is_shrouded(''side'', ''location'')'''<br />
<br />
Tests if the given location is under shroud from the point of view of the given side.<br />
<br />
==== wesnoth.switch_ai ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.switch_ai(''side'', ''file'')'''<br />
<br />
Replaces a side's AI with the configuration from a specified file.<br />
<br />
==== wesnoth.append_ai ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.append_ai(''side'', ''params'')'''<br />
<br />
Appends AI parameters (aspects, stages, goals) to the side's AI. The syntax for the parameters to be appended is the same as that supported by [modify_side].<br />
<br />
==== wesnoth.add_ai_component ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.add_ai_component(''side'', ''path'', ''component'')'''<br />
<br />
Adds a component to the side's AI. The path syntax is the same as that used by [modify_ai]. The component is the content of the component - it should not contain eg a toplevel [facet] tag.<br />
<br />
==== wesnoth.change_ai_component ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.change_ai_component(''side'', ''path'', ''component'')'''<br />
<br />
Like add_ai_component, but replaces an existing component instead of adding a new one.<br />
<br />
==== wesnoth.delete_ai_component ====<br />
<br />
{{DevFeature1.13|7}}<br />
<br />
* '''wesnoth.delete_ai_component(''side'', ''path'')'''<br />
<br />
Like add_ai_component, but removes a component instead of adding one.<br />
<br />
==== helper.all_teams ====<br />
<br />
* '''helper.all_teams()'''<br />
<br />
Returns an iterator over sides that can be used in a for-in loop.<br />
<br />
Note that the method name "teams" is a historical mistake, currently left out for backwards compatibility. It has no relation to [team] tag.<br />
<br />
for side in helper.all_teams() do side.gold = 200 end<br />
<br />
[[Category: Lua Reference]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=58988Template:DevDownload2017-11-05T14:28:47Z<p>Vultraz: </p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.10 | filename=wesnoth-1.13.10.tar.bz2 | size=416.6 MB | hash=8fb33971384702bb932a8f401c4b9f75822dcf142c11fd8b1bcda2e03520264d}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.8 | filename=wesnoth-1.13.8.tar.bz2 | size=409.0 MB | hash=df98a343ac2d83fb5f4144fb79379afa827c57cb8c68c3eaa29a2afb706352b5}}<br />
<br />
==== Windows (XP and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.10 | filename=wesnoth-1.13.10-win32.exe | size=379.9 MB | hash=d32e80fc824a023bd35946687ab6f613820b1451264a7ba6c091130144968036}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.8 | filename=wesnoth-1.13.8-win32.exe | size=371.3 MB | hash=72e7e77c8164be6ca57b3c7b1b31c79c1b271a4b6add89bf6508b0a3e495d7dc}}<br />
<br />
==== macOS (10.7 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.10 | filename=Wesnoth_1.13.10.dmg | size=418.9 MB | hash=b1452d4b7392f1f828944cac48658275eafd3c0076cf2ba73535d3d24f96b917}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.8 | filename=Wesnoth_1.13.8.dmg | size=408.2 MB | hash=df98a343ac2d83fb5f4144fb79379afa827c57cb8c68c3eaa29a2afb706352b5}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=58984Template:DevDownload2017-10-23T18:25:37Z<p>Vultraz: </p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.10 | filename=wesnoth-1.13.10.tar.bz2 | size=416.6 MB | hash=8fb33971384702bb932a8f401c4b9f75822dcf142c11fd8b1bcda2e03520264d}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.8 | filename=wesnoth-1.13.8.tar.bz2 | size=409.0 MB | hash=df98a343ac2d83fb5f4144fb79379afa827c57cb8c68c3eaa29a2afb706352b5}}<br />
<br />
==== Windows (XP and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.10 | filename=wesnoth-1.13.10-win32.exe | size=379.9 MB | hash=d32e80fc824a023bd35946687ab6f613820b1451264a7ba6c091130144968036}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.8 | filename=wesnoth-1.13.8-win32.exe | size=371.3 MB | hash=72e7e77c8164be6ca57b3c7b1b31c79c1b271a4b6add89bf6508b0a3e495d7dc}}<br />
<br />
==== macOS (10.7 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.8 | filename=Wesnoth_1.13.8.dmg | size=408.2 MB | hash=df98a343ac2d83fb5f4144fb79379afa827c57cb8c68c3eaa29a2afb706352b5}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Saurians&diff=58691Saurians2017-07-18T14:29:00Z<p>Vultraz: </p>
<hr />
<div>{{Race |<br />
race = Saurians |<br />
image= <br />
https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/core/images/units/saurians/oracle/oracle-se-magic2.png |<br />
faction=[[Drakes]] |<br />
alignment=Chaotic |<br />
tree=[http://units.wesnoth.org/1.12/mainline/en_US/mainline.html#Saurians 1.12]<br />
}}<br />
<br />
{| style="float:left"<br />
|<br />
__TOC__<br />
|}<br />
<br />
'''Saurians''' are small, slender, and lizard-like creatures. Much smaller than their Drake allies, they rarely stand taller than a ten year old child, though the distance from the tip of their snout to the end their tail can be as long as the average man is tall. Light and nimble, the warriors prefer to fight as they hunt- slipping through enemy lines to target the weak and the injured while their slender figures allow them to evade their attackers. <br />
<br />
=== Society ===<br />
Saurians are very mysterious creatures due to their tendency to live in areas inhospitable to others, such as swamps. Fatalistic in the extreme, Saurians believe all the events in a life can be predicted by the use of a complex form of astrology.<br />
<br />
Saurian culture is sharply segregated between the genders. Within each gender the members compete and through skill, determination, and reputation establish a clear pecking order, with a chief at the top. On those occasions when the two genders interact they do not contest for dominance, the situation determines the dominant gender. The chief of the males is alpha if they are within their village or encampment while the chief of females is dominant anywhere else. This continues down the rank structure with each male or female being dominant over any member of the opposite gender with lower rank and submitting to members of the opposite gender with higher rank.<br />
<br />
The segregation and alternating gender-dominance of Saurian society is an outgrowth of their clearly defined gender roles. It is the responsibility of the female to hunt and find food, skills which ultimately train them to be warriors; the skirmishers, flankers, and ambushers other races so fear. Males, meanwhile, are responsible for guarding the clutch- the eggs left by the females. While this leaves time for the males to develop and hone the arts of astrology, healing, and magic, it also exposes them to significant danger, as they are stationary targets for a Saurian clan's number one enemy- other Saurian clans. <br />
<br />
New Saurian clans are started when the proper astrological signs are read. Called a “hatching,” the female indicated by the conjunction select a group of individuals with lower rank and leave their source clan. Frequently all females with a specific trait will be selected, causing multiple clans to “hatch” at the same time. Selection is a simple process, no group leaving can be larger than any other, all the groups together can not be larger, than the group being left, and higher ranking allows a female to overrule another female's choice of who they take.<br />
<br />
Because of the rapid growth of saurian populations, these frequent splits in clans, and the fact that cannibalism is not taboo among Saurians violence is one of the defining features of the Saurian life. This limits the growth of the Saurian culture, limiting it to fits and starts- as much of their knowledge is passed by oral tradition and their possessions must be mobile.<br />
<br />
=== Geography ===<br />
Saurians can live in many different areas, though swamps are by far their most common habitat. <br />
<br />
=== Biology === <br />
Saurians live spectacularly short lives by comparison to most of the other races of Wesnoth, reaching full adulthood within three years and often dying by the time they are 10 to 15 years old. By far, the most common cause of death is violence. Saurian females produce clutches of about 20 eggs roughly once a year, which creates constant population pressure and would stress most carnivore's food supply. Hunters and scavengers, Saurians have extremely strong jaws and have a very powerful digestive system with highly acidic fluids, making them capable of eating and digesting their entire prey including skin, teeth, horns and bones. Further they have no aversion to and readily eat carrion and commit cannibalism. Due to this, the males of the Saurian race have specialized in cold-magics to take advantage of their own cold-blooded nature.<br />
<br />
=== See also ===<br />
*[[Drakes]]<br />
<br />
{{Racebox}}<br />
<br />
[[Category:Races]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Merfolk&diff=58690Merfolk2017-07-18T14:28:11Z<p>Vultraz: Change image path to GitHub.</p>
<hr />
<div>{{Race |<br />
race = Merfolk |<br />
image= <br />
https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/campaigns/Dead_Water/images/units/merfolk/warrior_king.png |<br />
faction=[[Rebels]], [[Loyalists]] |<br />
alignment=Lawful |<br />
tree=[http://units.wesnoth.org/1.12/mainline/en_US/mainline.html#Mermen 1.12]<br />
}}<br />
<br />
Something like a fusion between humans and fish, the merfolk are an enigmatic race with both piscine and humanoid attributes. They have strong tails that lend themselves to quick movement in any watery environment while their dextrous hands and intelligent minds allow fine craftsmanship and toolmaking. Semi-aquatic by nature, merfolk can breathe both water and air without difficulty. Despite being able to survive on land, they are much quicker and more agile in the water and will rarely be found far from the ocean. They are typically wary of dry land, as they are awkward and clumsy there and they struggle greatly to move over rough or forested terrain.<br />
<br />
===See also===<br />
*[[Loyalists]]<br />
<br />
*[[Rebels]]<br />
<br />
{{Racebox}}<br />
<br />
[[Category:Races]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Undead_(race)&diff=58689Undead (race)2017-07-18T14:27:42Z<p>Vultraz: Change image path to GitHub.</p>
<hr />
<div>{{Race |<br />
race = Undead |<br />
image= <br />
https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/core/images/units/undead-skeletal/deathknight.png |<br />
faction=[[Undead]] |<br />
alignment=Chaotic |<br />
tree=[http://units.wesnoth.org/1.12/mainline/en_US/mainline.html#Undead 1.12]<br />
}}<br />
<br />
<!--The text of the article is the official in-game race description. Please do not add or remove text unless it actually changes in-game.--><br />
'''Undead''' are not really a single race of creatures, although often treated as such. Almost any dead creature can, by a sufficiently skilled necromancer, be reanimated and rise again in undeath. Undead are for the most part unnatural but mindless constructs, obeying whoever created them without question nor thought. A greater mystery of necromancy is in how constructs are sustained without continuous effort from the necromancer. An undead creature does not require the constant attention of the necromancer to command and sustain, but can work autonomously according to the commands of it's master. Only rarely, perhaps once every few months, does the necromancer need to maintain his creation.<br />
<div class="thumb tleft"><div><br />
[http://www.wesnoth.org/images/sshots/wesnoth-1.3.13-3.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.3.13-3-175.jpg]<br />
<div class="thumbcaption">Two groups of Undead fighting<br><br />
over Hornshark Island.</div></div><br />
</div><br />
Necromancy is almost solely limited to [[humans]]. Even the legends of magically apt races like [[elves]] and mermen tell of very few of their kind who have ever delved in the dark arts. It is surmised that necromantic magic requires great adaptability and a flexible mind, extremes of which are most commonly found in humans.The ultimate goal of most necromancers is to turn the same art of preserving and imbuing life upon themselves, to alter themselves at whatever cost, to ultimately escape death by preserving their own mind and spirit.<br />
<br />
===Geography===<br />
While undead lords arrived on the Great Continent in considerable numbers only in the wake of Haldric I, they were not completely unheard of by elves and dwarves before that.<br />
<br />
===See also===<br />
*[[Undead]]<br />
<br />
{{Racebox}}<br />
<br />
[[Category:Races]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Drakes_(race)&diff=58688Drakes (race)2017-07-18T14:20:00Z<p>Vultraz: Change image path to GitHub.</p>
<hr />
<div>{{Race |<br />
race = Drakes |<br />
image= <br />
https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/core/images/units/drakes/armageddon-fly-2.png |<br />
faction=[[Drakes]] |<br />
alignment=Lawful |<br />
tree=[http://units.wesnoth.org/1.12/mainline/en_US/mainline.html#Drakes 1.12]<br />
}}<br />
<br />
<!--The text of the article is the official in-game race description. Please do not add or remove text unless it actually changes in-game.--><br />
{| style="float:left"<br />
|<br />
__TOC__<br />
|}<br />
<br />
'''Drakes''' are large, winged and fire-breathing creatures, reminiscent of true dragons. On average, an adult drake stands around three meters tall and easily weighs more than a [[humans|man]] and a horse combined. Their skin is made up of hard scales, resistant to most physical strikes except piercing and cold damage. Most drakes are capable of true flight and can travel long distances quickly. However, their sheer weight and bulk limits their flight ability somewhat, making them ungainly in the air. Where possible, they make use of terrain features such as hills, mountains and trees as launch points in order to gain greater height and speed. Fortunately for their enemies, they are still quite clumsy creatures and surprisingly slow in combat. This, combined with their large size, renders them easy targets for those who dare attack them.<br />
<br />
Drakes are inherently magical creatures, with a mysterious internal fire fueling their very lives. This can easily be witnessed when one of their kind perishes in combat; its internal fire is released, burning their remains in to ashes. Their internal fire is also their greatest weakness; it makes them extremely vulnerable to cold attacks. Despite their magical nature, drakes are incapable of channeling magic in a controlled manner. While the magic imbued within a drake's body enables it to spit fire and gives it life, they have no willful control over its functions of this magic.<br />
<br />
===Society===<br />
Drakes are a relatively warlike race and their societies can be best described as cultured martial societies. The core of a drake tribe is small group of veteran warriors headed by a mutually respected - or simply feared - leader who rules the society with an iron fist. Every drake is expected to earn their place in the strict hierarchy, to obey their superiors and command their lessers. Entry to the ruling elite is only possible through challenging and defeating a superior in single combat, which is the way the hierarchy within the elite itself is established. The use of deception of any kind towards any fellow drake is, without exception, seen as cowardly and unacceptable.<br />
<br />
<div class="thumb tleft"><div><br />
[http://www.wesnoth.org/images/sshots/wesnoth1.8-1.jpg http://www.wesnoth.org/images/sshots/wesnoth1.8-1-175.jpg]<br />
<div class="thumbcaption">The Drakes face the Undead<br><br />
in the Ruins of Terra Dwelve.</div></div><br />
</div><br />
While their warlike nature and sense of territory drives them to defend their territories savagely, drakes rarely invade or trespass on areas already occupied by the other major races. Instead, they settle in unpopulated areas to establish their own territory there. They primarily feed on large game they hunt in the lowlands around their homes, but hatchlings and lower caste drakes are known to feed also on certain of moss and fungi they cultivate deep in their caverns. The only technology drakes value is armour- and weapon-smithing, and neither know or need other science and culture besides this. However the few implements they do fashion are almost unrivaled in quality, only matched by those produced in the finest [[Dwarves|Dwarven]] foundries.<br />
<br />
Drakes are hatched from eggs and usually live naturally between 20 to 30 years. Death in battle is the most preferred way for a drake to leave this world. Unlike the elder members of other races, drakes naturally grow more aggressive and reckless towards the ends of their natural lives, perhaps to help ensure their place in the heroic legends of their kind.<br />
<br />
===Geography===<br />
<br />
Drakes originated from a chain of volcanic islands in the Great Ocean. A combination of population pressure and the subsidence of many of their home islands has caused colonies of drakes to spread to the Great Continent. Drakes tend to make their homes in mountain caverns near volcanoes to protect their eggs, hatchings and forges. While drakes naturally prefer warmth, their internal fire is more than capable of sustaining them even in a relatively cold climate, a feature which has allowed them to populate even some of the mountains of the far north of the Great Continent.<br />
<!-- mainline help text ends here --><br />
<br />
===Biology===<br />
<br />
The ferocity of Drake culture and their isolation from other races both originate in constraints of their biology. As peak predators with huge energy requirements, drakes require very large hunting ranges to sustain them. This is the real reason drake warbands tend to be so extremely territorial and widely separated, and to be found mainly on oceanic islands or in isolated wilderness areas where other speaking peoples are not competing for the available game. Other, related adaptations include low birth rate and a tendency for Drake individuals to spend long periods in a cataleptic state.<br />
<br />
===See also===<br />
*[[Drakes]]<br />
<br />
{{Racebox}}<br />
<br />
[[Category:Races]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Trolls&diff=58687Trolls2017-07-18T14:19:31Z<p>Vultraz: Change image path to GitHub.</p>
<hr />
<div>{{Race |<br />
race = Trolls |<br />
image= <br />
https://raw.githubusercontent.com/wesnoth/wesnoth/master/data/core/images/units/trolls/warrior-attack-2.png |<br />
faction=[[Northerners]] |<br />
alignment=Chaotic |<br />
tree=[http://units.wesnoth.org/1.12/mainline/en_US/mainline.html#Trolls 1.12]<br />
}}<br />
<br />
'''Trolls''' are ancient creatures, one of the oldest known races known to inhabit the Great Continent. They are large, slow, simple-minded, and live extremely long lives inside deep caves or atop high mountains. The most unique characteristic of trolls is an internal vitality that sustains and heals them from within. As a result they live very different lives from almost any known creature. Trolls have few real needs: they require little food or water, and thus they have little incentive to pursue much besides protection from those who are hostile towards them. This in turn means they rarely have to worry about anything and can spend much of their time sleeping or in contemplation. Trolls have a curious affinity with nature. They do not relate with living things like elves do, but instead with earth and stone. They are also somewhat curious of their surroundings and many younger whelps even enjoy traveling and seeing the world. As trolls grow older they tend to become increasingly passive, gradually losing interest in their environment and spending more of their time sleeping in a quiet, familiar corner of their home cave. This is until they finally pass away as their bodies themselves slowly turn into lifeless statues of stone.<br />
<br />
Trolls are seen by many as being little more than a yet another race of savage monsters. This common misconception is in part perpetuated by orcs to persuade trolls to join their armies. Because they are rather simple and do not understand the ways of other races or sometimes can even tell them apart, it is usually easy for an orcish band to convince a group of trolls that by joining them they get to exact revenge on those that have before hunted them. These new recruits are then directed to attack whoever the orcs themselves are currently in conflict with, whether previously a foe of the trolls or not, accumulating even more enemies for the misled trolls. The most common enemy of trolls are dwarves, and the animosity between these two races is ancient.<br />
<br />
===Geography===<br />
Trolls have inhabited the mountains of the Great Continent longer than the dwarves who migrated there. Trolls are a common sight on the mountain ranges north and east of Wesnoth, and wherever Orcish hordes travel.<br />
<br />
===See also===<br />
*[[Northerners]]<br />
<br />
{{Racebox}}<br />
<br />
[[Category:Races]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=PblWML&diff=58683PblWML2017-07-18T04:35:06Z<p>Vultraz: Squash keys into single code blocks</p>
<hr />
<div>{{WML Tags}}<br />
<br />
To upload an add-on you have made, you need a '''_server.pbl''' file in your add-on's directory, at the same level as the '''_main.cfg''' file. When you upload the add-on, the entire directory and subdirectories containing the _server.pbl file will be published. Your add-on must be based entirely on these paths.<br />
<br />
See [[AddonStructure]] for more on setting up the add-on folder if you have not done so, and [[Distributing_content]] for more on uploading an add-on to the server with this file.<br />
<br />
<b>Note:</b> Be aware that translations in the .pbl-files are '''not''' used, so don't mark these strings as translatable.<br />
<br />
== What goes into a .pbl file? ==<br />
<br />
'''Note:''' ''You should '''not''' use special formatting or coloring in any of these keys when uploading to the official server.'''''<br />
<br />
The following keys are recognized for .pbl files:<br />
<br />
=== icon ===<br />
: An image, displayed leftmost in the add-ons download dialog. It must be a standard Wesnoth file and '''not a custom one'''. A custom file will only work for users who already have the relevant add-on installed. This is not related to the icon used for entries in the campaigns menu -- see [[CampaignWML]] for more information.<br />
<br />
: If the icon is a unit with magenta team-color bits, please use [[ImagePathFunctionWML]] to recolor it.<br />
<br />
=== title ===<br />
: Displayed to the right of the icon, it is just text. It should usually be the same as the name of your add-on when it is played.<br />
<br />
=== version ===<br />
: Displayed to the right of the title, it is just text. However, starting with Wesnoth 1.6, the ''required'' format is x.y.z where x, y and z are numbers and a value for x greater than 0 implies the add-on is complete feature-wise. Trailing non-numeric elements are allowed, but nothing should appear ''before'' the numbers. This is necessary for the ''Update add-ons'' button to work correctly. ([[#Version Key Examples|See Examples]])<br />
<br />
=== author ===<br />
: Displayed to the right of the version, it is just text. Put your name or nickname here. If several people have contributed significantly to the add-on you may want to list all of their names.<br />
<br />
=== passphrase ===<br />
: Not displayed, it prevents others from modifying the version of your add-on on the server. You do not need to input a passphrase when initially publishing a add-on; if you do not, one will be randomly generated for you and replaced in your local copy of the .pbl file.<br />
: '''SECURITY NOTE:''' If you do specify a passphrase of your own, note that it is stored in '''clear text''' form in the server; '''do NOT use a password you would normally use for any other services or web sites!'''<br />
<br />
=== description ===<br />
: This can be used to provide a brief description of your add-on, and for pre-1.0 versions, let people know how playable it is. The description can be viewed by users by clicking on the Description button in the built-in client, or by moving their mouse over the add-on's icon in the web interface.<br />
<br />
=== dependencies ===<br />
: An optional list of dependencies (a comma separated list of ''addon-name'' – the directory names of the needed add-ons), which should be provided if your add-on relies on other user-made content to work properly. ([[#Dependency Key Example|See Example]])<br />
<br />
=== core ===<br />
: An optional string defining the id of the core which the addon is designed for. Defaults to "default". Don't specify for an addon which is of type "core" itself. {{DevFeature1.13|0}}<br />
<br />
=== translate ===<br />
: If set to '''true''', the add-on will be sent to and updated with [[WesCamp|WesCamp-i18n]]. (NOTE: this is a new and experimental function, which will automatically update the translations in your add-on. Make sure you make backups of your add-on in case of problems.)<br />
<br />
: You should make sure your add-on complies with some very specific [[WesCamp#Preparing_your_add-on_for_WesCamp|conventions]] required to ease the process for translators as well as technical requirements.<br />
<br />
=== type ===<br />
: Indicates the type of the add-on, used for the downloads manager dialog. Possible values are:<br />
<br />
:* ''core'': replaces the whole wml tree. {{DevFeature1.13|0}}<br />
:* ''campaign'': single player campaign.<br />
:* ''scenario'': single player scenario.<br />
:* ''campaign_sp_mp'': hybrid campaign.<br />
:* ''era'': multiplayer era.<br />
:* ''faction'': multiplayer stand-alone faction, or add-on for other available era.<br />
:* ''map_pack'': multiplayer map-pack.<br />
:* ''campaign_mp'': multiplayer campaign.<br />
:* ''scenario_mp'': multiplayer scenario. (See the note below.)<br />
:* ''mod_mp'': multiplayer modification.<br />
:* ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.<br />
:* ''other'': The type to use when no other type fits.<br />
<br />
'''Note:''' If your add-on contains two or more separate multiplayer scenarios, use ''map_pack''.<br />
<br />
=== email ===<br />
: Hidden e-mail address used by the server administrators to contact content authors in case of major issues. Again, this will only be seen by the server administrators and it is required that you provide one in case you need to be contacted about your add-on.<br />
<br />
=== [feedback] ===<br />
: The [feedback] tag includes information used by the server to provide the client with a website URL for players to post feedback on an add-on and communicate with the maintainers. At this time, the official add-ons server is configured to take a single parameter described below.<br />
<br />
==== topic_id ====<br />
: Topic id from the [http://forums.wesnoth.org/ Wesnoth.org forums] for the add-on's feedback or development topic maintained by the add-on uploader or author. For existing topics, the '''topic_id''' corresponds to the series of digits in the '''t=YYYYY''' portion of a URL like <code><nowiki>http://forums.wesnoth.org/viewtopic.php?f=XX&t=YYYYY</nowiki></code>. You must take special care to ensure this information is valid before uploading if you want players to be able to reach you!<br />
<br />
<br />
The add-on server keeps track of some other information about uploaded content, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].<br />
<br />
== Examples ==<br />
<br />
=== Dependency Key Example ===<br />
<br />
The following dependency key could be used when the add-on needs the ''Imperial_Era'' and ''Era_of_Myths'' to be installed before it will work properly:<br />
<br />
dependencies=Imperial_Era,Era_of_Myths<br />
<br />
=== Version Key Examples ===<br />
<br />
The following are examples of '''good''' version values:<br />
<br />
version="1.5"<br />
version="0.11.4"<br />
version="0.1.4beta"<br />
version="1.5c"<br />
<br />
<br />
The following are examples of '''bad''' version values:<br />
<br />
version="Beta1.5"<br />
version="Incomplete (0.3.4)"<br />
<br />
In both of the above examples the version number as read by the server will be '''0.0.0Beta1.5''' and '''0.0.0Incomplete (0.3.4)'''. You can clearly see why this will not be a good thing with the ''Update add-ons'' feature.<br />
<br />
<br />
Finally, here are some example version numbers and how they will be interpreted by the ''Update add-ons'' button. The number on the left will be considered an earlier number than the number on the right in each example.<br />
<br />
0.5 < 1.0<br />
1.5 < 1.5c<br />
1.0 < 1.0.1<br />
1.0c < 1.0.1a<br />
1.0.1a < 1.0.1c<br />
1.0 Final < 1.0.1 Beta<br />
<br />
=== Example .pbl File ===<br />
<br />
title="My Campaign"<br />
type="campaign"<br />
icon="misc/ball.png"<br />
version="0.1.2"<br />
author="Me, artwork by myself"<br />
passphrase="This is like a password; see the security note in the documentation above before choosing a value of your own"<br />
description="You get to kill a lot of bad guys. But only the first map is done."<br />
email="name@example.com"<br />
# The following tag is only used by Wesnoth 1.11.8 and later!<br />
[feedback]<br />
topic_id=12345<br />
[/feedback]<br />
<br />
== See Also ==<br />
<br />
* [[IGNFileFormat]]<br />
* [[FancyAddonIcons]]<br />
* [[ReferenceWML]]<br />
* [[CampaignServerWML]]<br />
<br />
[[Category: WML Reference]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=58498Template:DevDownload2017-05-24T04:29:55Z<p>Vultraz: /* Development (1.13 branch) */</p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.8 | filename=wesnoth-1.13.8.tar.bz2 | size=409.0 MB | hash=df98a343ac2d83fb5f4144fb79379afa827c57cb8c68c3eaa29a2afb706352b5}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.7 | filename=wesnoth-1.13.7.tar.bz2 | size=407.2 MB | hash=cbb20adc36b238c39651f90006913451339928fae1d96450471a0e9583972fd2}}<br />
<br />
==== Windows (XP and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.8 | filename=wesnoth-1.13.8-win32.exe | size=371.3 MB | hash=72e7e77c8164be6ca57b3c7b1b31c79c1b271a4b6add89bf6508b0a3e495d7dc}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.7 | filename=wesnoth-1.13.7-win32.exe | size=369.6 MB | hash=1468cf8dbea8c65e324c864f5e4d89f3f112402daf35336045cc20a4bd79431b}}<br />
<br />
==== macOS (10.7 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.8 | filename=Wesnoth_1.13.8.dmg | size=408.2 MB | hash=df98a343ac2d83fb5f4144fb79379afa827c57cb8c68c3eaa29a2afb706352b5}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.7 | filename=Wesnoth_1.13.7.dmg | size=406.1 MB | hash=9b824e7a9d2eac45e9098ca4637a35d734d6c6a98a0f4bf2f00e96d64589b2de}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=58490Template:DevDownload2017-05-20T00:20:41Z<p>Vultraz: /* Development (1.13 branch) */</p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.8 | filename=wesnoth-1.13.8.tar.bz2 | size=409.0 MB | hash=d9bd3e86e3f813328ce1a2100be30d29ff8695e523cd3c08219905418f25d56a}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.7 | filename=wesnoth-1.13.7.tar.bz2 | size=407.2 MB | hash=cbb20adc36b238c39651f90006913451339928fae1d96450471a0e9583972fd2}}<br />
<br />
==== Windows (XP and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.8 | filename=wesnoth-1.13.8-win32.exe | size=371.3 MB | hash=72e7e77c8164be6ca57b3c7b1b31c79c1b271a4b6add89bf6508b0a3e495d7dc}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.7 | filename=wesnoth-1.13.7-win32.exe | size=369.6 MB | hash=1468cf8dbea8c65e324c864f5e4d89f3f112402daf35336045cc20a4bd79431b}}<br />
<br />
==== macOS (10.7 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.8 | filename=Wesnoth_1.13.8.dmg | size=408.2 MB | hash=df98a343ac2d83fb5f4144fb79379afa827c57cb8c68c3eaa29a2afb706352b5}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.7 | filename=Wesnoth_1.13.7.dmg | size=406.1 MB | hash=9b824e7a9d2eac45e9098ca4637a35d734d6c6a98a0f4bf2f00e96d64589b2de}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:Compiling_Wesnoth&diff=58466Template:Compiling Wesnoth2017-05-13T22:31:55Z<p>Vultraz: Mac OS X ->macOS</p>
<hr />
<div>{| class="gallery" style="width:175px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 8pt;margin-left;10px;"<br />
|-<br />
|<br />
<span style="float: right;"><small class="editlink noprint plainlinksneverexpand">[{{SERVER}}{{localurl:Template:Compiling Wesnoth|action=edit}} edit ]</small></span><br />
'''Compiling Wesnoth'''<br />
|-<br />
|Platforms<br />
* [[CompilingWesnoth|Linux or Unix]]<br />
* [[CompilingWesnothOnMacOSX|macOS]]<br />
* [[CompilingWesnothOnWindows|MS Windows]]<br />
* [[CompilingWesnothOnSuSE|SuSE]]<br />
* [[CompilingWesnoth/CrossCompiling|cross-compiling]]<br />
|-<br />
|Tools<br />
* [[ccache]]<br />
* [[CMake]]<br />
* [[Dev-Cpp|Dev-C++]]<br />
* [[EclipseScons|Eclipse (Scons)]]<br />
* [[SCons]]<br />
|}</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=58274Template:DevDownload2017-03-22T06:55:19Z<p>Vultraz: 1.13.7</p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.7 | filename=wesnoth-1.13.7.tar.bz2 | size=407.2 MB | hash=cbb20adc36b238c39651f90006913451339928fae1d96450471a0e9583972fd2}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.6 | filename=wesnoth-1.13.6.tar.bz2 | size=400.7 MB | hash=a10a193ef8bc9963b2e241826628a120bb7dda758eb2d25d9ad110ad4916937c}}<br />
<br />
==== Windows (XP and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.7 | filename=wesnoth-1.13.7-win32.exe | size=369.6 MB | hash=1468cf8dbea8c65e324c864f5e4d89f3f112402daf35336045cc20a4bd79431b}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.6 | filename=wesnoth-1.13.6-win32.exe | size=362.6 MB | hash=6275d70c63ca22ce49f16721628c5e8c10498baa6ef01c2eb0bdf3f561e408f8}}<br />
<br />
==== macOS (10.7 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.7 | filename=Wesnoth_1.13.7.dmg | size=406.1MB | hash=9b824e7a9d2eac45e9098ca4637a35d734d6c6a98a0f4bf2f00e96d64589b2de}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.6 | filename=Wesnoth_1.13.6.dmg | size=399.4 MB | hash=eb5c76cf7cd83a582bdef19d6a7c8b165eb69b4024ceab5ea1987b10753a15e8}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=ImagePathFunctions&diff=58158ImagePathFunctions2017-02-17T16:07:08Z<p>Vultraz: /* Miscellaneous */</p>
<hr />
<div>Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).<br />
<br />
If you need to practice it without having to reload all WML, you can use an add-on named ''Image loading tester'' from the 1.10 add-on server.<br />
<br />
All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.<br />
That is, stuff like "units/elves-wood/fighter.png~CROP(20,20,40,40)~CROP(10,10,10,10)" would result in taking a crop to a 40x40 rectangle whose top-left corner is x=20, y=20; and then taking a crop from ''that'' rectangle with x=10, y=10, w=10, h=10. The result is the area x=30, y=30, w=10, h=10 from the original graphic.<br />
<br />
= Changing the colors =<br />
<br />
== BLEND: Color-blend function ==<br />
Blends the image with the given color to produce a more controlled tinting effect than color-shifting, independently of the image's contents.<br />
<br />
'''~BLEND(r,g,b,o)'''<br />
<br />
The color is defined by the ''r'', ''g'', and ''b'' parameters (integers ranging from 0 to 255). The ''o'' (opacity) parameter controls the amount by which the given color will be blended into the image, and may be specified either as a factor from 0.0 to 1.0, or percentage up to 100%. Thus, ~BLEND(r,g,b,0.5) and ~BLEND(r,g,b,50%) are equivalent.<br />
<br />
== BW: Black and White Function ==<br />
{{devfeature1.13|1}}<br />
May be used to convert the image to pure black and white, without grey pixels. <br />
<br />
'''~BW(threshold)'''<br />
* ''threshold'': a value between 0 and 255 (both limits included). All pixels are converted as greyscale first, and if their average value is greater than the threshold they become white, otherwise they become black.<br />
<br />
== CS: Color-shift function ==<br />
Performs simple per-channel color shifts by adding the arguments to the respective color channels.<br />
<br />
''Multi-channel:'' '''~CS(r,g,b)'''<br />
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''<br />
<br />
The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.<br />
<br />
The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.<br />
<br />
== GS: Greyscale Function ==<br />
May be used to greyscale the image (turn to black and white)<br />
<br />
'''~GS( )'''<br />
<br />
== L: Lightmap color-shift function ==<br />
Performs per-pixel and per-channel color shifts using another image (a "lightmap") as source, allowing to create textured light effects.<br />
<br />
'''~L(lightmap)'''<br />
<br />
For each pixel of the original image, it checks the RGB values from the corresponding pixel of the lightmap, slightly transform them, then add these values to the original pixel.<br />
<br />
The transformation involved is done to convert the (0,255) spectrum to (-255,255), allowing to add or subtract color. The formula is (x-128)*2, which means that 0 gives -256, 128 gives 0 and 255 gives 254. So, the no-effect lightmap is a fully gray image (RGB = 128,128,128) and any non-gray pixel will shift the colors of the original.<br />
<br />
Note that the lightmap will be scaled to the same dimensions as the original image.<br />
<br />
== NEG: Negative Function ==<br />
{{devfeature1.13|0}}<br />
Also known as ''invert'', it negates all the RGB values of the image, giving it an effect similar to a photographic negative.<br />
<br />
'''~NEG( )'''<br />
<br />
Inverts the image, giving it an effect like a photographic negative.<br />
<br />
{{devfeature1.13|1}} '''~NEG(''' ''threshold'' ''')'''<br />
<br />
If a channel has a value greater than the threshold, the channel will be inverted, performing an effect known as ''solarization''.<br />
Threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.<br />
<br />
{{devfeature1.13|1}} '''~NEG(''' ''threshold_red, threshold_green, threshold_blue'' ''')'''<br />
<br />
If a channel has a value greater than the corresponding threshold, the channel will be inverted.<br />
Each threshold must be between -1 and 255, with -1 equivalent to full inversion and 255 as no-op value.<br />
<br />
== PAL: Palette-switch Function ==<br />
May be used to change colors in an image following the specifications of a source and target (new) palette.<br />
<br />
'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''<br />
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.<br />
*''target color palette'' - the new palette to take the place of the source colors in the image.<br />
<br />
== RC: Re-Color Function ==<br />
May be used to change some colors in an image.<br />
<br />
'''~RC(''' ''source color palette'' '''>''' ''color range ID'' ''')'''<br />
*''source color palette'' - the first parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.<br />
*''color range ID'' - this is the second parameter, signifying the ID of a color range defined in the file ''data/core/team-colors.cfg'' (or it may be a custom ID for a color range defined locally). <br />
<br />
=== Example ===<br />
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:<br />
<br />
[message]<br />
speaker=narrator<br />
image=units/elves-wood/captain.png~RC(magenta>green)<br />
message=_ "Now I am on the green team."<br />
[/message]<br />
<br />
The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.<br />
<br />
== SEPIA: Sepia Function ==<br />
{{devfeature1.13|0}}<br />
May be used to give to the image a sepia tint (like in old pictures).<br />
<br />
'''~SEPIA()'''<br />
<br />
== SWAP: Channel Swap Function ==<br />
{{devfeature1.13|1}}<br />
May be used to swap the RGBA channels of an image.<br />
<br />
'''~SWAP(''' ''r, g, b'' ''')'''<br />
'''~SWAP(''' ''r, g, b, a'' ''')'''<br />
* ''r'', ''g'', ''b'', ''a'': each of these arguments may have a value equal to ''red'', ''green'', ''blue'' or ''alpha''. The RGBA channels of the original image will be exchanged accordingly (for example, <tt>~SWAP(blue,green,red)</tt> swaps the blue and red channels).<br />
<br />
== TC: Team-Color Function ==<br />
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''<br />
<br />
'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''<br />
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).<br />
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.<br />
<br />
= Transformations =<br />
<br />
== FL: Flip Function ==<br />
May be used to flip an image horizontally and/or vertically.<br />
<br />
'''~FL(''' ''optional argument list'' ''')'''<br />
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.<br />
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizantally.<br />
*if the argument list is empty, the image will only be flipped horizontally.<br />
<br />
== ROTATE: Rotate Function ==<br />
May be used to rotate an image by a multiple of 90 degrees.<br />
<br />
'''~ROTATE(''' ''degrees'' ''')'''<br />
* ''degrees'' - The number of degrees by which the image will be rotated. This must be a multiple of 90. Positive numbers indicate clockwise rotation, while negative numbers indicate counter-clockwise. (Zero indicates no rotation.)<br />
If the number of degrees is omitted, a quarter turn (90 degrees) clockwise is assumed.<br />
<br />
== SCALE: Image-scaling function ==<br />
Scales a graphic up or down.<br />
<br />
'''~SCALE( ''new_width'', ''new_height'' )<br />
<br />
The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr. This uses the bilinear interpolation algorithm.<br />
<br />
== SCALE_INTO function ==<br />
{{DevFeature1.13|5}}<br />
<br />
Similar to SCALE, but preserves aspect aspect ratio, scaling to the minimum extent required to fit into the specified area. The resulting image will have the specified width or the specified height, but not necessarily both.<br />
<br />
== SCALE_SHARP function ==<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Scales functions using a nearest neighbor algorithm. Specify width and height. (It has the same syntax as ~SCALE.)<br />
<br />
'''~SCALE_SHARP(200,300)'''<br />
<br />
== SCALE_INTO_SHARP function ==<br />
{{DevFeature1.13|5}}<br />
<br />
Like SCALE_INTO, but uses nearest neighbor algorithm instead of bilinear intorpolation.<br />
<br />
== XBRZ function ==<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Scales functions using the XBRZ algorithm. You may scale things up either 2x, 3x, 4x, or 5x. The scaling tries to preserve the pixel art nature.<br />
<br />
'''~XBRZ(n)'''<br />
<br />
= Cut-and-paste =<br />
<br />
== BLIT: Blit Function ==<br />
Blit the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)<br />
<br />
'''~BLIT(src,x,y)'''<br />
* ''src'': an image file used as source for the blit, other image path functions can be used there.<br />
* ''x'',''y'': top-left corner coordinates where to blit. Must be greater or equal than zero. If missing assume (0,0).<br />
<br />
== CROP: Crop Function ==<br />
Extracts a rectangular section of an image file.<br />
<br />
'''~CROP(x,y,width,height)'''<br />
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.<br />
* ''width'': width of the selected region. Must be less than or equal to the original image's width, and must not be negative.<br />
* ''height'': height of the selected region. Must be less than or equal to the original image's height, and must not be negative.<br />
<br />
== MASK: Mask Function ==<br />
Remove parts of the main image using the parameter image as a mask. Example: grass.png~MASK(circle.png) will give a circle of grass.<br />
<br />
'''~MASK(mask,x,y)'''<br />
* ''mask'': an image file used as mask, other image path functions can be used there.<br />
* ''x'',''y'': top-left corner coordinates where to put the mask. Parts ouside of the mask are considered transparent. If missing assume (0,0).<br />
<br />
Only the alpha channel of the mask is used and each alpha value will be the maximum alpha of the resulting image. This means that the fully-transparent parts of the mask will erase the corresponding parts of the image, but also that a semi-transparent mask will create a semi-transparent image. <br />
<br />
= Opacity =<br />
<br />
== ADJUST_ALPHA ==<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Scales the alpha value at each pixel down by a fixed factor. The argument is either a %, or an integer from 0 to 255, in which case it is divided by 255 and reinterpretted as a %.<br />
<br />
'''~ADJUST_ALPHA(n)'''.<br />
<br />
== O: Opacity modifying function ==<br />
Changes an image's opacity at render time.<br />
<br />
'''~O( ''factor or percentage%'' )'''<br />
<br />
If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).<br />
<br />
Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.<br />
<br />
== PLOT_ALPHA ==<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
At each pixel, the color is replaced with a grey-tone reflecting the alpha value at that pixel, and the new image is fully opaque. Useful for plotting the alpha to help debug an IPF or inspect a sprite.<br />
<br />
'''~PLOT_ALPHA()'''<br />
<br />
== WIPE_ALPHA ==<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
At each pixel, the alpha value is discarded and the pixel is made fully opaque. Useful again for diagnostics.<br />
<br />
'''~WIPE_ALPHA()'''<br />
<br />
== Background coloring function ==<br />
Sets the color of all the (semi-)transparent pixels of the image.<br />
<br />
'''~BG(r,g,b)'''<br />
<br />
= Miscellaneous =<br />
<br />
== BL: Blurring function ==<br />
Blurs a graphic at render time using the same algorithm used for in-game dialogs.<br />
<br />
'''~BL( ''radius'' )'''<br />
<br />
== DARKEN: Overlay function ==<br />
Puts a time-of-day schedule overlay (misc/tod-dark.png) on the image, which must be large enough to accommodate it.<br />
<br />
'''~LIGHTEN()'''<br />
<br />
'''~DARKEN()'''<br />
<br />
NOTE: removed as of 1.13.7. Use a ~BLIT(misc/tod-dark.png) call instead.<br />
<br />
== LIGHTEN: Overlay function ==<br />
Puts a time-of-day schedule overlay (misc/tod-bright.png) on the image, which must be large enough to accommodate it.<br />
<br />
'''~LIGHTEN()'''<br />
<br />
'''~DARKEN()'''<br />
<br />
NOTE: removed as of 1.13.7. Use a ~BLIT(misc/tod-bright.png) call instead.<br />
<br />
== NOP: Null function ==<br />
Does nothing.<br />
<br />
'''~NOP()'''<br />
<br />
[[Category:WML Reference]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=58029Template:DevDownload2016-11-11T20:08:44Z<p>Vultraz: /* Development (1.13 branch) */</p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.6 | filename=wesnoth-1.13.6.tar.bz2 | size=400.7 MB | hash=a10a193ef8bc9963b2e241826628a120bb7dda758eb2d25d9ad110ad4916937c}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=wesnoth-1.13.5.tar.bz2 | size=397.0 MB | hash=bd11247edb92bf1f9c07af928928fe82aacee84d083e5539bd0681930d701b96}}<br />
<br />
==== Windows (XP and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.6 | filename=wesnoth-1.13.6-win32.exe | size=362.6 MB | hash=6275d70c63ca22ce49f16721628c5e8c10498baa6ef01c2eb0bdf3f561e408f8}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=wesnoth-1.13.5-win32.exe | size=360.1 MB | hash=fff3a6ed036a53f3c51bed38ed04886aa7f2f7592c8085f83a3fe64836732ff1}}<br />
<br />
==== macOS (10.7 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.6 | filename=Wesnoth_1.13.6.dmg | size=399.4 MB | hash=eb5c76cf7cd83a582bdef19d6a7c8b165eb69b4024ceab5ea1987b10753a15e8}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=Wesnoth_1.13.5.dmg | size=402.3 MB | hash=cc0bb33c480a0ae01ce49aa52efc310347a483d7191ed17f2b789a885612c96e}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=58028Template:DevDownload2016-11-11T20:08:11Z<p>Vultraz: /* Development (1.13 branch) */</p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.6 | filename=wesnoth-1.13.6.tar.bz2 | size=400.7 MB | hash=a10a193ef8bc9963b2e241826628a120bb7dda758eb2d25d9ad110ad4916937c}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=wesnoth-1.13.5.tar.bz2 | size=397.0 MB | hash=bd11247edb92bf1f9c07af928928fe82aacee84d083e5539bd0681930d701b96}}<br />
<br />
==== Windows (XP and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.6 | filename=wesnoth-1.13.6-win32.exe | size=362.6 MB | hash=6275d70c63ca22ce49f16721628c5e8c10498baa6ef01c2eb0bdf3f561e408f8}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=wesnoth-1.13.5-win32.exe | size=360.1 MB | hash=fff3a6ed036a53f3c51bed38ed04886aa7f2f7592c8085f83a3fe64836732ff1}}<br />
<br />
==== macOS (10.7 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.6 | filename=Wesnoth_1.13.6.dmg | size=399.4 MB | hash=eb5c76cf7cd83a582bdef19d6a7c8b165eb69b4024ceab5ea1987b10753a15e8}}<!--<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=Wesnoth_1.13.5.dmg | size=402.3 MB | hash=cc0bb33c480a0ae01ce49aa52efc310347a483d7191ed17f2b789a885612c96e}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=58023Template:DevDownload2016-11-10T00:57:23Z<p>Vultraz: /* Development (1.13 branch) */</p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.6 | filename=wesnoth-1.13.6.tar.bz2 | size=400.7 MB | hash=a10a193ef8bc9963b2e241826628a120bb7dda758eb2d25d9ad110ad4916937c}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=wesnoth-1.13.5.tar.bz2 | size=397.0 MB | hash=bd11247edb92bf1f9c07af928928fe82aacee84d083e5539bd0681930d701b96}}<br />
<br />
==== Windows (XP and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.6 | filename=wesnoth-1.13.6-win32.exe | size=362.6 MB | hash=6275d70c63ca22ce49f16721628c5e8c10498baa6ef01c2eb0bdf3f561e408f8}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=wesnoth-1.13.5-win32.exe | size=360.1 MB | hash=fff3a6ed036a53f3c51bed38ed04886aa7f2f7592c8085f83a3fe64836732ff1}}<br />
<br />
==== macOS (10.7 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=Wesnoth_1.13.5.dmg | size=402.3 MB | hash=cc0bb33c480a0ae01ce49aa52efc310347a483d7191ed17f2b789a885612c96e}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:DevDownload&diff=58022Template:DevDownload2016-11-10T00:56:33Z<p>Vultraz: /* Development (1.13 branch) */</p>
<hr />
<div><noinclude><br />
== Development (1.13 branch) ==<br />
==== Source code ====<br />
</noinclude><br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.6 | filename=wesnoth-1.13.6.tar.bz2 | size=400.7 MB | hash=a10a193ef8bc9963b2e241826628a120bb7dda758eb2d25d9ad110ad4916937c}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=wesnoth-1.13.5.tar.bz2 | size=397.0 MB | hash=bd11247edb92bf1f9c07af928928fe82aacee84d083e5539bd0681930d701b96}}<br />
<br />
==== Windows (XP and later) {{{4|}}} ====<br />
* {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.6 | filename=wesnoth-1.13.6-win32.exe | size=362.6 MB | hash=fff3a6ed036a53f3c51bed38ed04886aa7f2f7592c8085f83a3fe64836732ff1}}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=wesnoth-1.13.5-win32.exe | size=360.1 MB | hash=6275d70c63ca22ce49f16721628c5e8c10498baa6ef01c2eb0bdf3f561e408f8}}<br />
<br />
==== macOS (10.7 and later) {{{5|}}} ====<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.5 | filename=Wesnoth_1.13.5.dmg | size=402.3 MB | hash=cc0bb33c480a0ae01ce49aa52efc310347a483d7191ed17f2b789a885612c96e}}<!--<br />
<br />
Ivanovic says the OpenPandora port is currently discontinued for 1.13.x, so this is commented out in case it's resurrected at some point in the far future. -- shadowm<br />
<br />
==== OpenPandora {{{6|}}} ====<br />
* New version not available yet. {{DownloadItem | label={{{1|Current Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }}<br />
* {{DownloadItem | label={{{2|Previous Version}}} | group=wesnoth | version=1.13.99 | pkgversion=1.13.99-1 | filename=wesnoth-1.13.99-1.pnd | size=??? MB }} --></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=CodingStandards&diff=57990CodingStandards2016-10-27T19:40:56Z<p>Vultraz: Removed wstring blacklisting</p>
<hr />
<div>Wesnoth uses C++ that is portable to C++ compilers targeting various commonly used platforms.<br />
<br />
== C++ version ==<br />
<br />
Wesnoth uses C++ conforming to C++11. At the moment C++14 compiler support is still not widely available, therefore C++14 is not allowed.<br />
<br />
== Formatting ==<br />
<br />
When working on C++ for Wesnoth, indent your code with a tab character. After fully indenting, if you still need to line up the text with a specific character on the line above, you may further align it using space characters.<br />
<br />
You may use long lines.<br />
<br />
== Evil things to avoid ==<br />
<br />
=== Avoid implicit conversions ===<br />
<br />
Make all constructors which only take one argument that is of a different type to the class <tt>explicit</tt>.<br />
<br />
Do not use <tt>operator T()</tt> (where <tt>T</tt> is a type) to allow an implicit conversion to a different type. For example:<br />
<br />
t_string(const std::string&);<br />
<br />
This can cause many situations where a temporary t_string is implicitly created and then gets destroyed unexpectedly (reference [https://gna.org/bugs/index.php?20360 bug #20360]).<br />
<br />
=== Do not declare class data members as non-private ===<br />
<br />
It's okay to have a ''struct'' with only public members, if that's what you want.<br />
<br />
However, once something is a ''class'' with private data members, do not add public (or even protected) data members to the class. Doing this breaks encapsulation and can cause all kinds of confusing and evil things to happen.<br />
<br />
=== Destructors must not throw exceptions ===<br />
<br />
Do not allow exceptions to propogate from a destructor. Doing that is always bad in C++. Any code which does it should be treated as a bug and fixed. Doing this is a very easy way to cause memory leaks and crashes.<br />
<br />
It's okay to have exceptions thrown inside a destructor, just as long as you catch() them inside the destructor too and don't allow them to propagate out.<br />
<br />
In C++11, any destructor which throws an exception causes the program to be immediately terminated (except in special cases).<br />
<br />
You can read more about the issue here: http://c2.com/cgi/wiki?BewareOfExceptionsInTheDestructor<br />
<br />
== Naming ==<br />
<br />
=== End non-public class data members with an underscore ===<br />
<br />
All non-public data members of classes should have their names terminated with an underscore, to show that they are a class member. This makes for more readable code, once one is familiar with the convention.<br />
<br />
== Idioms ==<br />
<br />
=== Use references when a value may not be NULL ===<br />
<br />
If a value passed to a function can never be <tt>NULL</tt>, use a reference instead of a pointer. For example:<br />
<br />
void my_function(T& obj);<br />
<br />
rather than<br />
<br />
void my_function(T* obj);<br />
<br />
This more clearly shows prospective users of the function that <tt>obj</tt> may never be <tt>NULL</tt>, without them having to consult documentation or the implementation of the function.<br />
<br />
=== Use the const keyword ===<br />
<br />
The <tt>const</tt> keyword in C++ allows interfaces to more clearly specify how they treat objects. <br />
Always use <tt>const</tt> when you are not going to modify an object. For example:<br />
<br />
void my_function(const T& obj);<br />
<br />
This shows to the caller that <tt>obj</tt> will not be modified. If <tt>my_function()</tt> may modify <tt>obj</tt>, then use the following instead:<br />
<br />
void my_function(T& obj);<br />
<br />
Likewise, if a variable is not changed after initialization, make it <tt>const</tt>, and mark member functions as <tt>const</tt> if they do not modify their object.<br />
<br />
=== Know the behavior of const references when types differ ===<br />
<br />
If you assign something to a <tt>const</tt> reference of a different type, if necessary (if the type is different but there is a conversion) the compiler will create a temporary and guarantee it lasts for the lifetime of the reference. So<br />
<br />
char c = 0;<br />
const int& i = c;<br />
c = 5;<br />
<br />
will result in c == 5 and i == 0, which may not be what you expect.<br />
<br />
=== Write exception-safe code ===<br />
<br />
Wesnoth code should be exception-safe, even if you do not use exceptions directly. That is, you should be able to assume that an exception is thrown almost anywhere from within the code, with well-defined results (i.e. no resource leaks).<br />
<br />
Code that uses a pattern like the following is bad:<br />
<br />
{<br />
SDL_Surface* image = IMG_Load("image.bmp");<br />
...some code, which uses 'image'...<br />
SDL_FreeSurface(image);<br />
}<br />
<br />
The code may throw an exception, and <tt>image</tt> will never be freed. Instead, use wrapper objects which free the object in their destructor.<br />
<br />
For <tt>SDL_Surface</tt> objects, the <tt>surface</tt> type is used throughout the Wesnoth source code to achieve this purpose. So you could rewrite the above code as follows:<br />
<br />
{<br />
surface image(IMG_Load("image.bmp"));<br />
...some code, which uses 'image'...<br />
} ''the image is automatically freed here when 'image' is destroyed<br />
<br />
Instead of allocating memory directly using <tt>new[]</tt> or <tt>malloc()</tt>, use language-provided containers, such as vector.<br />
<br />
Similarly, avoid writing <tt>delete</tt> explicitly in your code. Oftentimes using a smart pointer or similar instead will improve the readability of your code, by making it obvious that you are managing memory correctly even if an exception is thrown. If you were deleting a pointer which is a member variable of an object, using a smart pointer instead may simplify your code by eliminating the need to write an explicit destructor in some cases.<br />
<br />
For more information, you can read about the (important) RAII idiom: http://c2.com/cgi/wiki?ResourceAcquisitionIsInitialization<br />
<br />
=== Do not use sprintf ===<br />
<br />
The <tt>sprintf()</tt> function does not check whether or not it is writing past the end of the space allocated. This is a security problem if someone other than the person running the game can cause <tt>sprintf()</tt> to write very long strings. In Wesnoth, this untrusted data could come potentially from other players in a multiplayer game, or from downloaded add-ons. Instead you should use <tt>snprintf()</tt> with the second argument being the <tt>sizeof</tt> of the buffer that will hold the result.<br />
<br />
== Standard C++ to avoid ==<br />
<br />
=== Do not use 0 or NULL when you mean nullptr ===<br />
<br />
Several Wesnoth developers, including Dave, find the number 0 to be very ambiguous when used in a non-numeric context. In keeping with the precedent that has already been established in the Wesnoth source code, you should avoid using literal zero for initializing and/or comparing null pointers.<br />
<br />
=== Do not use standard io functions ===<br />
This implies the std::fstream class and fopen. These functions do not support utf8 in windows which is our standard encoding for filepaths. Use our custom filesystem functions (filesystem.hpp) instead.<br />
<br />
== C legacy to be avoided ==<br />
<br />
=== Use std::array instead of C-style Arrays ===<br />
<br />
C-style arrays are very efficient, but their interface is ugly. Use <tt>std::array</tt> instead.<br />
<br />
=== Do not use C-style casts ===<br />
<br />
The following code,<br />
<br />
if(i->second.side() == (size_t)player_number_) {<br />
<br />
is considered bad practice in C++ since a C-style cast is overpowered -- if types change around it could end up casting away constness, or performing an implementation-defined data reinterpretation (basically a C-style cast is a compiler-generated combination of <tt>static_cast</tt>, <tt>reinterpret_cast</tt>, and <tt>const_cast</tt>).<br />
<br />
Good programming style is to use the least powerful tool available that does what you want. For example:<br />
<br />
if(i->second.side() == static_cast<size_t>(player_number_)) {<br />
<br />
Alternatively, a constructor call may be used for non-built-in types.<br />
<br />
''Note: there may be some obscure cases where a C-style cast is desirable, such as converting a pointer to an integer type of unspecified size.''<br />
<br />
=== Do not use #define for constants ===<br />
<br />
<tt><nowiki>#</nowiki>define foo X</tt> is not a typesafe approach to define constants. Instead, you can something like the following (in an anonymous namespace) to achieve the same goal in a typesafe fashion.<br />
<br />
namespace {<br />
const T foo = X;<br />
}<br />
<br />
== Documentation ==<br />
<br />
=== Document config preconditions and postconditions ===<br />
<br />
In the Wesnoth code you will commonly encounter a data container type known as <tt>config</tt>, which contains hierarchical string data (such as WML contents or game settings). The tagged ''children'' of the <tt>config</tt> object and their string ''attributes'' are arranged in an ordered and mapped format, internally implemented using the C++ STL.<br />
<br />
Because <tt>config</tt> data is utilized in so many ways and places, it can be difficult to track across the scope of the entire program. Thus, you should document all public functions that take/return <tt>config</tt> objects, specifying content expectations and updating any related entries in the [[ReferenceWML]] wiki pages. In particular, if your function requires a <tt>config</tt> parameter, specify where/how the <tt>config</tt> object should be created. This will be a great help to any future coders who need to call or modify your function.<br />
<br />
=== Doxygen ===<br />
<br />
See [[Doxygen]] for tips on how to comment the code, so that Doxygen can nicely document it.<br />
<br />
== See also ==<br />
<br />
* [[HackingWesnoth]]<br />
<br />
[[Category:Development]]</div>Vultrazhttps://wiki.wesnoth.org/index.php?title=Template:WML_Tags&diff=57928Template:WML Tags2016-10-08T22:31:00Z<p>Vultraz: Added [difficulty]</p>
<hr />
<div>{| class="gallery" style="width:225px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 7pt;margin-left;10px;"<br />
|-<br />
|<br />
<span style="float: right;"><small class="editlink noprint plainlinksneverexpand">[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit ]</small></span><br />
'''WML Tags'''<br />
<br />
|-<br />
|''A:'' <br />
[[AbilitiesWML|abilities]],<br />
[[CampaignWML#Campaign credits|about]],<br />
[[Creating_Custom_AIs#Behavior_Candidate_Actions|add_ai_behavior]],<br />
[[AbilitiesWML#Common_keys_and_tags_for_every_ability|adjacent_description]],<br />
[[SingleUnitWML|advance]],<br />
[[AdvancedPreferenceWML|advanced_preference]],<br />
[[UnitTypeWML|advancefrom]],<br />
[[UnitTypeWML#After_max_level_advancement_.28AMLA.29|advancement]],<br />
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|advances]],<br />
[[AbilitiesWML#Common_keys_and_tags_for_every_ability|affect_adjacent]],<br />
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|ai]],<br />
[[StandardSideFilter|allied_with]], <br />
[[DirectActionsWML#.5Ballow_end_turn.5D|allow_end_turn]],<br />
[[DirectActionsWML#.5Ballow_extra_recruit.5D|allow_extra_recruit]],<br />
[[DirectActionsWML#.5Ballow_recruit.5D|allow_recruit]],<br />
[[DirectActionsWML#.5Ballow_undo.5D|allow_undo]],<br />
[[ConditionalActionsWML#Meta-Condition_Tags|and]],<br />
[[InterfaceActionsWML#.5Banimate_unit.5D|animate]],<br />
[[InterfaceActionsWML#.5Banimate_unit.5D|animate_unit]],<br />
[[AnimationWML|animation]],<br />
[[VariablesWML#Array|array]],<br />
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|aspect]],<br />
[[UnitTypeWML#Attacks|attack]],<br />
[[AnimationWML|attack_anim]],<br />
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|attacks]],<br />
[[AiWML#List_of_AI_Aspects|avoid]];<br />
|-<br />
|''B:'' <br />
[[UnitTypeWML#Other_tags|base_unit]], <br />
[[AbilitiesWML|berserk]], <br />
[[BinaryPathWML|binary_path]],<br />
[[InternalActionsWML#Flow_control_actions|break]];<br />
|-<br />
|''C:'' <br />
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],<br />
[[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag|candidate_action]], <br />
[[DirectActionsWML#.5Bcapture_village.5D|capture_village]],<br />
[[ConditionalActionsWML#.5Bswitch.5D|case]],<br />
[[AbilitiesWML#The_.5Bspecials.5D_tag|chance_to_hit]], <br />
[[InterfaceActionsWML#.5Bchat.5D|chat]],<br />
[[ReplayWML|choose]],<br />
[[PersistenceWML|clear_global_variable]],<br />
[[InterfaceActionsWML#.5Bclear_menu_item.5D|clear_menu_item]],<br />
[[InternalActionsWML#.5Bclear_variable.5D|clear_variable]],<br />
[[InterfaceActionsWML#.5Bcolor_adjust.5D|color_adjust]],<br />
command&nbsp;([[ConditionalActionsWML#.5Bcommand.5D|action]], [[ReplayWML|replay]]),<br />
[[InternalActionsWML#Flow_control_actions|continue]],<br />
[[AiWML#The_.5Bgoal.5D_Tag|criteria]];<br />
|-<br />
|''D:'' <br />
[[AbilitiesWML#The_.5Bspecials.5D_tag|damage]],<br />
[[AnimationWML#death|death]], <br />
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|deaths]],<br />
[[AnimationWML#default|default]], <br />
[[AnimationWML#defend|defend]],<br />
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|defends]],<br />
[[UnitsWML#.5Bmovetype.5D|defense]],<br />
[[InterfaceActionsWML#.5Bdelay.5D|delay]],<br />
[[InterfaceActionsWML#.5Bdeprecated_message.5D|deprecated_message]],<br />
[[ReplayWML|destination]],<br />
[[CampaignWML|difficulty]],<br />
[[AbilitiesWML|disable]],<br />
[[DirectActionsWML#.5Bdisallow_end_turn.5D|disallow_end_turn]],<br />
[[DirectActionsWML#.5Bdisallow_extra_recruit.5D|disallow_extra_recruit]],<br />
[[DirectActionsWML#.5Bdisallow_recruit.5D|disallow_recruit]],<br />
[[ConditionalActionsWML#.5Bwhile.5D|do]], <br />
[[DirectActionsWML#.5Bdo_command.5D|do_command]],<br />
[[AbilitiesWML#The_.5Bspecials.5D_tag|drains]], <br />
[[AnimationWML#draw_weapon_anim|draw_weapon_anim]];<br />
|-<br />
|''E:'' <br />
[[EffectWML|effect]],<br />
else&nbsp;([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#.5Bif.5D_and_.5Belse.5D|animation]]), [[ConditionalActionsWML#.5Bif.5D|elseif]],<br />
[[DirectActionsWML#.5Bendlevel.5D|endlevel]],<br />
end_turn&nbsp;([[DirectActionsWML#.5Bend_turn.5D|action]], [[ReplayWML|replay]]),<br />
[[StandardSideFilter|enemy_of]], <br />
[[Wesnoth_AI_Framework#Available_Engines|engine]], <br />
[[CampaignWML#Campaign_credits|entry]], <br />
[[EraWML|era]],<br />
[[EventWML|event]],<br />
[[AnimationWML#Simplified_animation_blocks|extra_anim]];<br />
|-<br />
|''F:''<br />
[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]],<br />
[[InterfaceActionsWML#.5Banimate_unit.5D|facing]], <br />
[[InterfaceActionsWML#.5Bmove_units_fake.5D|fake_unit]], <br />
[[ConditionalActionsWML#True_Condition_Tags|false]],<br />
[[UnitTypeWML#Other_tags|female]], <br />
[[FilterWML|filter]],<br />
[[StandardUnitFilter|filter_adjacent]], <br />
[[StandardLocationFilter|filter_adjacent_location]], <br />
[[FilterWML#Filtering_Weapons|filter_attack]],<br />
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_attacker]], <br />
[[AbilitiesWML#Common_keys_and_tags_for_every_ability|filter_base_value]], <br />
[[EventWML#.5Bfilter_condition.5D|filter_condition]],<br />
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_defender]], <br />
[[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|filter_enemy]],<br />
[[StandardLocationFilter|filter_location]],<br />
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_opponent]], <br />
[[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|filter_own]],<br />
[[StandardLocationFilter|filter_owner]], <br />
[[StandardLocationFilter|filter_radius]], <br />
[[SingleUnitWML|filter_recall]], <br />
[[StandardUnitFilter|filter_second]],<br />
[[FilterWML#Filtering_Weapons|filter_second_attack]],<br />
[[AbilitiesWML|filter_self]], <br />
[[StandardSideFilter|filter_side]],<br />
[[FilterWML#Filtering_Vision|filter_vision]],<br />
[[AbilitiesWML#Common_keys_and_tags_for_every_weapon_special|filter_weapon]], <br />
[[StandardUnitFilter|filter_wml]],<br />
[[InternalActionsWML#.5Bfind_path.5D|find_path]],<br />
[[InternalActionsWML#.5Bfire_event.5D|fire_event]],<br />
[[AbilitiesWML#The_.5Bspecials.5D_tag|firststrike]], <br />
[[InterfaceActionsWML#.5Bfloating_text.5D|floating_text]],<br />
[[ConditionalActionsWML#.5Bfor.5D|for]],<br />
[[ConditionalActionsWML#.5Bforeach.5D|foreach]],<br />
[[AnimationWML#Frames|frame]],<br />
[[DirectActionsWML#.5Bfull_heal.5D|full_heal]];<br />
|-<br />
|''G:'' <br />
[[GameConfigWML|game_config]],<br />
[[PersistenceWML|get_global_variable]],<br />
[[AiWML#The_.5Bgoal.5D_Tag|goal]],<br />
[[DirectActionsWML#.5Bgold.5D|gold]],<br />
[[InterfaceActionsWML#.5Bobjectives.5D|gold_carryover]];<br />
|-<br />
|''H:'' <br />
[[DirectActionsWML#.5Bharm_unit.5D|harm_unit]],<br />
[[StandardSideFilter|has_unit]], <br />
[[ConditionalActionsWML#Condition_Tags|have_location]],<br />
[[ConditionalActionsWML#Condition_Tags|have_unit]],<br />
[[AbilitiesWML#The_.5Bspecials.5D_tag|heal_on_hit]], <br />
[[DirectActionsWML#.5Bheal_unit.5D|heal_unit]],<br />
[[AnimationWML#healed|healed_anim]], <br />
[[AnimationWML#healing|healing_anim]], <br />
[[AbilitiesWML|heals]], <br />
[[UnitsWML#.5Bhide_help.5D|hide_help]],<br />
[[InterfaceActionsWML#.5Bhide_unit.5D|hide_unit]],<br />
[[AbilitiesWML|hides]];<br />
|-<br />
|''I:'' <br />
[[AnimationWML#idling|idle_anim]], <br />
if&nbsp;([[ConditionalActionsWML#.5Bif.5D|action]], [[AnimationWML#.5Bif.5D_and_.5Belse.5D|animation]]),<br />
[[AbilitiesWML|illuminates]], <br />
[[TerrainGraphicsWML|image]],<br />
[[ReplayWML|init_side]],<br />
[[InternalActionsWML#.5Binsert_tag.5D|insert_tag]],<br />
[[InterfaceActionsWML#.5Binspect.5D|inspect]],<br />
[[InterfaceActionsWML#.5Bitem.5D|item]];<br />
|-<br />
|''J:''<br />
[[UnitsWML#.5Bmovetype.5D|jamming_costs]],<br />
[[InternalActionsWML#.5Bset_variables.5D|join]];<br />
|-<br />
|''K:'' <br />
[[DirectActionsWML#.5Bkill.5D|kill]],<br />
[[StatisticalScenarioWML|killed]];<br />
|-<br />
|''L:'' <br />
[[InterfaceActionsWML#.5Blabel.5D|label]],<br />
[[LanguageWML|language]],<br />
[[AiWML#List_of_AI_Aspects|leader_goal]],<br />
[[AbilitiesWML|leadership]], <br />
[[AnimationWML#leading|leading_anim]], <br />
[[AnimationWML#levelin|levelin_anim]],<br />
[[AnimationWML#levelout|levelout_anim]], <br />
[[DirectActionsWML#.5Blift_fog.5D|lift_fog]],<br />
[[AI_Recruitment#Aspect_recruitment_instructions|limit]],<br />
[[InternalActionsWML#.5Bset_variables.5D|literal]], <br />
[[LocaleWML|locale]],<br />
[[InterfaceActionsWML#.5Block_view.5D|lock_view]],<br />
[[LuaWML|lua]];<br />
|-<br />
|''M:'' <br />
[[UnitTypeWML#Other_tags|male]], <br />
[[SavefileWML|menu_item]], <br />
[[InterfaceActionsWML#.5Bmessage.5D|message]],<br />
[[Micro AIs|micro_ai]],<br />
[[AnimationWML#The_content_of_a_frame|missile_frame]],<br />
[[ModificationWML|modification]],<br />
[[SingleUnitWML|modifications]],<br />
[[DirectActionsWML#.5Bmodify_ai.5D|modify_ai]],<br />
[[DirectActionsWML#.5Bmodify_side.5D|modify_side]],<br />
[[DirectActionsWML#.5Bmodify_turns.5D|modify_turns]],<br />
[[DirectActionsWML#.5Bmodify_unit.5D|modify_unit]],<br />
[[ReplayWML|move]],<br />
[[DirectActionsWML#.5Bmove_unit.5D|move_unit]],<br />
[[InterfaceActionsWML#.5Bmove_unit_fake.5D|move_unit_fake]],<br />
[[InterfaceActionsWML#.5Bmove_units_fake.5D|move_units_fake]],<br />
[[AnimationWML#movement|movement_anim]], <br />
[[UnitsWML#.5Bmovetype.5D|movement costs]],<br />
[[UnitsWML#.5Bmovetype.5D|movetype]],<br />
[[ScenarioWML|multiplayer]],<br />
[[EraWML|multiplayer_side]],<br />
[[MusicListWML#.5Bmusic.5D|music]];<br />
|-<br />
|''N:'' <br />
[[ConditionalActionsWML#Meta-Condition_Tags|not]], <br />
[[InterfaceActionsWML#.5Bobjectives.5D|note]];<br />
|-<br />
|''O:'' <br />
[[DirectActionsWML#.5Bobject.5D|object]],<br />
[[InterfaceActionsWML#.5Bobjectives.5D|objective]],<br />
[[InterfaceActionsWML#.5Bobjectives.5D|objectives]],<br />
[[InterfaceActionsWML#.5Bopen_help.5D|open_help]],<br />
[[InterfaceActionsWML#.5Bmessage.5D|option]],<br />
[[OptionWML|options]],<br />
[[ConditionalActionsWML#Meta-Condition_Tags|or]];<br />
|-<br />
|''P:'' <br />
[[IntroWML|part]], <br />
[[AbilitiesWML#The_.5Bspecials.5D_tag|petrifies]], <br />
[[DirectActionsWML#.5Bpetrify.5D|petrify]], <br />
[[DirectActionsWML#.5Bplace_shroud.5D|place_shroud]], <br />
[[AbilitiesWML#The_.5Bspecials.5D_tag|plague]], <br />
[[AbilitiesWML#The_.5Bspecials.5D_tag|poison]], <br />
[[UnitTypeWML#Other_tags|portrait]], <br />
[[AnimationWML#post_movement|post_movement_anim]], <br />
[[AnimationWML#pre_movement|pre_movement_anim]], <br />
[[FilterWML#Filtering_Weapons|primary_attack]], <br />
[[StandardUnitFilter|primary_unit]], <br />
[[InterfaceActionsWML#.5Bprint.5D|print]], <br />
[[DirectActionsWML#.5Bput_to_recall_list.5D|put_to_recall_list]];<br />
|-<br />
|''R:'' <br />
[[UnitsWML#.5Brace.5D|race]], <br />
[[ReplayWML|random]], <br />
recall&nbsp;([[DirectActionsWML#.5Brecall.5D|action]], [[ReplayWML|replay]]), <br />
[[StatisticalScenarioWML|recalls]],<br />
[[ReplayWML|recruit]], <br />
[[AnimationWML#recruited|recruit_anim]], <br />
[[AnimationWML#recruiting|recruiting_anim]], <br />
[[StatisticalScenarioWML|recruits]], <br />
[[InterfaceActionsWML#.5Bredraw.5D|redraw]],<br />
[[AbilitiesWML|regenerate]],<br />
[[InternalActionsWML#.5Bremove_event.5D|remove_event]],<br />
[[InterfaceActionsWML#.5Bremove_item.5D|remove_item]], <br />
[[DirectActionsWML#.5Bremove_shroud.5D|remove_shroud]], <br />
[[InterfaceActionsWML#.5Bremove_sound_source.5D|remove_sound_source]], <br />
[[DirectActionsWML#.5Bremove_time_area.5D|remove_time_area]], <br />
[[InterfaceActionsWML#.5Bremove_unit_overlay.5D|remove_unit_overlay]],<br />
[[ConditionalActionsWML#.5Brepeat.5D|repeat]],<br />
[[DirectActionsWML#.5Breplace_map.5D|replace_map]], <br />
[[DirectActionsWML#.5Breplace_schedule.5D|replace_schedule]], <br />
[[ReplayWML|replay]], <br />
[[SavefileWML|replay_start]],<br />
[[DirectActionsWML#.5Breset_fog.5D|reset_fog]], <br />
resistance&nbsp;([[AbilitiesWML|ability]], [[UnitsWML#.5Bmovetype.5D|unit]]),<br />
[[UnitsWML#.5Bresistance_defaults.5D|resistance_defaults]],<br />
[[ModificationWML#The_.5Bresource.5D_toplevel_tag|resource]],<br />
[[ReplayWML|results]],<br />
[[InternalActionsWML#Flow_control_actions|return]],<br />
[[InternalActionsWML#.5Brole.5D|role]], <br />
[[TerrainMaskWML|rule]];<br />
|-<br />
|''S:'' <br />
[[SavefileWML|save]], <br />
[[ScenarioWML|scenario]],<br />
[[InterfaceActionsWML#.5Bscroll.5D|scroll]], <br />
[[InterfaceActionsWML#.5Bscroll_to.5D|scroll_to]],<br />
[[InterfaceActionsWML#.5Bscroll_to_unit.5D|scroll_to_unit]], <br />
[[FilterWML#Filtering_Weapons|secondary_attack]], <br />
[[StandardUnitFilter|secondary_unit]], <br />
[[HelpWML|section]], <br />
[[InterfaceActionsWML#.5Bselect_unit.5D|select_unit]], <br />
[[ReplayWML|sequence]], <br />
[[DirectActionsWML#.5Bset_extra_recruit.5D|set_extra_recruit]],<br />
[[PersistenceWML|set_global_variable]],<br />
[[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]], <br />
[[DirectActionsWML#.5Bset_recruit.5D|set_recruit]],<br />
[[EffectWML|set_specials]], <br />
[[InternalActionsWML#.5Bset_variable.5D|set_variable]], <br />
[[InternalActionsWML#.5Bset_variables.5D|set_variables]], <br />
[[AnimationWML#sheath_weapon|sheath_weapon_anim]], <br />
show_if&nbsp;([[InterfaceActionsWML#.5Bmessage.5D|message]], [[InterfaceActionsWML#.5Bset_menu_item.5D|set_menu_item]]),<br />
[[InterfaceActionsWML#.5Bshow_objectives.5D|show_objectives]],<br />
[[SideWML|side]], <br />
[[AbilitiesWML|skirmisher]], <br />
[[AbilitiesWML#The_.5Bspecials.5D_tag|slow]], <br />
[[SavefileWML|snapshot]],<br />
[[InterfaceActionsWML#.5Bsound.5D|sound]], <br />
[[InterfaceActionsWML#.5Bsound_source.5D|sound_source]], <br />
source&nbsp;([[ReplayWML|replay]], [[DirectActionsWML#.5Btunnel.5D|teleport]]),<br />
[[AbilitiesWML#The_.5Bspecials.5D_tag|specials]], <br />
[[InternalActionsWML#.5Bset_variables.5D|split]],<br />
[[Wesnoth_AI_Framework#Available_Stages|stage]], <br />
[[AnimationWML#standing|standing_anim]], <br />
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],<br />
[[SingleUnitWML|status]], <br />
[[InternalActionsWML#.5Bstore_gold.5D|store_gold]], <br />
[[InternalActionsWML#.5Bstore_items.5D|store_items]], <br />
[[InternalActionsWML#.5Bstore_locations.5D|store_locations]],<br />
[[InternalActionsWML#.5Bstore_map_dimensions.5D|store_map_dimensions]],<br />
[[InternalActionsWML#.5Bstore_reachable_locations.5D|store_reachable_locations]],<br />
[[InternalActionsWML#.5Bstore_relative_direction.5D|store_relative_direction]],<br />
[[InternalActionsWML#.5Bstore_side.5D|store_side]], <br />
[[InternalActionsWML#.5Bstore_starting_location.5D|store_starting_location]], <br />
[[InternalActionsWML#.5Bstore_time_of_day.5D|store_time_of_day]], <br />
[[InternalActionsWML#.5Bstore_turns.5D|store_turns]], <br />
[[InternalActionsWML#.5Bstore_unit.5D|store_unit]], <br />
[[InternalActionsWML#.5Bstore_unit_type.5D|store_unit_type]], <br />
[[InternalActionsWML#.5Bstore_unit_type_ids.5D|store_unit_type_ids]], <br />
[[InternalActionsWML#.5Bstore_villages.5D|store_villages]], <br />
[[IntroWML|story]], <br />
[[AbilitiesWML#The_.5Bspecials.5D_tag|swarm]], <br />
[[ConditionalActionsWML#.5Bswitch.5D|switch]],<br />
[[InternalActionsWML#.5Bsync_variable.5D|sync_variable]];<br />
|-<br />
|''T:'' <br />
[[DirectActionsWML#.5Btunnel.5D|target]], <br />
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],<br />
teleport&nbsp;([[AbilitiesWML|ability]], [[DirectActionsWML#.5Bteleport.5D|action]]),<br />
[[AnimationWML#pre_teleport|teleport_anim]],<br />
[[DirectActionsWML#.5Bterrain.5D|terrain]], <br />
[[UnitsWML#.5Bterrain_defaults.5D|terrain_defaults]],<br />
[[TerrainGraphicsWML|terrain_graphics]], <br />
[[TerrainMaskWML|terrain_mask]], <br />
[[TerrainWML|terrain_type]], <br />
[[ScenarioWML#Test_scenario|test]],<br />
[[InterfaceActionsWML#.5Btest_condition.5D|test_condition]],<br />
[[InterfaceActionsWML#.5Bmessage.5D|text_input]], <br />
[[WesCamp#The_textdomain_declaration|textdomain]],<br />
[[ConditionalActionsWML#.5Bif.5D|then]],<br />
[[TerrainGraphicsWML|tile]], <br />
[[TimeWML|time]], <br />
[[DirectActionsWML#.5Btime_area.5D|time_area]], <br />
[[HelpWML|topic]], <br />
[[HelpWML|toplevel]], <br />
[[UnitsWML#.5Btrait.5D|trait]], <br />
[[DirectActionsWML#.5Btransform_unit.5D|transform_unit]], <br />
[[InternalActionsWML#.5Bfind_path.5D|traveler]], <br />
[[ConditionalActionsWML#True_Condition_Tags|true]],<br />
[[DirectActionsWML#.5Btunnel.5D|tunnel]], <br />
[[ScenarioWML|tutorial]];<br />
|-<br />
|''U:'' <br />
[[InterfaceActionsWML#.5Bunhide_unit.5D|unhide_unit]], <br />
[[SingleUnitWML|unit]],<br />
[[InterfaceActionsWML#.5Bunit_overlay.5D|unit_overlay]], <br />
[[UnitTypeWML|unit_type]], <br />
[[InternalActionsWML|unit_worth]], <br />
[[UnitsWML|units]],<br />
[[InterfaceActionsWML#.5Bunlock_view.5D|unlock_view]],<br />
[[DirectActionsWML#.5Bunpetrify.5D|unpetrify]], <br />
[[DirectActionsWML#.5Bunstore_unit.5D|unstore_unit]];<br />
|-<br />
| ''V:'' <br />
[[InternalActionsWML#.5Bset_variables.5D|value]], <br />
[[ConditionalActionsWML#Condition_Tags|variable]],<br />
[[VariablesWML#The_.5Bvariables.5D_tag|variables]],<br />
[[UnitTypeWML#Other_tags|variation]], <br />
[[AnimationWML#victory|victory_anim]], <br />
[[SideWML|village]],<br />
[[UnitsWML#.5Bmovetype.5D|vision_costs]],<br />
[[InterfaceActionsWML#.5Bvolume.5D|volume]];<br />
|-<br />
| ''W:'' <br />
[[ConditionalActionsWML#.5Bwhile.5D|while]],<br />
[[InterfaceActionsWML#.5Bwml_message.5D|wml_message]];<br />
|}<br />
<br />
<includeonly>[[Category:WML Reference]]</includeonly><br />
<br />
<noinclude>A box with all the WML tags, each one linking to the page and section they are described in. This box should be included in each of the WML reference pages.</noinclude></div>Vultrazhttps://wiki.wesnoth.org/index.php?title=CampaignWML&diff=57927CampaignWML2016-10-08T22:30:06Z<p>Vultraz: </p>
<hr />
<div>{{WML Tags}}<br />
<br />
<!--<br />
<br />
Dacyn and/or Invisible Philosopher -- please be careful<br />
you don't reduce the signal-to-noise ratio on the WML pages<br />
when editing! Eg. knowing that a tag is translatable is _important_<br />
for the 29 translations we have in progress. -- ott<br />
<br />
--><br />
<br />
This page describes how the campaign is displayed in the "Campaign" menu, and how it starts.<br />
<br />
==The [campaign] Tag==<br />
<br />
The following keys and tags are recognized in '''[campaign]''' tags:<br />
* '''id''': the internal campaign identifier used to classify saved games<br />
* '''icon''': the image displayed in the campaign selection menu<br />
* '''name''': (translatable) name displayed in the campaign selection menu<br />
* '''abbrev''': (translatable) abbreviation used as a prefix for savefile names made from this campaign<br />
* '''image''': the image shown in the information pane when this campaign is selected in the campaign selection menu (typically a transparent, 350×350 pixels portrait)<br />
* '''description''': (translatable) text shown in the information pane when this campaign is selected in the campaign selection menu<br />
* '''description_alignment''': {{DevFeature1.13|3}} The text alignment of the description. Choose between "left" (default), "center", or "right".<br />
* '''type''': campaign's type to specify if it should be visible in singleplayer, multiplayer or both. Possible values are "sp", "mp" and "hybrid". Defaults to "sp".<br />
* '''define'''='''''CAMPAIGN_SYMBOL''''' when this campaign is started, the preprocessor symbol '''''CAMPAIGN_SYMBOL''''' will be defined. See '''#ifdef''' in [[PreprocessorRef]] for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags '''[campaign]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''CAMPAIGN_SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed. Important note: starting with 1.7.13, [binary_path] does no longer need to be outside of the '''#ifdef ''CAMPAIGN_SYMBOL''''' block to make custom binary data available, which could easily cause overwrites. E.g. icon=data/add-ons/whatever/something.png is supposed to work. This seems to have been a bug since at least BfW 1.0 which means that practically all available examples of user made add-ons are wrong in this aspect.<br />
* '''extra_defines''': a comma(''',''') separated list of preprocessor symbols. Those symbols will be defined ''before'' any .cfg is preprocessed. Currently supported extra_defines are:<br />
<ul><br />
;ENABLE_ARMAGEDDON_DRAKE<br />
:allows the advancement ''Inferno Drake'' -> ''Armageddon Drake''<br />
;ENABLE_DWARVISH_ARCANISTER<br />
:allows the advancement ''Dwarvish Runemaster'' -> ''Dwarvish Arcanister''<br />
;ENABLE_DWARVISH_RUNESMITH<br />
:allows the advancement ''Dwarvish Fighter'' -> ''Dwarvish Runesmith''<br />
;DISABLE_GRAND_MARSHAL<br />
:disallows the advancement ''General'' -> ''Grand Marshal''<br />
;ENABLE_ANCIENT_LICH<br />
:allows the advancement ''Lich'' -> ''Ancient Lich''<br />
;ENABLE_DEATH_KNIGHT<br />
:allows the advancement ''Revenant'' -> ''Death Knight'<br />
;ENABLE_TROLL_SHAMAN<br />
:allows the advancement ''Troll Whelp'' -> ''Troll Shaman''<br />
;ENABLE_WOLF_ADVANCEMENT<br />
:allows the advancements ''Wolf'' -> ''Great Wolf'' -> ''Direwolf''<br />
;ENABLE_NIGHTBLADE {{DevFeature1.13|0}}<br />
:allows the advancement ''Orcish Slayer'' -> ''Orcish Nightblade''<br />
;ENABLE_KHALID {{DevFeature1.13|0}}<br />
:allows the advancement ''Shuja'' -> ''Khalid''<br />
</ul><br />
* '''difficulties''': a comma(''',''') separated list of preprocessor symbols, exactly one of which will be stored depending on the difficulty setting chosen when the campaign is started. The symbols '''EASY''', '''NORMAL''', and '''HARD''' are usually used, and there are several macros in utils.cfg (see [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg| Macro Reference]) which check for these values to set WML keys to different values depending on difficulty. If you use different difficulty symbols, you may need to define your own versions of these macros. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=.<br />
* '''difficulty_descriptions''': the menu of difficulties; this is a list of descriptions (see [[DescriptionWML]]) that correspond to different difficulty levels. Since each description is a menu option for a difficulty level, this must provide the same number of descriptions as there are levels in the ''difficulties'' list. {{DevFeature1.13|2}} This key has been deprecated in favor of [difficulty] define=<br />
* '''[difficulty]''': {{DevFeature1.13|2}} specifies a single campaign difficulty. The following keys are accepted:<br />
** '''define''': the preprocessor symbol defined when this difficulty is selected. Uses the same format as an entry in the old ''difficulties'' list.<br />
** '''image''': the image to display for this difficulty in the selection menu<br />
** '''label''': a flavor label describing this difficulty. Displayed second after the image<br />
** '''description''': a description of the difficulty, usually along the lines of "Beginner" or "Challenging". Displayed third after the image.<br />
** '''default''': whether this is the difficulty which will be selected by default when the difficulty selection menu is displayed.<br />
* '''allow_difficulty_change''': Allows difficulty switching during an ongoing campaign. Default:yes<br />
* '''first_scenario''': the ID of the first scenario in the campaign; see ''id'' in [[ScenarioWML]]<br />
* '''[options]''': {{DevFeature1.13|1}} Allows configuration options to be displayed to the user, see [[OptionWML]]<br />
* '''rank''': a number that determines the order of campaigns in the campaign selection menu. Lower ''rank'' campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 10 from 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400. (Note: This replaces an older convention that topped out at 50.)<br />
* '''[about]''': inserts your own credits into the game's list of credits. See below for syntax.<br />
* '''end_credits''': Whether to display the credits screen at the end of the campaign. Defaults to ''yes''.<br />
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End".<br />
* '''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.<br />
* '''[event]''': {{DevFeature1.13|2}} events placed here will be automatically inserted into all scenarios of the campaign.<br />
<br />
The following keys are additionally recognized in multiplayer:<br />
* '''min_players''': Minimum number of players campaign supports. Defaults to 2.<br />
* '''max_players''': Maximum number of players campaign supports. Defaults to '''min_players'''.<br />
* '''allow_era_choice''': Whether to hide era selection and use a default one when creating a game. Defaults to ''yes''.<br />
* '''require_campaign''': Whether clients are required to have this campaign installed beforehand to be allowed join a game using this campaign. Possible values 'yes' (the default) and 'no'.<br />
<br />
== Campaign credits ==<br />
<br />
The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs. There can be any number of '''[about]''' tags inside a '''[campaign]''' tag, but none of them will display credits if there is no "id" key present inside [campaign] (see above). The '''[about]''' tag has the following keys:<br />
* '''title''': (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits<br />
* '''text''': (translatable, but you probably won't want to make it such) smaller text which is displayed before the contributor names<br />
* '''[entry]''': Contains information about a single contributor. Only the ''name'' key will be used in-game, the other three keys are for display on the [[Credits]] page ('''note:''' the values of these keys will only display on the Credits page for mainline campaigns; they will not display for UMC campaigns)<br />
** '''name''': The name of the contributor<br />
** '''comment''': Optional short note about what that person did<br />
** '''email''': Optional email address<br />
** '''wikiuser''': Optional, the user name on the wiki<br />
<br />
== See Also ==<br />
<br />
* [[PreprocessorRef]]<br />
* [[ScenarioWML]]<br />
* [[ReferenceWML]]<br />
* [[PblWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vultraz