https://wiki.wesnoth.org/api.php?action=feedcontributions&user=Cannedfood&feedformat=atomThe Battle for Wesnoth Wiki - User contributions [en]2024-03-28T16:09:39ZUser contributionsMediaWiki 1.31.16https://wiki.wesnoth.org/index.php?title=CampaignWML&diff=60173CampaignWML2019-01-26T20:57:25Z<p>Cannedfood: /* The [campaign] Tag */ added usage of min_players and max_players</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_WARMASTER {{DevFeature1.13|11}}<br />
:allows the advancement ''Dune Blademaster'' -> ''Dune Warmaster''<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.) '''''(Version 1.14.6 and later only)''''' 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 />
* '''[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 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 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>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=ConditionalActionsWML&diff=59914ConditionalActionsWML2018-08-08T19:04:13Z<p>Cannedfood: VariablesWML -> SyntaxWML#Variables</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Part of [[ActionWML]], Conditional Actions WML is used to describe container actions that create branching and flow control for WML. The [[#Conditional Actions|conditional actions]] act as gatekeepers, encapsulating other actions with [[#Condition Tags|conditions]] which must be met before an action can take place. These conditional actions also contain the actions which will take place if those conditions are met and, in some cases, what actions will take place if they are ''not'' met.<br />
<br />
== Conditional Actions ==<br />
<br />
These actions describe actions that should be executed only if certain conditions are met.<br />
<br />
=== [if] ===<br />
<br />
Executes actions only if the contained [[#Condition Tags|conditions]] are met.<br />
<br />
* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.<br />
<br />
* '''[then]''': Contains [[ActionWML|actions]] which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.<br />
<br />
* '''[elseif]''': {{DevFeature1.13|0}} in case that the conditions inside [if] aren't met, these tags will be evalutated one by one. If the specified conditions are met, the contained [then] tags will be executed, and the cycle will end.<br />
** '''[then]''': it behaves exactly like the [then] tag inside [if].<br />
<br />
* '''[else]''': Contains [[ActionWML|actions]] which should be executed if any condition evaluates as false ''and'' '''all''' of the '''[or]''' tags evaluate as false.<br />
<br />
<br />
'''Attention''': There are tags named [if] and [else] inside [animation] (see [[AnimationWML#.5Bif.5D_and_.5Belse.5D|AnimationWML]]), which have a different syntax.<br />
<br />
Example usage:<br />
[if]<br />
[variable]<br />
name=we.gold<br />
greater_than=$they.gold<br />
[/variable]<br />
[then]<br />
[message]<br />
message=This should be easy!<br />
[/message]<br />
[/then]<br />
[else]<br />
[message]<br />
message=This will not be easy!<br />
[/message]<br />
[/else]<br />
[/if]<br />
<br />
=== [switch] ===<br />
<br />
The '''[switch]''' tag is a special case because it does not use [[#Condition Tags|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable. Boolean variable values are not accepted and cause lua errors currently.<br />
<br />
* '''variable''': The name of the variable to check.<br />
* '''[case]''': Case tag which forms a block containing:<br />
** '''value''': The value to test the variable's value against. This can be a comma separated list of values.<br />
** [[ActionWML|Action WML]]: Action WML to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)<br />
* '''[else]''': Else tag which forms a block of [[ActionWML|Action WML]] to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.<br />
<br />
Example usage:<br />
[switch]<br />
variable=foo<br />
[case]<br />
value="A"<br />
... WML if foo=A ...<br />
[/case]<br />
[case]<br />
value="B"<br />
... WML if foo=B ...<br />
[/case]<br />
[else]<br />
... WML if not foo=A nor foo=B ...<br />
[/else]<br />
[/switch]<br />
<br />
=== [while] ===<br />
<br />
Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags|conditions]] are no longer met. Executes a maximum of 65536 iterations per invocation.<br />
<br />
* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.<br />
<br />
* '''[do]''': contains [[ActionWML|actions]] that should be executed repeatedly until some condition is false.<br />
<br />
The '''[while]''' tag is useful for iterating over an array.<br />
An array is a list of values.<br />
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.<br />
Note that if '''number''' is the value of the variable '''variable''',<br />
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.<br />
<br />
==== 'FOREACH' Macro ====<br />
This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH] and [http://www.wesnoth.org/macro-reference.xhtml#NEXT NEXT] macros.<br />
<br />
==== 'REPEAT' Macro ====<br />
This macro simplifies the use of a '''[while]''' tag to execute the same [[ActionWML|actions]] repeatedly for a specified number of times. To use it, use the [http://www.wesnoth.org/macro-reference.xhtml#REPEAT REPEAT] macro.<br />
<br />
=== [for] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
Loops over an integer range. As of 1.13.2, this is used instead of [while] to implement the {FOREACH} macro. Note that, if iterating over an array to delete several elements, it is best to use '''reverse=yes''' to avoid accidentally skipping some elements.<br />
<br />
<!-- For some reason, standard wiki markup didn't work for this line --><br />
* '''variable''': The name of the variable containing the current index. Defaults to ''i''.<br />
* '''start''': The index of the first element to loop over, and sets the starting value of '''variable'''. Defaults to 0.<br />
* '''end''': The index of the final element to loop over, and sets the maximum allowed value of '''variable'''. Defaults to '''start'''.<br />
* '''step''': The value added to the current value of '''variable''' after each iteration of the loop. Defaults to 1 if '''start''' < '''end''', or -1 if '''start''' > '''end'''.<br />
** For example, if '''start=1''' and '''step=2''', then the value of '''variable''' for each iteration will be: 1, 3, 5, ...<br />
* '''array''': Specify an array to iterate over. This is a shortcut for setting '''start=0''' and '''end=$($array_name.length-1)'''<br />
** If '''array''' is set, then '''start''', '''end''', and '''step''' are ignored.<br />
* '''reverse''': If set to '''yes''', and '''array''' was specified, then this is a shortcut for setting '''start=$($array_name.length-1)''' and '''end=0'''.<br />
* '''[do]''': The actions to execute on each iteration.<br />
<br />
=== [foreach] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
Loops over an array variable. This is not used to implement the {FOREACH} macro because adding or removing elements while looping is not possible (and will usually raise an error).<br />
<br />
* '''array''': The array variable to loop over.<br />
* '''variable''': The name of a variable which refers to the current item. Defaults to ''this_item''. Any changes made to this variable will persist in the array after the loop has completed.<br />
* '''index_var''': The name of a variable which refers to the index of the current item. Defaults to ''i''. Note that this is just for information purposes and should not be used to access the array from within the loop (any such changes made will not persist).<br />
* '''readonly''': If set to yes, this prevents the array from being modified in any way during the loop. (It defaults to no.) That means that changes made through the '''variable''' will ''not'' persist. Changes made through the '''index_var''' will also not persist (as normal). In effect, the array is reverted to its original state once the loop exits.<br />
* '''[do]''': The actions to execute on each iteration.<br />
<br />
=== [repeat] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
Repeats some actions a fixed number of times. This is a completely stateless loop - there's no way to know which iteration of the loop you're on. (If you need this, use [for] instead.)<br />
<br />
* '''times''': The number of times to repeat the actions.<br />
* '''[do]''': The actions to repeat.<br />
<br />
=== [command] ===<br />
<br />
This tag is more of an Unconditional Action: when it is encountered, the [[ActionWML|actions]] in its content are simply executed once. In practice, this tag serves little purpose. However, it may be used to arrange actions together in logical groups, for example, with actions that are stored in an array and later inserted.<br />
(It is also used inside of [set_menu_item] and [option] of [[InterfaceActionsWML]].)<br />
<br />
== Condition Tags ==<br />
<br />
===True Condition Tags===<br />
These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions|Conditional Actions]].<br />
<br />
; [true]<br />
: Represents a condition that always yields true. Takes no arguments.<br />
<br />
; [false]<br />
: Represents a condition that always yields false. Takes no arguments.<br />
<br />
; [have_unit]<br />
: A unit with greater than zero hit points matching this filter exists.<br />
:* [[StandardUnitFilter]] '''*''': Selection criteria. Do not use a [filter] tag.<br />
:* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".<br />
:* '''search_recall_list''': ''(Optional)'' If 'yes', search through recall list too. (Default is 'no')<br />
<br />
; [have_location]<br />
: A location matching this filter exists.<br />
:* [[StandardLocationFilter]]: Selection criteria.<br />
:* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".<br />
<br />
; [variable]<br />
: Test the value of a WML [[SyntaxWML#Variables|variable]] against another value.<br />
:* '''name''': The name of the variable to test.<br />
:* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:<br />
:** '''contains''': ''$name'' contains this string value.<br />
:** '''equals''': ''$name'' is equal (string wise) to this value.<br />
:** '''not_equals''': ''$name'' is not equal (string wise) to this value.<br />
:** '''numerical_equals''': ''$name'' is equal (numerically) to this value. <br />
:** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value.<br />
:** '''greater_than''': ''$name'' is numerically greater than this value.<br />
:** '''greater_than_equal_to''': ''$name'' is numerically greater than or equal to this value.<br />
:** '''less_than''': ''$name'' is numerically less than this value.<br />
:** '''less_than_equal_to''': ''$name'' is numerically less than or equal to this value.<br />
:** '''boolean_equals''': ''$name'' has an equivalent boolean value.<br />
:** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value.<br />
<br />
; [found_item]<br />
: {{DevFeature1.13|2}} Test if an item (ie, a modification given by <nowiki>[</nowiki>[[DirectActionsWML#.5Bobject.5D|object]]]) has been found yet. Note: This will only detect objects added via ActionWML in an event. It will not detect objects added in [modifications] when a unit is created, nor objects added via [modify_unit] or the Lua wesnoth.add_modification function.<br />
:* '''id''': The ID of the item to test. It must exactly match an [object] that has been taken for the test to pass.<br />
<br />
====Boolean Values====<br />
When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.<br />
<br />
* These values are evaluated as ''true'': '''"yes"''' and '''"true"'''<br />
* These values are evaluated as ''false'': '''"no"''', '''"false"''' and '''""'''(uninitialized)<br />
** However, in contexts where ''true'' is defined as the default value, an uninitialized value would be considered true. <br />
<br />
'''Warning:''' Do not use "off", "on", integers, floating-point numbers or anything else than the above as booleans.<br />
<br />
=== Meta-Condition Tags ===<br />
<br />
These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in top-to-bottom order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.<br />
<br />
; [and]<br />
: A condition which must evaluate to true in addition to any other conditions that precede it. This is useful as a bracket for complex conditions, but not strictly necessary.<br />
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.<br />
<br />
; [or]<br />
: A condition which, when false, has no effect, but when true, allows previously failed conditions to be ignored. <br />
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true. <br />
<br />
; [not]<br />
: Similar to [and], but its contents must be false. Thus it reverses the evaluation of its contents. Since a normal condition tag without contents is always considered true, an empty [not] is always considered false.<br />
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.<br />
<br />
<br />
When multiple meta-conditions are encountered one after another in a containing tag, the evaluation order is as follows:<br />
# the immediate contents of the containing tag are evaluated first to determine if there is a successful match known as a "true" condition<br />
# this true or false result is combined with the top meta-condition to produce another true or false result<br />
# this result is combined with the next meta-condition, and so on. However, if the engine recognizes that no remaining meta-conditions might reverse the result, it will cleverly skip them.<br />
# if the final result is a successful match, then the [[:Category:ActionsWML|action]] will take place.<br />
<br />
For more details on use of meta-conditions, see [[AdvancedConditionalWML|these examples]].<br />
<br />
== See Also ==<br />
* [[SyntaxWML]]<br />
* [[InternalActionsWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=ImagePathFunctions&diff=59555ImagePathFunctions2018-04-30T22:52:01Z<p>Cannedfood: updated mention of sources for ILT</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]]<br />
<br />
[[Category:WML Reference]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=Talk:Agent/Swarm_based_AI&diff=59345Talk:Agent/Swarm based AI2018-03-30T16:56:07Z<p>Cannedfood: instantiated with one item in list of pages describing similar proposals</p>
<hr />
<div>== Similar Proposals ==<br />
<br />
=== [[AI_Development/Improvement]] ===<br />
<br />
Proposed in April 2008.</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=User_talk:Xudojnik&diff=59239User talk:Xudojnik2018-03-04T21:03:07Z<p>Cannedfood: regarding my edit to your user page …</p>
<hr />
<div>=== Hello, and about my edit to your user page ===<br />
<br />
I hope you are not upset that I performed a minor edit on your user page. I did so simply to remove it from the Category:WML_Reference, where it really didn't belong. If you like that infobox of Template:WML_Ttags, then we should devise something else which doesn't place your user page in a category where it doesn't actually feature. <br/><br />
I initially wanted to do all this because it was a small nuisance to me, but please don't think that I was being self–centered when I did so. Really, it helps make this wiki more useful and functional for everyone. [[User:Cannedfood|Cannedfood]] ([[User talk:Cannedfood|talk]]) 21:03, 4 March 2018 (UTC)</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=User:Xudojnik&diff=59238User:Xudojnik2018-03-04T20:57:37Z<p>Cannedfood: this doesn't belong in Category:WML_Reference, nor does it need the sidebar of Template:WML_Tags</p>
<hr />
<div>I know Wesnoth from version 1.1.2a. This is really perspective game not only as strategy, but as RPG too. Large world, filled by history, epic battles, heroes and factions, is perfect for creating RPG. It's not so hard because Wesnoth have simple language, what support wide variety of events, easy way to define dialogs, items, forum and Wiki, where always can be found answer for any question.<br />
<br />
===WesMMO===<br />
To play it (now only in theory):<br />
#*Download WesMMO era.<br />
#*Download any map, designed for WesMMO.<br />
#*Create game in lobby.<br />
#*WesMMO era will automatically use your account.<br />
#*Now choose any three units from your account or create new and play.<br />
#*Persistent data will be stored at the end of each turn<br />
<br />
Character is a "team" of three units. Each unit have own stats and small inventory<br />
;Stats:<br />
:Stamina - increases your hitpoints. ''Each point of stamina should increase survivalalibity of unit for an average amount of damage, given by 1 strength or agility, multiplied by 6.<br />
:Strength - increases your melee damage and armor contribution from items.<br />
:Speed - increases your movement points.<br />
:Agility - increase your ranged damage and defense on each type of terrain.<br />
::100 * A / (A + 30) 60% Defence at 45 agility<br />
::100 * A / (A + 20) 60% Defence at 30 agility<br />
::100 * A / (A + 10) 60% Defence at 15 agility<br />
:Intellect - increase magical potence of unit in some ways<br />
<br />
;Inventory:<br />
:Melee Weapon - affects melee combat: multiplies damage from strength and number of strikes.<br />
:Ranged Weapon - affects ranged combat: multiplies damage from agility and number of strikes.<br />
:Amulet - affects base stats, magical resistances and magical potency of unit<br />
:Body Armor - affects base stats, all resistances and defenses.<br />
:Boots - affects base stats and multiplies speed of unit.<br />
:Helm - affects melee resistances and magical potence of unit.<br />
<br />
Each item have it's own stats.<br />
<br />
;Spell system:<br />
:Each class have some predefined spells. ''In most cases they are not simple "damage unit X for Y hp". That's why they are the greatest headache for me.''<br />
:Each unit can use it's spell once per turn.<br />
:There are no limit of uses through whole scenario.<br />
<br />
Each item has it own's id. This ID is the key to macro what will apply effect of item stats to unit structure. Data about it will be stored inside WesMMO era. That allows me to implement 'inventory slots'. Players will carry unused items in them.<br />
<br />
<br />
<br />
Ideas:<br />
#situation: players A,B,C,D starts the game. player B leaves game before it ends. spectator E (player A) takes control of units B. players A,E,C,D ends the game and information about their units is stored to persistent. player E gets units of player B.<br />
#suggestion: Best items should kill much time before player get them, but players should get something each time they play this game. Ways to reach this objective:<br />
#*1) Add "random stats" to items. Then item drops, RNG choose stats on them between predefined sets. 1/4 of randem stat set (RaSS) should be awesome and 1/4 should be real crap.<br />
#*2) Add "crafted items". Players should collect some resourses and get to place where they can craft this item.<br />
#Itemisation(1). WesMMO will be published by patches. In each patch I will add some new items and functions to players. Items added in new patch should be better than items added in previous patch. But difference should not be enormous.<br />
#levelling(1). I would not change standart mechanic of XP colection of BfW. Each player have 3 unit, what allows them to prapare and perform last-hit for any unit. Levelling shouldn't make items of this patch worster.<br />
#Levelling(2). Data, stored in unit.class[], should contain multipliers of stats. Later this will be used to recalculate stats of unit.<br />
#Itemisation(2). There are three items: A(require 1-3 of X), B(require 2-5 of X), C(require 4-8 of X). While player have 3 X, he can't share A and B to others if he get them and can not use C. But when he collect 4 X, he can share A, can't share B and can use C.<br />
#Crafted items++. If craft of new items will require resourses from old patch, old maps will become outdated only if I will want this.<br />
#Itemisation(3). Items should have requirments by level.<br />
#Levelling(3). There should be a level cap in each patch.<br />
#Itemisation(4). Items can have no requirements by level, but stats on item can be influensed by level.<br />
#Itemisation(5). Add "mantle". It will have +int, +stam and magical resistances. Body no longer affect magical resistences and stam.<br />
#Development(1). Add various "count" functions to collect statistical data about each option in dialogs. This data should be stored in special namespace. Then this will be done, I should add to feedback thread request to put file with this data to the forum.<br />
#UI(1). Frankensteining. Each equipped item will have it's own overlay on unit. During the fights overlays aren't shown. Thats why I should create attack and defend animations what will look like cloud with "Ouch" messages jumped out of it.<br />
#UI(2). Fast backpack browser<br />
+-----------------------------+<br />
| Backpack browser<br />
| +-------------------------+ |<br />
| | Back<br />
| +-------------------------+ |<br />
| +-------------------------+ |<br />
| | Next 10(5?)<br />
| +-------------------------+ |<br />
| +-------------------------+ |<br />
| | Previous 10(5?)<br />
| +-------------------------+ |<br />
| +-------------------------+ |<br />
| | item_slot) item_name id | |<br />
| +-------------------------+ |<br />
| +-------------------------+ |<br />
| | 2) Cracked Bow <id><br />
| +-------------------------+ |<br />
+-----------------------------+<br />
<br />
#UI(3). Resourse browser<br />
<br />
===WesMMO. Theorycraft===<br />
;Main questions:<br />
:1) I have some 'slots' of equipped items. Why player should fill all this slots?<br />
:2) I have some 'stats' on items. Why player should concentrate on some stats and ignore other?<br />
:3) There are some 'classes' of characters. How to make real difference between any two classes?<br />
:4) How to make class system where anticlasses will exists.<br />
<br />
;Base statements:<br />
:Player control 3 units.<br />
:Units have around 5 equipment 'slots' and few stats.<br />
:Any damage dealing should be based on stadart battle system.<br />
:There are around 5-10 different classes.<br />
:Each class have at least 2 good, 2 worst and 2 average attack types and defenses.<br />
:Item can not affect 2 good or 2 worst stats for any class at once.<br />
:Bonuses from items should not break class balance.<br />
:Items are not able to affect all stats.<br />
:All characters have same movement cost and base defence at any type of terrain.<br />
:Any character is able to wear any item he gets.<br />
<br />
;Stat system<br />
Handling good/average/worst stats for any class.<br />
Each class will have set of modifiers, what will affect resistances. It can be equal to 1 (good), 2 (average), 4 (worst).<br />
''main formula of effect diminishing'':<br />
y = x / (a * x + 20) * 100%, where<br />
x - value from gear,<br />
a - class modifier.<br />
According to this formula, there are 3 tier of armor exists:<br />
1 tier: gear give 1-20 value (5-50;5-33;5-20)<br />
2 tier: gear give 20-40 value (50-66;33-40;20-22)<br />
3 tier: gear give 40-80 value (66-80;40-45;22-23)<br />
The following stats are good for any class:<br />
:hitpoint amount. ''Even mages with ranged combat should stand face-to-face to it's current opponent. Noone can one-shot any other class with full hp. Thats why mage surely will get some amount of damage from counterattack.<br />
:movepoints amount. ''Difference in 1 point of movement make one unit unreachable by other.<br />
<br />
There are 5 equippable slots:<br />
:1 - affects magical combat<br />
:2 - affects defences<br />
:3 - affects melee combat<br />
:4 - affects ranged combat<br />
:5 - affects movement<br />
<br />
If item affects combat, it always says how many strikes you have and how much damage you will deal with this item. This should also be influenced by class, in some way, to make sure, what character A can not be owerpowered just because enemy have wrong and this class - right weapon.<br />
<br />
How can I make difference for class A between weapon a and b?<br />
:1) Class multiplier. ''Multipliers for damage is not a good idea.<br />
:2) Gear hacking. ''This way is rather hard, but possible.<br />
:3) Weapon blocking. ''Easy as pie.<br />
<br />
Damage and number of strikes completely influenced by weapon. That means, what weapons of same tier, will have same damage output.<br />
:Blade-based melee weapons are fast. Ex: 2-6<br />
:Blow-based melee weapons have average characterictics. 3-4 or 4-3<br />
:Only arcane melee weapon allowed. it's speed and damage is not good itself, but it is not influenced by common physical resistances.<br />
:Pierce weapons are usually ranged and rather fast. 3-4 or 2-6.<br />
:Fire magic is one-shottable. 12-1 and cannot miss, of course.<br />
:Cold magic is a pain. 1-12.<br />
<br />
There are 2 group of stats:<br />
:''Active''<br />
:''Passive''<br />
There are two ''active'' stat: hitpoint and damage, and two ''passive'': dodge chance and absorbition.<br />
And total list of stats will look like this:<br />
+--------------------+---+<br />
| stat |PPL|<br />
+--------------------+---+<br />
| hitpoints |60 |<br />
+-------+------------+---+<br />
| blade | | |<br />
| blow | | |<br />
| pierce|absorbitions| 5 |<br />
| arcane| | |<br />
| fire | | |<br />
| cold | | |<br />
+-------+------------+---+<br />
| blade | | |<br />
| blow | | |<br />
| pierce| power |10 |<br />
| arcane| | |<br />
| fire | | |<br />
| cold | | |<br />
+-------+------------+---+<br />
| avoidance | 4 |<br />
+-------+------------+---+<br />
Absorbitions have limits in 12 levels.<br />
Let's imagine, what absorbition capped at 75% value. According to ''main formula of effect diminishing'', character with a=1 will achieve 75% mitigation at x=60. And 60 / 5 = 12.<br />
<br />
Look to this table:<br />
x value difference value difference value difference<br />
0 0 0 0 <br />
5 16,66666667 16,66666667 12,5 12,5 20 20<br />
10 25 8,333333333 16,66666667 4,166666667 33,33333333 13,33333333<br />
15 30 5 18,75 2,083333333 42,85714286 9,523809524<br />
20 33,33333333 3,333333333 20 1,25 50 7,142857143<br />
25 35,71428571 2,380952381 20,83333333 0,833333333 55,55555556 5,555555556<br />
30 37,5 1,785714286 21,42857143 0,595238095 60 4,444444444<br />
35 38,88888889 1,388888889 21,875 0,446428571 63,63636364 3,636363636<br />
40 40 1,111111111 22,22222222 0,347222222 66,66666667 3,03030303<br />
45 40,90909091 0,909090909 22,5 0,277777778 69,23076923 2,564102564<br />
50 41,66666667 0,757575758 22,72727273 0,227272727 71,42857143 2,197802198<br />
55 42,30769231 0,641025641 22,91666667 0,189393939 73,33333333 1,904761905<br />
60 42,85714286 0,549450549 23,07692308 0,16025641 75 1,666666667<br />
2'nd column shows mitigation value at a = 2, 4'th at a = 4 and 6'th at a = 1. If you calculate average value of all difference columns and turn float value to int, you get 4. This is Avoidance PPL.<br />
There are also ''Soft cap'' and ''hard cap'' of mitigation. Soft cap means what further collecting of this stat is useful, but player can spend training points into something more valuable. Hard cap means what further improvement is not recommended (by me of course).<br />
:for a = 1. SC = 30. HC = 60<br />
:for a = 2. SC = 20. HC = 40.<br />
:for a = 4. SC = 10. HC = 20.<br />
Avoidance should give static value, because it is not depend from character class. And it should be capped too. According to wesnoth phylosophy, defence should not be higner than 60. 60 / 4 = 15 levels of stat.</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=UsefulWMLFragments&diff=59236UsefulWMLFragments2018-03-03T20:07:37Z<p>Cannedfood: /* Item Tools */ added link to orphan page</p>
<hr />
<div>== Useful WML Fragments ==<br />
<br />
Most of the things found here are macros (see [[PreprocessorRef]]) that must be copied into a scenario file or another file included first by the campaign, and then used in the scenario (or multiplayer map). Remember that a macro cannot be used at a point before it is defined.<br />
<br />
Also, when creating or using macros, please remember: Every macro must generate a WML fragment which would be syntactically balanced and correct by itself. Unbalanced macros confuse our maintenance and sanity-checking tools, creating extra work and headaches for the already-overworked WML maintainers.<br />
<br />
'''Note: some of the code here is outdated or otherwise poor. It's not advisable to blindly copy-paste code from here and expect it to work on recent Wesnoth versions or assume that the recent versions don't support a simpler and less hacky way of doing the same thing.'''<br />
<br />
Some things '''not''' to do here:<br />
* Don't add macros that duplicate things in [http://www.wesnoth.org/macro-reference.xhtml the core macro library].<br />
* Don't add macros that are trivial syntax shortcuts.<br />
* Don't add macros that generate unbalanced syntax fragments.<br />
<br />
Try to avoid adding pages here. It is better to find a category in which your code fits and add it to that page.<br />
<br />
=== Logic Structure Macros ===<br />
*[[WML Utilities]]: Macros to assist other macros. Overlay with Filter. Determine Opposite Coordinates. Find nearest hex(es)<br />
<br />
=== Campaign Tools ===<br />
*[[AlternateToDWML]]: Macros for alternate time-of-day schemes, including per-hour time-of-day.<br />
<br />
==== RPG Tools ====<br />
*[[A Shop Like Thing]]: How to add even more RPG elements to your scenarios.<br />
*[[CutsceneWML]]: Fixed MOVE_TO event (uses FIND_NEARBY from [[WML Utilities]]), move + exit to recall list, define character dialogue and a "main character", grant unlimited moves.*<br />
*[[An effect that changes icons]]: Wanted to change some attack's icon when the unit took an object, but there was no set_icon variable accepted? This enables it!<br />
<br />
==== Music Tools ====<br />
*[[WML Musical Moods]]: Groups the Wesnoth music (as of 1.7.x) into "moods" and defines macros for playing randomly songs from these pools and for quickly switching music.<br />
<br />
==== Unit Tools ====<br />
*[[WML Abilities]]: Knockback. Charm. Bloodlust.<br />
<br />
==== Item Tools ====<br />
*[[Removing Items]]: A macro that removes objects from a unit.<br />
*[[DroppableItem]]: For placing items on the terrain upon death of a unit.<br />
<br />
==== Map Tools ====<br />
*[[FloodWML]]: Macros to create a flood of a certain terrain type spreading across the map.<br />
<br />
=== Advanced WML ===<br />
*[[Advanced WML]]: Store Reachable Locations.<br />
*[[Advanced Optimisations and Hacks]]: If you're coding something really complex, this might come handy<br />
<br />
=== Templates ===<br />
*[[WML Templates]]: Generic campaign, scenario and unit templates. <b>Obsolete; most of these won't work right.</b><br />
<br />
== See Also ==<br />
<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: UsefulWMLFragments|*]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=PblWML&diff=59137PblWML2018-01-21T15:44:21Z<p>Cannedfood: formatted text, several changes to word choice, improved description of the version value</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 />
: {{DevFeature1.13|0}} Description can be enriched with "pango" markup. Older wesnoth versions or descriptions with syntax errors will be rendered as plain text.<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>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=Talk:StandardUnitFilter&diff=59061Talk:StandardUnitFilter2017-12-13T02:55:49Z<p>Cannedfood: /* Sequence of filtering */ added small tidbit</p>
<hr />
<div>=== Sequence of filtering ===<br />
<br />
The first paragraph says:<br />
: first it applies to all units on the field, based on their coordinates. Next it applies to units in the recall list.<br />
I have not yet inspected the code or anything, so I don't know whether this it correct or accurate. <br/><br />
I do know, however, that it is only relevant if something can occur internally which would prevent it from comparing against the Recall space — and other than use of x= or y= or search_recall_list= to do so. I.e. if it always checked the map but only also checked the Recall if it didn't make any matches on the map. Otherwise, you might as well say what situations there are for which either space — Map or Recall — are unavailable. [[User:Cannedfood|Cannedfood]] ([[User talk:Cannedfood|talk]]) 02:52, 13 December 2017 (UTC)</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=Talk:StandardUnitFilter&diff=59060Talk:StandardUnitFilter2017-12-13T02:52:19Z<p>Cannedfood: /* Sequence of filtering */ discussion begun</p>
<hr />
<div>=== Sequence of filtering ===<br />
<br />
The first paragraph says:<br />
: first it applies to all units on the field, based on their coordinates. Next it applies to units in the recall list.<br />
I have not yet inspected the code or anything, so I don't know whether this it correct or accurate. <br/><br />
I do know, however, that it is only relevant if something can occur internally which would prevent it from comparing against the Recall space — and other than use of x= or y= to do so. I.e. if it always checked the map but only also checked the Recall if it didn't make any matches on the map. Otherwise, you might as well say what situations there are for which either space — Map or Recall — are unavailable. [[User:Cannedfood|Cannedfood]] ([[User talk:Cannedfood|talk]]) 02:52, 13 December 2017 (UTC)</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=SyntaxWML&diff=59059SyntaxWML2017-12-11T19:25:35Z<p>Cannedfood: /* Special Attribute Values */ reverted my previous edit but kept a link to TranslationsWML</p>
<hr />
<div>{{Translations}}<br />
{{WML Tags}}<br />
<br />
The '''Wesnoth Markup Language''' ('''WML''') is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML.<br />
For guidelines on keeping these files easily human-readable, see [[ConventionsWML#Indentation|ConventionsWML]].<br />
<br />
== Tag and Attribute Structures ==<br />
<br />
WML has a syntax containing two basic elements: ''tags'' and ''attributes''. Furthermore, ''attributes'' consist of ''keys'' and ''values''. For example:<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key=value<br />
[/tag]<br />
</syntaxhighlight><br />
<br />
''Tags'' are used to partition information, while the data is contained in the ''attributes''. ''Keys'' identify the type of data to be stored and ''values'' are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each <code>key=value</code> line within a tag, the attribute identified by <code>key</code> has its data set to <code>value</code>.<br />
Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.<br />
<syntaxhighlight lang="wml"><br />
[parent_tag]<br />
key1=value1<br />
[child_tag]<br />
key2=value2<br />
[/child_tag]<br />
[/parent_tag]<br />
</syntaxhighlight><br />
<br />
Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "[[ReferenceWML#WML_toplevel_tags|top-level tags]]" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored.<br />
<br />
''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.<br />
<br />
Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they will not contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed.<br />
<br />
<br />
=== Tag Amendment Syntax ===<br />
<br />
Inserting a plus sign (<code>+</code>) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key=value<br />
[/tag]<br />
[+tag]<br />
key=value<br />
[/tag]<br />
</syntaxhighlight><br />
<br />
* All keys in the ''+tag'' will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].<br />
<br />
* Any child tags of the ''+tag'' will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."<br />
<br />
* It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.<br />
<br />
=== Multiple Assignment Syntax ===<br />
<br />
It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key1,key2,key3=value1,value2,value3<br />
[/tag]<br />
</syntaxhighlight><br />
would be the same as:<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key1=value1<br />
key2=value2<br />
key3=value3<br />
[/tag]<br />
</syntaxhighlight><br />
* If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.<br />
<br />
=== Special Attribute Values ===<br />
<br />
Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.<br />
* '''key = "value"''': a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break inside quotes does not end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped. It is never wrong to use quotes with correct WML.<br />
* '''key = _"value"''': a ''[[translatable]] value'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data. See to [[TranslationsWML]] for more information.<br />
* '''key = "value1" + "value2"''': ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left. To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes.<br />
* '''key = "quoted ""double quoted value"" value"''': ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)<br />
* '''key = $variable''': a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].<br />
* '''key = "$(formula-expression)"''': a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''<br />
* '''key = <<value>>''': similar to a quoted value but stronger: the value is hidden from the [[PreprocessorRef|preprocessor]], which will see all text therein as literal. Useful with [[LuaWML]] or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string.<br />
<br />
== Variables ==<br />
<br />
Variables in WML are used to store data for later retrieval. Each variable is identified by its name, which may contain only alphanumerics and underscores. Once created, a variable persists until the end of a campaign unless explicitly cleared.<br />
<br />
The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.<br />
* '''Assigning to a variable''': stores a value in the variable. This is done with tags like {{tag|InternalActionsWML|set_variable}} or with [[PreprocessorRef|macros]] like <tt>{VARIABLE}</tt>.<br />
* '''Querying a variable''': returns the last value stored in the variable (or the empty string, if no value was). This is done by prefixing the variable name with a dollar sign, as in <tt>$variable</tt>, and sometimes ending the variable name with a pipe character, as in <tt>$variable|</tt>.<br />
* '''Clearing a variable''': makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games. This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].<br />
<br />
=== Kinds of Variables ===<br />
==== Scalar ====<br />
A scalar variable can store a single string or number.<br />
<br />
<syntaxhighlight lang="wml"><br />
[set_variable]<br />
name=my_variable<br />
value="sample value"<br />
[/set_variable]<br />
</syntaxhighlight><br />
<br />
The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).<br />
<br />
==== Array ====<br />
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:<br />
<syntaxhighlight lang="wml"><br />
[set_variable]<br />
name=my_awesome_array[0].x<br />
value=10<br />
[/set_variable]<br />
[set_variable]<br />
name=my_awesome_array[1].x<br />
value=12<br />
[/set_variable]<br />
[set_variable]<br />
name=my_awesome_array[2].x<br />
value=14<br />
[/set_variable]<br />
</syntaxhighlight><br />
<br />
However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:<br />
<syntaxhighlight lang="wml"><br />
[set_variables]<br />
name=my_awesome_array<br />
[value]<br />
x=10<br />
[/value]<br />
[value]<br />
x=12<br />
[/value]<br />
[value]<br />
x=14<br />
[/value]<br />
[/set_variables]<br />
</syntaxhighlight><br />
<br />
If <tt>foo</tt> is the name of an array, <tt>foo[0]</tt> is the full name of its first container variable, <tt>foo[1]</tt> the full name of its second, and so on. <tt>foo.length</tt> is the special variable that always stores the number of containers in the array <tt>foo</tt>. Hence, if the value stored in <tt>foo.length</tt> is 18, the last container in the array would be <tt>foo[17]</tt>. If you try to query an array as if it were a container, then it will simply use the first index[0]. Thus $foo.bar would be the same as $foo[0].bar<br />
<br />
''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <tt>foo[3]</tt> as if it were a scalar one is illegal; instead, you would use <tt>foo[3].value</tt> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a text save of a game that contains such variables will fail with a WML error.)<br />
<br />
==== Container ====<br />
A container variable can store any number of scalar and/or array variables. There are tags to assign specific information, for instance [store_side]. To refer to a variable <tt>bar</tt> stored in a container <tt>foo</tt> you would write <tt>foo.bar</tt>. An explicit index inside an array is also considered a container.<br />
<br />
=== Conditionals ===<br />
Variables may be compared by using [variable] within an [if] or [while] tag. For more information, please refer to [[ConditionalActionsWML]].<br />
<br />
=== Variable Substitution ===<br />
Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:<br />
<syntaxhighlight lang="wml"><br />
[event]<br />
name=turn 1<br />
[set_variable]<br />
name=my_variable<br />
value= _ "Konrad"<br />
[/set_variable]<br />
[message]<br />
speaker=Delfador<br />
message= _ "Hello, $my_variable|... How are you?"<br />
[/message]<br />
[/event]<br />
</syntaxhighlight><br />
<br />
The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.<br />
<br />
When writing scenario events ([[EventWML]]), a scalar variable can generally be substituted into the right-hand of any '''key=value''' assignment. If the provided value contains a <tt>$</tt>, the WML engine with interpret what is between the rightmost <tt>$</tt> and the next <tt>|</tt> as a full variable name to be queried, and replace <tt>$''variable''|</tt> with the result of this query.<br />
<br />
In certain situations, the <tt>|</tt> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no |, variable names span letters, digits, underlines, balanced square brackets and some periods. Doubled periods and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using $|), then it will be replaced by just $, giving you an easy way to include a dollar sign in an interpolated string.<br />
<br />
{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, you can use the syntax <tt>$varname?default text|</tt>. In this case, the <tt>|</tt> is required.<br />
<br />
==== Literal Mode ====<br />
<br />
There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:<br />
* value of '''literal=''' inside [set_variable]<br />
* contents of '''[literal]''' inside [set_variables]<br />
* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start<br />
<br />
=== Automatically Stored Variables ===<br />
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)<br />
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)<br />
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered<br />
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered<br />
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event<br />
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event<br />
* '''unit''': inside an event, this is the unit at $x1,$y1<br />
* '''second_unit''': inside an event, this is the unit at $x2,$y2<br />
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match<br />
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match<br />
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted<br />
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].<br />
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].<br />
<br />
Note: Automatically stored container and array variables are only stored once that one of their attributes is accessed for the first time. This means that one can sometimes get wrong results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.<br />
<br />
=== The [variables] tag ===<br />
<br />
The [variables] tag is used in saved games to describe the current value of each variable, and in scenario files for assigning initial values to variables at scenario start.<br />
<br />
A scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.<br />
<br />
A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.<br />
<br />
An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...<br />
<br />
=== Storing variables inside units ===<br />
<br />
Sometimes it is useful to store a custom WML variable inside a unit. Units stored with the [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]] command have a '''unit.variables''' sub-container where custom variables related to that unit may be saved. (Remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.) One benefit of this approach is that the unit may then be [[FilterWML|filtered]] based on the value, for example:<br />
<syntaxhighlight lang="wml"><br />
[filter]<br />
[filter_wml]<br />
[variables]<br />
my_variable="test"<br />
[/variables]<br />
[/filter_wml]<br />
[/filter]<br />
</syntaxhighlight><br />
<br />
=== Variable Usage Examples ===<br />
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)<br />
<syntaxhighlight lang="wml"><br />
[variables]<br />
attitude_of_elves=hate<br />
attitude_of_dwarves=love<br />
attitude_of_humans=like<br />
current_opponent=elves<br />
[/variables]<br />
</syntaxhighlight><br />
<br />
Then,<br />
<syntaxhighlight lang="wml"><br />
[message]<br />
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"<br />
[/message]<br />
</syntaxhighlight><br />
displays the message<br />
Oh, I see elves! They surely hate us!<br />
<br />
Consider another game with variables<br />
<syntaxhighlight lang="wml"><br />
[variables]<br />
our_side=1<br />
their_side=2<br />
[/variables]<br />
</syntaxhighlight><br />
where side 1 has 75 gold, and side 2 50 gold. Then, <br />
<syntaxhighlight lang="wml"><br />
[store_side]<br />
side=$our_side<br />
variable=we<br />
[/store_side]<br />
[store_side]<br />
side=$their_side<br />
variable=they<br />
[/store_side]<br />
[message]<br />
message=We have $we.gold gold, they have $they.gold gold.<br />
[/message]<br />
[if]<br />
[variable]<br />
name=we.gold<br />
greater_than=$they.gold<br />
[/variable]<br />
[then]<br />
[message]<br />
message=This should be easy!<br />
[/message]<br />
[/then]<br />
[else]<br />
[message]<br />
message=This will not be easy!<br />
[/message]<br />
[/else]<br />
[/if]<br />
[clear_variable]<br />
name=we<br />
[/clear_variable]<br />
[clear_variable]<br />
name=they<br />
[/clear_variable]<br />
</syntaxhighlight><br />
displays the messages<br />
We have 75 gold, they have 50 gold.<br />
This should be easy!<br />
If side 2 had 100 gold instead, the same code would display the messages<br />
We have 75 gold, they have 100 gold.<br />
This will not be easy!<br />
<br />
The code<br />
<syntaxhighlight lang="wml"><br />
[store_unit]<br />
[filter]<br />
canrecruit=yes<br />
side=1<br />
[/filter]<br />
variable=leader<br />
[/store_unit]<br />
[message]<br />
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.<br />
[/message]<br />
[clear_variable]<br />
name=leader<br />
[/clear_variable]<br />
</syntaxhighlight><br />
always displays a true sentence.<br />
<br />
You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.<br />
<br />
== Comments ==<br />
<br />
Comments are indicated by starting a line with a pound sign (<code>#</code>). Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine.<br />
<br />
It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.<br />
<br />
== Tutorial ==<br />
<br />
* [[VariablesWML/How_to_use_variables|How to use variables]]<br />
<br />
== See Also ==<br />
<br />
* [[PreprocessorRef]]<br />
* [[ConventionsWML]]<br />
* [[SavefileWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=SyntaxWML&diff=59058SyntaxWML2017-12-11T19:14:49Z<p>Cannedfood: /* Special Attribute Values */ added circumflex as particular type of value</p>
<hr />
<div>{{Translations}}<br />
{{WML Tags}}<br />
<br />
The '''Wesnoth Markup Language''' ('''WML''') is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML.<br />
For guidelines on keeping these files easily human-readable, see [[ConventionsWML#Indentation|ConventionsWML]].<br />
<br />
== Tag and Attribute Structures ==<br />
<br />
WML has a syntax containing two basic elements: ''tags'' and ''attributes''. Furthermore, ''attributes'' consist of ''keys'' and ''values''. For example:<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key=value<br />
[/tag]<br />
</syntaxhighlight><br />
<br />
''Tags'' are used to partition information, while the data is contained in the ''attributes''. ''Keys'' identify the type of data to be stored and ''values'' are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each <code>key=value</code> line within a tag, the attribute identified by <code>key</code> has its data set to <code>value</code>.<br />
Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.<br />
<syntaxhighlight lang="wml"><br />
[parent_tag]<br />
key1=value1<br />
[child_tag]<br />
key2=value2<br />
[/child_tag]<br />
[/parent_tag]<br />
</syntaxhighlight><br />
<br />
Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "[[ReferenceWML#WML_toplevel_tags|top-level tags]]" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored.<br />
<br />
''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.<br />
<br />
Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they will not contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed.<br />
<br />
<br />
=== Tag Amendment Syntax ===<br />
<br />
Inserting a plus sign (<code>+</code>) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key=value<br />
[/tag]<br />
[+tag]<br />
key=value<br />
[/tag]<br />
</syntaxhighlight><br />
<br />
* All keys in the ''+tag'' will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].<br />
<br />
* Any child tags of the ''+tag'' will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."<br />
<br />
* It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.<br />
<br />
=== Multiple Assignment Syntax ===<br />
<br />
It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key1,key2,key3=value1,value2,value3<br />
[/tag]<br />
</syntaxhighlight><br />
would be the same as:<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key1=value1<br />
key2=value2<br />
key3=value3<br />
[/tag]<br />
</syntaxhighlight><br />
* If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.<br />
<br />
=== Special Attribute Values ===<br />
<br />
Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.<br />
* '''key = "value"''': a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break inside quotes does not end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped. It is never wrong to use quotes with correct WML.<br />
* '''key = _"value"''': a ''[[translatable|translatable value]]'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data.<br />
* '''key = _"info^value"''': keys which function as [[translatable]] text allow for the use of the circumflex to cause the circumflex and any text preceeding it to be ignored when the key's value is displayed in the Wesnoth GUI. See to [[TranslationsWML]].<br />
* '''key = "value1" + "value2"''': ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left. To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes.<br />
* '''key = "quoted ""double quoted value"" value"''': ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)<br />
* '''key = $variable''': a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].<br />
* '''key = "$(formula-expression)"''': a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''<br />
* '''key = <<value>>''': similar to a quoted value but stronger: the value is hidden from the [[PreprocessorRef|preprocessor]], which will see all text therein as literal. Useful with [[LuaWML]] or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string.<br />
<br />
== Variables ==<br />
<br />
Variables in WML are used to store data for later retrieval. Each variable is identified by its name, which may contain only alphanumerics and underscores. Once created, a variable persists until the end of a campaign unless explicitly cleared.<br />
<br />
The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.<br />
* '''Assigning to a variable''': stores a value in the variable. This is done with tags like {{tag|InternalActionsWML|set_variable}} or with [[PreprocessorRef|macros]] like <tt>{VARIABLE}</tt>.<br />
* '''Querying a variable''': returns the last value stored in the variable (or the empty string, if no value was). This is done by prefixing the variable name with a dollar sign, as in <tt>$variable</tt>, and sometimes ending the variable name with a pipe character, as in <tt>$variable|</tt>.<br />
* '''Clearing a variable''': makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games. This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].<br />
<br />
=== Kinds of Variables ===<br />
==== Scalar ====<br />
A scalar variable can store a single string or number.<br />
<br />
<syntaxhighlight lang="wml"><br />
[set_variable]<br />
name=my_variable<br />
value="sample value"<br />
[/set_variable]<br />
</syntaxhighlight><br />
<br />
The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).<br />
<br />
==== Array ====<br />
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:<br />
<syntaxhighlight lang="wml"><br />
[set_variable]<br />
name=my_awesome_array[0].x<br />
value=10<br />
[/set_variable]<br />
[set_variable]<br />
name=my_awesome_array[1].x<br />
value=12<br />
[/set_variable]<br />
[set_variable]<br />
name=my_awesome_array[2].x<br />
value=14<br />
[/set_variable]<br />
</syntaxhighlight><br />
<br />
However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:<br />
<syntaxhighlight lang="wml"><br />
[set_variables]<br />
name=my_awesome_array<br />
[value]<br />
x=10<br />
[/value]<br />
[value]<br />
x=12<br />
[/value]<br />
[value]<br />
x=14<br />
[/value]<br />
[/set_variables]<br />
</syntaxhighlight><br />
<br />
If <tt>foo</tt> is the name of an array, <tt>foo[0]</tt> is the full name of its first container variable, <tt>foo[1]</tt> the full name of its second, and so on. <tt>foo.length</tt> is the special variable that always stores the number of containers in the array <tt>foo</tt>. Hence, if the value stored in <tt>foo.length</tt> is 18, the last container in the array would be <tt>foo[17]</tt>. If you try to query an array as if it were a container, then it will simply use the first index[0]. Thus $foo.bar would be the same as $foo[0].bar<br />
<br />
''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <tt>foo[3]</tt> as if it were a scalar one is illegal; instead, you would use <tt>foo[3].value</tt> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a text save of a game that contains such variables will fail with a WML error.)<br />
<br />
==== Container ====<br />
A container variable can store any number of scalar and/or array variables. There are tags to assign specific information, for instance [store_side]. To refer to a variable <tt>bar</tt> stored in a container <tt>foo</tt> you would write <tt>foo.bar</tt>. An explicit index inside an array is also considered a container.<br />
<br />
=== Conditionals ===<br />
Variables may be compared by using [variable] within an [if] or [while] tag. For more information, please refer to [[ConditionalActionsWML]].<br />
<br />
=== Variable Substitution ===<br />
Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:<br />
<syntaxhighlight lang="wml"><br />
[event]<br />
name=turn 1<br />
[set_variable]<br />
name=my_variable<br />
value= _ "Konrad"<br />
[/set_variable]<br />
[message]<br />
speaker=Delfador<br />
message= _ "Hello, $my_variable|... How are you?"<br />
[/message]<br />
[/event]<br />
</syntaxhighlight><br />
<br />
The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.<br />
<br />
When writing scenario events ([[EventWML]]), a scalar variable can generally be substituted into the right-hand of any '''key=value''' assignment. If the provided value contains a <tt>$</tt>, the WML engine with interpret what is between the rightmost <tt>$</tt> and the next <tt>|</tt> as a full variable name to be queried, and replace <tt>$''variable''|</tt> with the result of this query.<br />
<br />
In certain situations, the <tt>|</tt> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no |, variable names span letters, digits, underlines, balanced square brackets and some periods. Doubled periods and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using $|), then it will be replaced by just $, giving you an easy way to include a dollar sign in an interpolated string.<br />
<br />
{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, you can use the syntax <tt>$varname?default text|</tt>. In this case, the <tt>|</tt> is required.<br />
<br />
==== Literal Mode ====<br />
<br />
There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:<br />
* value of '''literal=''' inside [set_variable]<br />
* contents of '''[literal]''' inside [set_variables]<br />
* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start<br />
<br />
=== Automatically Stored Variables ===<br />
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)<br />
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)<br />
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered<br />
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered<br />
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event<br />
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event<br />
* '''unit''': inside an event, this is the unit at $x1,$y1<br />
* '''second_unit''': inside an event, this is the unit at $x2,$y2<br />
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match<br />
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match<br />
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted<br />
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].<br />
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].<br />
<br />
Note: Automatically stored container and array variables are only stored once that one of their attributes is accessed for the first time. This means that one can sometimes get wrong results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.<br />
<br />
=== The [variables] tag ===<br />
<br />
The [variables] tag is used in saved games to describe the current value of each variable, and in scenario files for assigning initial values to variables at scenario start.<br />
<br />
A scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.<br />
<br />
A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.<br />
<br />
An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...<br />
<br />
=== Storing variables inside units ===<br />
<br />
Sometimes it is useful to store a custom WML variable inside a unit. Units stored with the [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]] command have a '''unit.variables''' sub-container where custom variables related to that unit may be saved. (Remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.) One benefit of this approach is that the unit may then be [[FilterWML|filtered]] based on the value, for example:<br />
<syntaxhighlight lang="wml"><br />
[filter]<br />
[filter_wml]<br />
[variables]<br />
my_variable="test"<br />
[/variables]<br />
[/filter_wml]<br />
[/filter]<br />
</syntaxhighlight><br />
<br />
=== Variable Usage Examples ===<br />
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)<br />
<syntaxhighlight lang="wml"><br />
[variables]<br />
attitude_of_elves=hate<br />
attitude_of_dwarves=love<br />
attitude_of_humans=like<br />
current_opponent=elves<br />
[/variables]<br />
</syntaxhighlight><br />
<br />
Then,<br />
<syntaxhighlight lang="wml"><br />
[message]<br />
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"<br />
[/message]<br />
</syntaxhighlight><br />
displays the message<br />
Oh, I see elves! They surely hate us!<br />
<br />
Consider another game with variables<br />
<syntaxhighlight lang="wml"><br />
[variables]<br />
our_side=1<br />
their_side=2<br />
[/variables]<br />
</syntaxhighlight><br />
where side 1 has 75 gold, and side 2 50 gold. Then, <br />
<syntaxhighlight lang="wml"><br />
[store_side]<br />
side=$our_side<br />
variable=we<br />
[/store_side]<br />
[store_side]<br />
side=$their_side<br />
variable=they<br />
[/store_side]<br />
[message]<br />
message=We have $we.gold gold, they have $they.gold gold.<br />
[/message]<br />
[if]<br />
[variable]<br />
name=we.gold<br />
greater_than=$they.gold<br />
[/variable]<br />
[then]<br />
[message]<br />
message=This should be easy!<br />
[/message]<br />
[/then]<br />
[else]<br />
[message]<br />
message=This will not be easy!<br />
[/message]<br />
[/else]<br />
[/if]<br />
[clear_variable]<br />
name=we<br />
[/clear_variable]<br />
[clear_variable]<br />
name=they<br />
[/clear_variable]<br />
</syntaxhighlight><br />
displays the messages<br />
We have 75 gold, they have 50 gold.<br />
This should be easy!<br />
If side 2 had 100 gold instead, the same code would display the messages<br />
We have 75 gold, they have 100 gold.<br />
This will not be easy!<br />
<br />
The code<br />
<syntaxhighlight lang="wml"><br />
[store_unit]<br />
[filter]<br />
canrecruit=yes<br />
side=1<br />
[/filter]<br />
variable=leader<br />
[/store_unit]<br />
[message]<br />
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.<br />
[/message]<br />
[clear_variable]<br />
name=leader<br />
[/clear_variable]<br />
</syntaxhighlight><br />
always displays a true sentence.<br />
<br />
You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.<br />
<br />
== Comments ==<br />
<br />
Comments are indicated by starting a line with a pound sign (<code>#</code>). Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine.<br />
<br />
It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.<br />
<br />
== Tutorial ==<br />
<br />
* [[VariablesWML/How_to_use_variables|How to use variables]]<br />
<br />
== See Also ==<br />
<br />
* [[PreprocessorRef]]<br />
* [[ConventionsWML]]<br />
* [[SavefileWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=TranslationsWML&diff=59057TranslationsWML2017-12-11T19:13:22Z<p>Cannedfood: restructure headings ; added information concerning the circumflex</p>
<hr />
<div>This page describes tags and syntax used for enabling translation in your user made campaign.<br />
<br />
== Components ==<br />
<br />
=== _ "<translatable string>" ===<br />
<br />
Any string that you want to be [[translatable]] needs to be prefixed with an underscore, US-ASCII 0x5F. It will usually also be enclosed in quote marks.<br />
Example:<br />
[message]<br />
speaker=narrator<br />
message= _ "This string is going to be translated."<br />
[/message]<br />
<br />
=== #textdomain <textdomain> ===<br />
<br />
This comment tells Wesnoth to use a certain textdomain. Affects the tag that it has been placed in and all children until another #textdomain is found. A textdomain is a set of translations(you can create your own one for your campaign).<br />
Example:<br />
#textdomain wesnoth-trow<br />
[event]<br />
#textdomain wesnoth-httt<br />
[message]<br />
message= _ "heir to the throne message" #this will be translated using the HttT textdomain<br />
[/message]<br />
[message]<br />
message= _ "heir to the throne message two" #same as above<br />
[/message]<br />
<br />
#textdomain wesnoth-utbs<br />
[message]<br />
message= _ "under the burning suns message" #UtbS textdomain<br />
[/message]<br />
[/event]<br />
<br />
[event]<br />
[message]<br />
message= _ "the rise of wesnoth message" #TroW textdomain<br />
[/message]<br />
[/event]<br />
<br />
Note: The [scenario] tag isn't a child of [campaign], so you will have to specify a textdomain for both, your campaign and each of your scenarios.<br />
<br />
=== the [textdomain] tag ===<br />
<br />
This tag, which has to be placed at the same level as [campaign], is used to specify a path for your own textdomain.<br />
<br />
Example:<br />
[textdomain]<br />
name="wesnoth-Liberty"<br />
path="data/campaigns/Liberty/translations"<br />
[/textdomain]<br />
<br />
== Functional Characteristics ==<br />
<br />
=== Hidden Text ===<br />
<br />
Presence of the circumflex (''^''), US-ASCII 0x5E, in any text string which is translatable — i.e. processed by the functions of src/tstring.cpp — causes the circumflex and any text preceeding it to be ignored; any such text is therefore not shown in the GUI. This can be used to provide translators with informative messages because, of course, such text is retained in the original value.<br />
<br />
Examples of this are seen throughout the mainline assets. Most often, it is used when a name is purposed for an object of certain gender and when that gender is not obvious by the text of the name itself. <br /><br />
Used in a '''[side]''' key:<br />
user_team_name= _ "teamname^Southeast"<br />
Used in a '''[race]''' key:<br />
female_name= _ "race+female^Bat"<br />
<br />
== See Also ==<br />
<br />
* [[SyntaxWML]]<br />
<br />
[[Category:WML Reference]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=InterfaceActionsWML&diff=59055InterfaceActionsWML2017-12-10T16:10:34Z<p>Cannedfood: /* [set_menu_item] */ corrected typographical errors</p>
<hr />
<div>{{WML Tags}}<br />
== Interface actions ==<br />
<br />
Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;<br />
instead, they show something to the player. The main interface tags<br />
are '''[message]''' and '''[objectives]''', but several other tags affect<br />
the interface also.<br />
<br />
== [inspect] ==<br />
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.<br />
<br />
* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.<br />
<br />
== [message] ==<br />
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.<br />
<br />
The following key/tags are accepted for [message]:<br />
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed).<br>'''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.<br />
<br />
* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:<br />
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image<br />
** '''unit''': the primary unit for the event is speaking<br />
** '''second_unit''': {{DevFeature1.13|6}} the secondary unit for the event is speaking<br />
<br />
* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')<br />
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.<br />
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).<br />
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])<br />
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will <b>not</b> work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.<br />
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side. <br />
** {{DevFeature1.13|0}} <b>none:</b> display no image<br />
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.<br />
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.<br />
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.<br />
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above<br />
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.<br />
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.<br />
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.<br />
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.<br />
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.<br />
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''<br />
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]]) {{DevFeature1.13|2}} This is now a synonym for '''label='''.<br />
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].<br />
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])<br />
** '''[command]''': an element containing actions which are executed if the option is selected.<br />
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''<br />
** '''variable''': the variable that the user's input will be written to<br />
** '''label''': a text label to the left of the input field<br />
** '''max_length''': the maximum number of characters that may be typed into the field<br />
** '''text''': text that is written into the field in the beginning<br />
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.<br />
<br />
=== Formatting ===<br />
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [http://developer.gnome.org/pango/unstable/PangoMarkupFormat.html Pango markup formatting codes].<br />
<br />
Remember to use single quotes (') instead of double quotes (") within the formatting string, as double quotes cannot be escaped, and the string will appear fragmented and possibly cause errors.<br />
<br />
For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:<br />
<br />
<nowiki><span color='#BCB088' size='large' font-style='italic'>You are victorious!</span></nowiki><br />
<br />
<br />
These are the codes taken from the Pango markup formatting guide:<br />
<br />
*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".<br />
*'''font_family''', '''face''': A font family name.<br />
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.<br />
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.<br />
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.<br />
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.<br />
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.<br />
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.<br />
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.<br />
*'''strikethrough''': 'true' or 'false' whether to strike through the text.<br />
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'<br />
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.<br />
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.<br />
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.<br />
*'''gravity_hint''': One of 'natural', 'strong', 'line'.<br />
<br />
The following pango attributes are also available directly as attributes of the '''[message]''' tag:<br />
{{DevFeature1.13|4}}<br />
<br />
*'''font'''<br />
*'''font_family'''<br />
*'''font_size'''<br />
*'''font_style'''<br />
*'''font_weight'''<br />
*'''font_variant'''<br />
*'''font_stretch'''<br />
*'''color'''<br />
*'''bgcolor'''<br />
*'''underline'''<br />
*'''underline_color'''<br />
*'''rise'''<br />
*'''strikethrough'''<br />
*'''strikethrough_color'''<br />
*'''fallback'''<br />
*'''letter_spacing'''<br />
*'''gravity'''<br />
*'''gravity_hint'''<br />
<br />
== [objectives] ==<br />
The other tag used for plot development is '''[objectives]'''.<br />
The '''[objectives]''' tag overwrites any previously set objectives,<br />
and displays text which should describe the objectives of the scenario.<br />
Scenario objectives are displayed on the player's first turn after the tag is used,<br />
or as part of the event if it triggers during that player's turn.<br />
Objectives can also be accessed at any time in a scenario using the<br />
"Scenario Objectives" game menu option, making this tag useful for<br />
scenario-specific information that the player may need to refer to during play.<br />
<br />
Attributes of '''[objectives]''':<br />
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.<br />
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.<br />
* '''bullet''': Default '• '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].<br />
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.<br />
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.<br />
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives. Can be set to "" too.<br />
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.<br />
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.<br />
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.<br />
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.<br />
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.<br />
<br />
Tags of '''[objectives]''':<br />
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.<br />
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.<br />
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.<br />
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.<br />
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.<br />
** '''description''': text for the specific win or loss condition.<br />
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.<br />
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'').<br />
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.<br />
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.<br />
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].<br />
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.<br />
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.<br />
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.<br />
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.<br />
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.<br />
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.<br />
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.<br />
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.<br />
** '''bullet''': Default '• ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.<br />
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.<br />
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.<br />
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.<br />
** '''description''': the text of the note.<br />
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.<br />
<br />
== [set_menu_item] ==<br />
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.<br />
<br />
'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.<br />
<br />
* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.<br />
* '''description''': the in-game text that will appear for this item in the menu.<br />
* '''image''': the image to display next to this item.<br />
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].<br />
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS<br />
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp. <br />
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.<br />
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.<br />
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:<br />
** '''key''': a string that contains the key to assign to this.<br />
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.<br />
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.<br />
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.<br />
<br />
== [clear_menu_item] ==<br />
<br />
Removes a menu item from the scenario.<br />
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).<br />
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.<br />
<br />
== Other interface tags ==<br />
<br />
The following tags are also action tags:<br />
<br />
=== [change_theme] ===<br />
<br />
{{DevFeature1.13|8}}<br />
<br />
Change the current interface theme.<br />
<br />
* '''theme''': The ID of the new theme. Use 'theme=' (empty key) to change to the theme that the player has selected in preferences.<br />
<br />
=== [item] ===<br />
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt><br />
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)<br />
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctionWML#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''<br />
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image.<br />
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''<br />
or equivalently (requires Wesnoth 1.11.2+):<br />
''halo=scenery/fire[1~8].png:100''<br />
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.<br />
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.<br />
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.<br />
<br />
=== [remove_item] ===<br />
Removes any graphical items on a given hex.<br />
* [[StandardLocationFilter]]: the hexes to remove items off<br />
* '''image''' if specified, only removes the given image item (This image name must include any [[ImagePathFunctionWML|image path functions]] appended to the original image name.)<br />
<br />
=== [print] ===<br />
Displays a message across the screen. The message will disappear after a certain time.<br />
* '''text''': (translatable) the text to display.<br />
* '''size''': (default=12) the pointsize of the font to use<br />
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.<br />
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. {{DevFeature1.13|x}} Use of red, green, blue is now deprecated; use color=0,0,0 instead.<br />
<br />
=== [move_unit_fake] ===<br />
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.<br />
* '''type''': the type of the unit whose image to use<br />
* '''x''': a comma-separated list of x locations to move along<br />
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)<br />
* '''side''': the side of the fake unit, used for team-coloring the fake unit<br />
* '''gender''': the gender of the fake unit. Example: gender=female<br />
* '''variation''': the variation of the fake unit. Example: variation=undead<br />
* '''image_mods''': [[ImagePathFunctionWML|image path functions]] sequence to be applied on the fake unit.<br />
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.<br />
<br />
=== [move_units_fake] ===<br />
moves multiple images of units along paths on the map. These units are moved in lockstep.<br />
* '''[fake_unit]''': A fake unit to move<br />
** '''type''': the type of unit whose image to use<br />
** '''x''': a comma-separated list of x locations to move along<br />
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)<br />
** '''side''': the side of the fake unit, used for team-coloring the fake unit<br />
** '''skip_steps''': the number of steps to skip before this unit starts moving<br />
=== [hide_unit] ===<br />
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.<br />
* [[StandardUnitFilter]]: All matching units will be hidden<br />
<br />
=== [unhide_unit] ===<br />
Stops the currently hidden units from being hidden.<br />
* [[StandardUnitFilter]]: Only the matching units will be unhidden<br />
<br />
=== [lock_view] ===<br />
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.<br />
<br />
This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.<br />
<br />
{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.<br />
<br />
=== [unlock_view] ===<br />
Unlocks gamemap view scrolling for human players.<br />
<br />
=== [scroll] ===<br />
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.<br />
* '''x''', '''y''': the number of pixels to scroll along the x and y axis<br />
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.<br />
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.<br />
<br />
=== [scroll_to] ===<br />
Scroll to a given hex<br />
* '''x''', '''y''': the hex to scroll to<br />
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.<br />
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.<br />
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').<br />
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').<br />
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.<br />
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.<br />
<br />
=== [scroll_to_unit] ===<br />
Scroll to a given unit<br />
* [[StandardUnitFilter]]<br />
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.<br />
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').<br />
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').<br />
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.<br />
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.<br />
<br />
=== [select_unit] ===<br />
Selects a given unit.<br />
* [[StandardUnitFilter]]: The first unit found will be selected.<br />
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)<br />
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').<br />
<br />
=== [sound]===<br />
Plays a sound<br />
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.<br />
* '''repeat''': repeats the sound for a specified additional number of times (default=0)<br />
<br />
=== [sound_source] ===<br />
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.<br />
* '''id''': a unique identification key of the sound source<br />
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source<br />
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play<br />
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)<br />
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged<br />
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded<br />
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source<br />
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly<br />
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center<br />
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)<br />
<br />
=== [story] ===<br />
{{DevFeature1.13|8}}<br />
<br />
Shows the story screen.<br />
* '''title''': Default title used if a part does not specify one — unlike the intro storyscreen, the scenario name is not used as a default title.<br />
* '''[part]''': As [[IntroWML]].<br />
<br />
=== [remove_sound_source] ===<br />
Removes a previously defined sound source.<br />
* '''id''': the identification key of the sound source to remove<br />
<br />
=== [music]===<br />
Switches to playing different music<br />
* '''name''': the filename of the music to play (in ''music/'' as .ogg)<br />
* see [[MusicListWML]] for the correct syntax<br />
===[volume]===<br />
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100: <br />
* '''music''': Changes the music volume.<br />
* '''sound''': Changes the sound volume.<br />
=== [color_adjust]===<br />
Tints the color of the screen.<br />
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color<br />
=== [delay] ===<br />
Pauses the game.<br />
* '''time''': the time to pause in milliseconds<br />
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.<br />
<br />
=== [redraw] ===<br />
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).<br />
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).<br />
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.<br />
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.<br />
<br />
=== [unit_overlay] ===<br />
Sets an image that will be drawn over a particular unit, and follow it around<br />
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])<br />
* '''image''': the image to place on the unit<br />
<br />
=== [remove_unit_overlay] ===<br />
removes a particular overlayed image from a unit<br />
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])<br />
* '''image''': the image to remove from the unit<br />
<br />
=== [animate_unit] ===<br />
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).<br />
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.<br />
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].<br />
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.<br />
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)<br />
* '''text''': a text to hover during the animation <br />
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above<br />
* '''red''': red value for the text color (0-255)<br />
* '''green''': green value for the text color<br />
* '''blue''': blue value for the text color<br />
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)<br />
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.<br />
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated<br />
<br />
=== [label] ===<br />
Places a label on the map.<br />
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)<br />
* '''text''': what the label should say<br />
* '''team_name''': if specified, the label will only be visible to the given team.<br />
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.<br />
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.<br />
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.<br />
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.<br />
<br />
=== [floating_text]===<br />
Floats text (similar to the damage and healing numbers) on the given locations.<br />
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.<br />
* '''text''': the text to display.<br />
<br />
The default text color is <span style="color: #6b8cff;">'''#6b8cff'''</span>. To change the color, use [[#Formatting|Pango markup]]. For example:<br />
<br />
<pre><br />
# Float some golden yellow text at 20,20.<br />
[floating_text]<br />
x,y=20,20<br />
text="<span color='#cccc33'>" + _ "Your text here" + "</span>"<br />
[/floating_text]<br />
</pre><br />
<br />
=== [deprecated_message] ===<br />
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.<br />
* '''message''': the message to show.<br />
=== [wml_message] ===<br />
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.<br />
* '''message''': the message to show.<br />
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.<br />
<br />
Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.<br />
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).<br />
<br />
=== [test_condition] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.<br />
<br />
* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.<br />
* '''logger''': Same as for [wml_message]. Defaults to "warning".<br />
<br />
=== [open_help] ===<br />
Opens the in-game help.<br />
* '''topic''': the id of the topic to open<br />
=== [show_objectives] ===<br />
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)<br />
* '''side''': the side to show the objectives. If not set, all sides are used.<br />
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.<br />
<br />
=== [chat] ===<br />
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.<br />
* '''speaker''': (default="WML") A string for the name of the sender of the message.<br />
* '''message''': The message that should be displayed.<br />
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.<br />
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.<br />
<br />
=== [zoom] ===<br />
<br />
{{DevFeature1.13|8}}<br />
<br />
Changes the zoom level of the map.<br />
<br />
* '''factor''': The new zoom factor<br />
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.<br />
<br />
== Useful Macros ==<br />
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].<br />
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units<br />
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations<br />
* '''{SET_IMAGE}''' Places an image on the map which has no other function.<br />
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.<br />
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.<br />
<br />
== See Also ==<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=SideWML&diff=59040SideWML2017-12-01T04:27:42Z<p>Cannedfood: /* the [side] tag */ corrected typographical errors; formatted WML names</p>
<hr />
<div>{{WML Tags}}<br />
== the [side] tag ==<br />
<br />
The [side] tag is used to describe a side in a particular scenario.<br />
<br />
The following keys are recognized:<br />
<br />
* '''side''': a number. The leader of this side is placed on the tile represented by this number (see [[BuildingMaps]]). When defining sides, they must be defined in order since the side number is checked against the number of sides seen so far. Currently, the Multiplayer server rejects entering a scenario with more than 9 sides, even if those extra sides are AI sides. {{DevFeature1.13|2}} The server doesn't limit the number of sides anymore.<br />
<br />
* '''controller''' (required): how moves for this side should be inputted.<br />
** '''ai''': the Wesnoth AI makes this side's moves.<br />
** '''human''': a player controls this side's moves.<br />
** '''null''': the side doesn't get a turn to move and doesn't have a leader generated from the contents of the [side] tag. (It still can get units from [unit] tags in the [side] tag.) Events that would usually occur on the side's turn will not take place. This includes healing (ability, villages and rest) and ''side turn'' events.<br />
** '''a number''': gives this side's control to a side with '''side''' matching the number (multiplayer only). {{DevFeature1.13|2}} using a number is deprecated, use previous_save_id= instead.<br />
<br />
* '''no_leader''': if `no' (default), then keys describing a unit which will begin on the side's keep will be the remainder of the '''[side]''' tag, See [[SingleUnitWML]]. Note that if the keys '''x''', '''y''' are included, the leader will begin there regardless of keep location. If this side has a recall list from a previous level, then the recall list will be searched for a leader (using ''canrecruit=yes'') and if one is found it will be used instead of the one described in the '''[side]''' tag. Typical keys used for defining the leader unit are ''type'' (mandatory), ''id'', ''name'' and ''unrenamable=yes'', see [[SingleUnitWML]].<br />
<br />
* '''recruit''': a list of unit types. At the beginning of the scenario, the side gains recruitment of these units.<br />
<br />
* '''gold''': the starting gold for this side. Default: 100. (If gold is carried over from a previous scenario, this value is the minimum starting gold.)<br />
<br />
* '''income''': the base income for this side. Default: 0. This is added to ''base_income'', '''[game_config]''' to determine the side's base income. (see [[GameConfigWML]]).<br />
<br />
* '''hidden''': if `yes', side is not shown in status table.<br />
<br />
* '''fog''': if `yes', this side cannot see any tiles it is not within vision of, except at the start. Please note that the AI currently ignores the fog.<br />
<br />
* '''fog_data''': describes the area which this team has de-fogged, using the same format as shroud_data. (This is not particularly useful when defining a side, though, as the game will recalculate fog as turns begin and end.) It is used in saved games.<br />
<br />
* '''[fog_override]''' With keys x= and y=, this records the hexes that have been cleared (multiturn) with {{tag|DirectActionsWML|lift_fog}}.<br />
<br />
* '''shroud''': if `yes', this side cannot see any tiles it has not moved within sight of. Please note that the AI currently ignores the shroud. NOTE: with shroud=no, this team *ignores* shroud, so it is not possible to modify it using place_shroud and remove_shroud tags. If you want to do so, use "shroud=yes" and place_shroud/remove_shroud tags.<br />
<br />
* '''shroud_data''': describes the area which this team has de-shrouded. An example:<br />
|<br />
|00011111000<br />
:This would leave the first column on the map unaltered and would change the second column for 11 tiles. A '0' means: shrouded, '1' means unshrouded. You can either call an external file using {@filename} (see [[PreprocessorRef]]) or place the data in quotes. For making an external file see [[ShroudDataWML]].<br />
<br />
* '''persistent''': whether the side exists in any other scenarios. If `yes', then ''save_id'' (see below) is used to identify the side in other scenarios. Defaults to `yes' for sides with a human controller, and `no' for ai controlled sides.<br />
<br />
* '''save_id''': defaults to the leader's ''id'' if available, 'Unknown' otherwise. The ID of the side with respect to the previous and next scenarios. Used to carry over the side's recall list (including the side's leader), recruitment list, and starting gold from scenario to scenario. Also used for the side's displayed name in the victory gold-calculation dialog.<br />
<br />
* '''previous_save_id''': {{DevFeature1.13|2}} defaults to ''save_id''. Only used in mp games, specially mp campaigns. This attribute specifies which user should play this side by default. For example if a side has previous_save_id="Konrad" then the side will be assigned to that player who played the side with the save_id="Konrad" in the previous level. If used in the first scenario, multiple sides with the same ''previous_side_id'' will be assigned to the same player.<br />
<br />
* '''team_name''': a non translatable string representing the team's description. Sides with the same team_name are allied. Default ''side''. ''team_name'' is now a comma-separated list of teams that the side is on.<br />
<br />
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Default ''team_name''.<br />
<br />
* '''current_player''': a translatable string representing the player's or leader's name. Defaults to the leader's id; if the side's leader is a human player in multiplayer, the default is the player's username. {{DevFeature1.13|0}} This field is now always the player name (mp server nick) it impossible to change it with wml/lua. {{DevFeature1.13|5}} You can use ''side_name'' instead to specify the name for the side (which is then used in new turn dialogs, statisitc dialogs etc.)<br />
<br />
* '''side_name''': {{DevFeature1.13|5}} The name of the side, used for example in the new turn dialog, defaults to ''name'' if the side was inside a '''[scenario]''' and to the player's name if the side was inside a '''[multiplayer]'''.<br />
<br />
* '''color''': May be either a numeric color index or a color name (e.g. 'blue', 'purple', 'orange', etc.). The numeric form is deprecated. The default list of numbers and corresponding colors can be found in data/core/team_colors.cfg.<br />
<br />
* '''flag''': a custom flag animation to use instead of the default one to mark captured villages. An automatic side-coloring is applied.<br />
** Example animation that has three frames and loops every 750ms: ''flag=misc/myflag-[1~3].png:750''<br />
<br />
* '''flag_icon''': a custom flag icon to indicate the side playing in the statusbar (a size of 24x16 is recommended). An automatic side-coloring is applied.<br />
<br />
* '''village_gold''': the amount of gold given to this side per village it controls per turn. Default specified in ''village_income'', '''[game_config]''' ([[GameConfigWML]]).<br />
<br />
* '''village_support''': the number of unit levels this side is able to support (does not pay upkeep on) per village it controls. Default specified in ''village_support'', '''[game_config]''' ([[GameConfigWML]]).<br />
<br />
* '''recall_cost''': the amount of gold it costs to recall a unit. Default specified in ''recall_cost'', '''[game_config]''' ([[GameConfigWML]]).<br />
<br />
* '''share_maps''': whether sides allied with this side see all terrains that this side sees, if they are on shroud. {{DevFeature1.13|1}} This has been deprecated in favor of share_vision (see below).<br />
<br />
* '''share_view''': whether sides allied with this side see the units that this side sees, if they are on FoW (fog). {{DevFeature1.13|1}} This has been deprecated in favor of share_vision (see below).<br />
<br />
* '''share_vision''': {{DevFeature1.13|1}} all/shroud/none. If ''all'', both shroud and fog view will be shared by this side. If ''shroud'', only shroud view will be shared. If ''none'', the view is not shared.<br />
<br />
* '''scroll_to_leader''': optional. If `no', scroll to the leader is not performed on the start of each turn. (default: yes)<br />
<br />
* '''suppress_end_turn_confirmation''': If "yes", then the player will not be asked to confirm ending their turn even if they have not done anything. This is provided for some (probably few) user-made scenarios in which players often skip their turns. (default: no)<br />
<br />
* '''[ai]''' if '''controller=ai''', gives parameters to the AI. See [[AiWML]].<br />
<br />
* '''[village]''' describes a village the side begins in control of.<br />
** ''x'', ''y'' the location of the village. If the pair of coordinates is not a village or is duplicated in another '''[village]''' tag, behaviour is undefined. Recent game engine or wmllint should warn about these.<br />
<br />
* '''[unit]''' describes a unit which begins on the side. See [[SingleUnitWML]]. If the side has a recall list and the unit is not given a location, it will start on the recall list. Note that the ''side'' attribute under '''[unit]''' will be ignored, as the side will come from the ''side'' attribute of '''[side]'''.<br />
<br />
* '''[leader]''' same as '''[unit]''' except that ''canrecruit'' will default to yes and current position to the side starting location if not specified.<br />
<br />
* '''defeat_condition''' Specifies when a side is considered ''defeated'' this is checked ''for all sides'', after every player action and at the beginning of every turn.<br />
** '''no_leader_left''': (default) The side is considered defeated if it has no units with canrecruit=yes<br />
** '''no_units_left''': The side is defeated as soon as it has no units left.<br />
** '''never''': The side is never considered defeated.<br />
** '''always''': The side is always considered defeated.<br />
<br />
: For the meaning and significance of ''defeated'', see [[ScenarioWML#Scenario_End_Conditions]]<br />
<br />
The following keys are multiplayer only:<br />
<br />
* '''allow_player''': if false then this side will not be allowed to be modified and will be hidden during game creation. False also prevents this side from being included in shuffle sides. Defaults to yes.<br />
<br />
* '''disallow_observers''': prevents observers from seeing this side turn. (default: no)<br />
<br />
* '''disallow_shuffle''': {{DevFeature1.13|0}} do not shuffle this side if the "shuffle sides" option is used. (Usually all playable sides are shuffled.) (default: no)<br />
<br />
* '''chose_random''': {{DevFeature1.13|0}} indicates if a side chose a random faction during creation <br />
<br />
* '''controller_lock''': if true then this side's controller ("Player/Type") modification is limited. It is bound to the '''controller''' attribute in [[SideWML]].<br />
<br />
* '''team_lock''': if true then this side's team is not allowed to be modified.<br />
<br />
* '''color_lock''': if true then this side's color is not allowed to be modified.<br />
<br />
* '''gold_lock''': if true then this side's gold is not allowed to be modified. <br />
<br />
* '''income_lock''': if true then this side's income is not allowed to be modified.<br />
<br />
* '''faction_lock''': if true then this side's faction is not allowed to be modified.<br />
<br />
* '''leader_lock''': if true then this side's leader (type or gender) is not allowed to be modified.<br />
<br />
* '''faction''': if valid faction id is provided then this side's faction will default to it.<br />
<br />
* '''faction_from_recruit''': if true then this side will be locked to the faction that matches the recruits better.<br />
<br />
N.B. the ''lock'' attributes use [[ScenarioWML]] '''force_lock_settings''' as their default value. I.e. if no value to ''lock'' was set, it will take '''force_lock_settings''' value.<br />
<br />
== See Also ==<br />
* [[EraWML]]<br />
* [[ScenarioWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=AbilitiesWML&diff=59030AbilitiesWML2017-11-25T17:58:42Z<p>Cannedfood: /* Common keys and tags for specials with a value */ repair on malformed {{}}</p>
<hr />
<div>{{WML Tags}}<br />
== Abilities and their effects ==<br />
<br />
There are two types of abilities: ones that apply to units (called ''abilities'') and ones that only apply when using a particular attack (called ''specials'' or ''weapon specials''). A unit may have multiple abilities and an attack can have multiple specials, but by convention only one weapon special should be assigned to any given attack.<br />
<br />
== The ''[abilities]'' tag ==<br />
<br />
The following tags are used to describe an ability in WML:<br />
<br />
* '''[heals]''': modifies the hitpoints of a unit at the beginning of the healer's turn<br />
* '''[regenerate]''': modifies the hitpoints of a unit at the beginning of the unit's turn<br />
* '''[resistance]''': modifies the resistance of a unit to damage<br />
* '''[leadership]''': modifies the damage of a unit<br />
* '''[skirmisher]''': negates enemy zones of control<br />
* '''[illuminates]''': modifies the time of day adjacent to the affected units<br />
* '''[teleport]''': allows the unit to teleport<br />
* '''[hides]''': renders the unit invisible to enemies<br />
Any other name is valid (for example '''[dummy]'''), but will result in an ability that does nothing but report it's there. These tags still use the same common keys and tags as every other ability. '''Note:''' a dummy ability must have an id for the name and description to display.<br />
<br />
=== Common keys and tags for every ability ===<br />
<br />
* '''name''': the (translatable) name of the ability.<br />
* '''female_name''': the (translatable) name of the ability when possessed by a female unit. Defaults to ''name'' if not specified.<br />
* '''name_inactive''': the (translatable) name of the ability when inactive. Defaults to ''name'' if not specified; if the ability is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).<br />
* '''female_name_inactive''': the (translatable) name of the ability when inactive and possessed by a female unit. Defaults to ''name_inactive'' if not specified.<br />
* '''description''': the (translatable) description of the ability.<br />
* '''description_inactive''': the (translatable) description of the ability when inactive. Defaults to ''description'' if not specified.<br />
* '''affect_self''': if equal to 'yes', the ability will affect the unit that has it.<br />
* '''affect_allies''': if equal to 'yes', the ability will affect allies in the specified adjacent hexes.<br />
* '''affect_enemies''': if equal to 'yes', the ability will affect enemies in the specified adjacent hexes.<br />
* '''cumulative''': if set to 'yes', this ability will be cumulative with the base value for this ability.<br />
* '''id''': this ability will not be cumulative with other abilities using this id. Must be present if cumulative is anything other than 'yes'.<br />
* '''[filter]''': [[StandardUnitFilter]] If the unit owning the ability does not match this filter, the ability will be inactive.<br />
* '''[affect_adjacent]''': an adjacent unit that does not match this filter will not receive its effects. There can be multiple [affect_adjacent] tags in a single ability; a unit needs to match any one of these to receive the effects. If there are no [affect_adjacent] tags, then no adjacent units will receive the effects.<br />
** '''adjacent''': a comma separated list of any combination of these directions: '''n''','''ne''','''se''','''s''','''sw''','''nw'''. (See [[StandardLocationFilter#Directions|notes]])<br />
** '''[filter]''': a [[StandardUnitFilter]]. {{DevFeature1.13|2}} The variable $other_unit refers to the unit owning the ability.<br />
* '''[filter_self]''': if the owner of the ability does not match this filter, it will not receive the effects of the ability. [filter_self] takes a [[StandardUnitFilter]] as argument.<br />
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the ability will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). In fact, it's really a shorthand for a [filter_adjacent] nested within [filter]. The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate.<br />
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter][filter_location][filter_adjacent_location].<br />
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc. If several keys are used all have to match.<br />
<br />
=== Extra keys used by the ''[heals]'' ability ===<br />
<br />
* '''value''': the amount healed.<br />
* '''poison''': can be one of ''slowed'',''cured''.<br />
<br />
=== Extra keys used by the ''[regenerate]'' ability ===<br />
<br />
* '''value''': the amount healed.<br />
* '''poison''': can be one of ''slowed'',''cured''.<br />
<br />
=== Extra keys and tags used by the ''[resistance]'' ability ===<br />
<br />
* '''value''': set resistance to this value.<br />
* '''max_value''': maximum resistance value. This value '''must''' be set in order for [resistance] to function.<br />
* '''add''': adds to resistance.<br />
* '''sub''': subtracts from resistance.<br />
* '''multiply''': multiplies resistance value. <br />
* '''divide''': divides resistance value.<br />
* '''apply_to''': a list of damage types; if left out, the ability applies to all types.<br />
* '''active_on''': one of 'defense' or 'offense'; if left out, the ability is active on both.<br />
These keys affect the actual resistance (e.g. -20%), not the damage modifier normally used in [resistance] (e.g. 120).<br />
<br />
=== Extra keys used by the ''[leadership]'' ability ===<br />
<br />
* '''value''': the percentage bonus to damage.<br />
<br />
=== Extra keys used by the ''[illuminates]'' ability ===<br />
<br />
* '''value''': the percentage bonus to lawful units. Units with '''alignment=lawful''' do +''value'' % damage when under the influence of a unit with this ability. Units with '''alignment=chaotic''' do -''value'' % damage. Units with '''alignment=neutral''' are unaffected by this ability. Units with '''alignment=liminal''' do -(abs(''value'')) % damage. ''value'' can be a negative number; this is useful if you want to give Chaotic units an advantage instead of Lawful ones. <br />
* '''max_value''': the maximum percentage bonus given.<br />
* '''min_value''': the minimum percentage bonus given.<br />
<br />
=== Extra keys used by the ''[hides]'' ability ===<br />
<br />
* '''alert''': the displayed text when the unit is discovered. Default "Ambushed!".<br />
<br />
=== Extra tags used by the ''[teleport]'' ability ===<br />
<br />
* '''[tunnel]''' - a [[DirectActionsWML#.5Btunnel.5D|tunnel tag]] (without the remove key) defining the tunneling source and target hexes, and maybe other conditions. (It automatically applies only to the unit with the ability.) You may use $teleport_unit inside the tunnel tag for filtering purposes.<br />
<br />
=== Macros for common abilities ===<br />
<br />
* ABILITY_AMBUSH<br />
* ABILITY_CURES<br />
* ABILITY_HEALS<br />
* ABILITY_ILLUMINATES<br />
* ABILITY_LEADERSHIP_LEVEL_1 to ABILITY_LEADERSHIP_LEVEL_5<br />
* {{DevFeature1.13|2}} ABILITY_LEADERSHIP (replaces the above leadership macros, which are now deprecated)<br />
* ABILITY_NIGHTSTALK<br />
* ABILITY_REGENERATES<br />
* ABILITY_SKIRMISHER<br />
* ABILITY_STEADFAST<br />
* ABILITY_SUBMERGE<br />
* ABILITY_TELEPORT<br />
<br />
== The ''[specials]'' tag ==<br />
<br />
The '''[specials]''' tag goes inside the '''[attack]''' tag. It can contain the following tags:<br />
<br />
* '''[attacks]''': modifies the number of attacks of a weapon<br />
* '''[berserk]''': pushes the attack for more than one combat round<br />
* '''[chance_to_hit]''': modifies the chance to hit of a weapon<br />
* '''[damage]''': modifies the damage of a weapon<br />
* '''[disable]''': disables the weapon<br />
* '''[drains]''': heals the attacker half of the damage dealt<br />
* '''[firststrike]''': forces the weapon to always strike first<br />
* '''[heal_on_hit]''': heals the attacker when an attack connects<br />
* '''[petrifies]''': turns the target to stone<br />
* '''[plague]''': when used to kill an enemy, a friendly unit takes its place<br />
* '''[poison]''': poisons the target<br />
* '''[slow]''': slows the target<br />
* '''[swarm]''': number of strikes decreases as the unit loses hitpoints<br />
Any other name is valid, but will result in an special that does nothing but report it is there.<br />
<br />
=== Common keys and tags for every weapon special ===<br />
<br />
* '''name''': the (translatable) name of the special.<br />
* '''name_inactive''': the (translatable) name of the special when inactive. Defaults to ''name'' if not specified; if the special is supposed to be not displayed when inactive, you must explicitly set ''name_inactive'' to an empty string (nothing after the equals sign).<br />
* '''description''': the (translatable) description of the special.<br />
* '''description_inactive''': the (translatable) description of the special when inactive. Defaults to ''description'' if not specified.<br />
* '''id''': this ability will not be cumulative with other specials using this id.<br />
* '''active_on''': one of '''defense''' or '''offense'''; if left out, the special is active on both.<br />
* '''apply_to''': one of '''self''','''opponent''','''attacker''','''defender''','''both''' (default: ''self''). Determines who the effects of this special are applied to.<br />
* '''[filter_adjacent]''': if an adjacent unit does not match this filter, the special will not be active and no-one will receive its affects. Takes extra keys ''adjacent'', ''count'', ''is_enemy'', just like in a [[StandardUnitFilter]]. In fact, it's really a shorthand for a [filter_adjacent] nested within [filter_self], with the one difference that, in the absence of a specified ''count'', all listed directions must match (so, with two directiones eg ''adjacent=n,s'', the default is ''count=2''). The variables $this_unit and {{DevFeature1.13|2}} $other_unit both work as you'd expect. Multiple [filter_adjacent] can be provided, all of which must pass for the ability to activate. <br />
* '''[filter_adjacent_location]''': like [filter_adjacent], but filters on locations instead of units. This is a shorthand for [filter_self][filter_location][filter_adjacent_location].<br />
* '''[filter_self]''': the special will only be active if the owner matches this [[StandardUnitFilter]] (SUF).<br />
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.<br />
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the opponent.<br />
* '''[filter_opponent]''': the special will only be active if the opponent matches this SUF.<br />
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.<br />
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the unit that owns the weapon.<br />
* '''[filter_attacker]''': the special will only be active if the attacker matches this SUF.<br />
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.<br />
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the defender.<br />
* '''[filter_defender]''' the special will only be active if the defender matches this SUF.<br />
** '''[filter_weapon]''': a [[FilterWML#Filtering_Weapons|standard weapon filter]], including special=.<br />
** '''$other_unit''': {{DevFeature1.13|2}} The special variable $other_unit refers to the attacker.<br />
<br />
=== Common keys and tags for specials with a value ===<br />
<br />
The '''[damage]''', '''[attacks]''', and '''[chance_to_hit]''' specials take values that specify how those specials modify their respective base values. The '''[drains]''' special takes a value specifying the percentage of damage drained (default 50) and '''[heal_on_hit]''' takes the amount to heal (default 0; negative values will harm the attacker, but not kill).<br />
<br />
* '''value''': the value to be used.<br />
* '''add''': the number to add to the base value.<br />
* '''sub''': the number to subtract from the base value.<br />
* '''multiply''': this multiplies the base value.<br />
* '''divide''': this divides the base value.<br />
* '''cumulative''': if set to 'yes', this special will be cumulative with the base value.<br />
* '''backstab''': if set to 'yes', this special will only apply to the attacker, and only when there is an enemy on the target's opposite side (i.e. when the standard backstab special applies). {{DevFeature1.13|2}} This is now deprecated. The same functionality can be achieved with a [filter_adjacent] in [filter_opponent]; see the implementation of the default backstab special for details.<br />
* '''[filter_base_value]''': filters on the value before any modifications; uses the keys '''equals''', '''not_equals''', etc.<br />
<br />
=== Extra keys used by the ''[berserk]'' special ===<br />
<br />
* '''value''': the maximum number of combat rounds (default 1).<br />
* '''cumulative''': if set to 'yes', this special will be cumulative with other active berserk specials (on the current combatant, not with an opponent's berserk).<br />
<br />
=== Extra keys used by the ''[plague]'' special ===<br />
<br />
* '''type''': the unit type to be spawned on kill.<br />
<br />
=== Extra keys used by the ''[swarm]'' special ===<br />
<br />
* '''swarm_attacks_max''': the maximum number of attacks for the swarm. Defaults to the base number of attacks modified by any applicable [attacks] specials. If this is specified, then the base number of attacks is ignored.<br />
* '''swarm_attacks_min''': the minimum number of attacks for the swarm. Defaults to zero. This can be set higher than swarm_attacks_max to cause a unit to gain attacks as health decreases.<br />
The ratio of the unit's current to maximum hit points will be used to scale the number of attacks between these two values.<br />
<br />
Prior to version 1.11, a [swarm] special will cause [attacks] specials to be ignored. In 1.11 and later, [attacks] specials are applied before [swarm].<br />
<br />
=== Macros for common weapon specials ===<br />
<br />
* WEAPON_SPECIAL_BACKSTAB<br />
* WEAPON_SPECIAL_BERSERK<br />
* WEAPON_SPECIAL_CHARGE<br />
* WEAPON_SPECIAL_DRAIN<br />
* WEAPON_SPECIAL_FIRSTSTRIKE<br />
* WEAPON_SPECIAL_MAGICAL<br />
* WEAPON_SPECIAL_MARKSMAN<br />
* WEAPON_SPECIAL_PLAGUE<br />
* WEAPON_SPECIAL_PLAGUE_TYPE TYPE<br />
* WEAPON_SPECIAL_POISON<br />
* WEAPON_SPECIAL_SLOW<br />
* WEAPON_SPECIAL_STONE<br />
* WEAPON_SPECIAL_SWARM<br />
<br />
== See Also ==<br />
<br />
* [[UnitTypeWML]]<br />
* [[SingleUnitWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category:WML Reference]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=LuaWML&diff=58969LuaWML2017-10-20T12:35:38Z<p>Cannedfood: /* The [lua] tag */ corrected spelling</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.2] 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#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.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 />
<br />
=== User interface ===<br />
<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_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#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.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.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.clear_shroud|wesnoth.clear_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.add_ai_component|wesnoth.add_ai_component]] {{DevFeature1.13|7}}<br />
* [[LuaWML:Sides#helper.all_teams|helper.all_teams]]<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.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#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 />
== 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 />
[[Category: Lua Reference|*]]<br />
[[Category: WML Reference]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=UnitTypeWML&diff=58740UnitTypeWML2017-08-07T14:55:31Z<p>Cannedfood: /* Attacks */ corrected descriptions of when parry= and accuracy= are used</p>
<hr />
<div>{{WML Tags}}<br />
<br />
__TOC__<br />
<br />
Each '''[unit_type]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]])<br />
<br />
Unit animation syntax is described in [[AnimationWML]]. In addition to the animation tags described there, the following key/tags are recognized:<br />
* '''[advancefrom]''': Defines the previous unit type on the advancement tree. Allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys:<br />
** ''unit'': the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into.<br />
** ''experience'': (optional) If present the experience needed to advance is set to this value. If there are more than one [advancefrom] tags referencing the same base unit within the same preprocessor scope (e.g. a campaign #ifdef) with experience= keys, the lowest value of these is chosen. Note: this will also lower the experience required to advance to other units which the base unit can advance into.<br />
: If the previous unit type makes use of '''[male]''' and/or '''[female]''' tags, then the current (new) unit type is expected to also. That is, the subtypes defined by those tags will only receive this advancement if the new type has a corresponding tag.<br />
* '''advances_to''': When this unit has ''experience'' greater than or equal to ''experience'', it is replaced by a unit of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead. Can be a comma-separated list of units that can be chosen from upon advancing.<br />
* '''alignment''': one of lawful/neutral/chaotic/liminal (See [[TimeWML]]). Default is "neutral".<br />
* '''attacks''': the number of times that this unit can attack each turn.<br />
* '''cost''': when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited.<br />
* '''recall_cost''': {{DevFeature1.13|0}} the default recall cost of units of this type, overriding the recall cost set in scenario [[SideWML|[side]]] tags or the global [[GameConfigWML|[game_config]]] value. Individual units may override this value in [[SingleUnitWML|[unit]]]. A value of -1 is equivalent to not specifying this attribute.<br />
* '''description''': (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'. <br />
* '''do_not_list''': Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools. {{DevFeature1.13|?}} When placing units in debug mode this unit isn't listed (but can still be placed using the :create command).<br />
* '''ellipse''': the ellipse image to display under the unit, which is normally team-colored. Default is "misc/ellipse"; "-nozoc" and "-leader" are automatically appended for units without zone of control and with canrecruit=yes respectively. The [http://www.wesnoth.org/macro-reference.xhtml#IS_HERO IS_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#MAKE_HERO MAKE_HERO]/[http://www.wesnoth.org/macro-reference.xhtml#UNMAKE_HERO UNMAKE_HERO] macros change the ellipse to/back from "misc/ellipse-hero". Finally, setting this to "none" will cause the unit to not have any ellipses displayed under it regardless of the user's preferences.<br />
* '''experience''': When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.<br />
* '''flag_rgb''': usually set by [http://www.wesnoth.org/macro-reference.xhtml#MAGENTA_IS_THE_TEAM_COLOR MAGENTA_IS_THE_TEAM_COLOR]; specifies the colours in the base flag to use for team-colouring the unit, expressed as a colour name (such as magenta) or a comma-separated list of RGB values (in hex format).<br />
* '''gender''': has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base.<br />
* '''halo''': an image to place centered on the unit. It is drawn on top of the unit, and on top of surrounding units if the image is larger than one hex. It works similarly to the halo attribute of {{tag|InterfaceActionsWML|item}}, and it can be animated with a comma-separated list of images.<br />
* '''hide_help''': (yes|no) default=no. Determines if the unit type will appear in the in-game help.<br />
* '''hitpoints''': the maximum HP that the unit has, and the HP it has when it is created.<br />
* '''id''': the value of the ''type'' key for units of this type. This is required and must be unique among all [unit_type] tags. An ''id'' should consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare<br />
::WARNING : characters "$", "&", "*", "-", "(" and ")" are illegal for use in the unit type id and must be avoided because they might lead to corrupted saved games<br />
*'''ignore_race_traits''': 'yes' or 'no' (default). Determines whether racial traits (see [[UnitsWML]]) are applied. <br />
* '''image''': sets the base image of the unit, which is used on the map.<br />
* '''image_icon''': sets the image used to represent the unit in areas such as the attack dialog and the unit image box in the sidebar. [[ImagePathFunctionWML#Crop_Function|~CROP]] function can be useful here. You can see Loyalists Paladin as an example.<br />
* '''level''': the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).<br />
* '''movement''': the number of move points that this unit receives each turn.<br />
* '''movement_type''': See [[UnitsWML#.5Bmovetype.5D|movetype]]. Note that the tags '''[movement_costs]''', '''[vision_costs]''', '''[defense]''', and '''[resistance]''' can be used to modify this movetype.<br />
* '''name''':(translatable) displayed in the Status Table for units of this type.<br />
* '''num_traits''': the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.<br />
* '''profile''': the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). The engine first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cutoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.<br />
** If "unit_image" is given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).<br />
* '''small_profile''': the image to use when a smaller portrait is needed than the one used for messages (e.g., in the help system). When this attribute is missing, the value of the '''profile''' attribute is used instead. When present, the heuristic for finding a transparent portrait is disabled for the '''profile''' attribute, so the correct '''profile''' should be set too. If '''profile''' is not present, '''small_profile''' is ignored. Note that image modifiers are allowed; they might be useful for cropping and rescaling a portrait:<br />
small_profile="portraits/elves/transparent/marksman+female.png~CROP(0,20,380,380)~SCALE(205,205)"<br />
profile="portraits/elves/transparent/marksman+female.png"<br />
* '''race''': See {{tag|UnitsWML|race}}. Also used in standard unit filter (see [[FilterWML]]). Mainline Wesnoth features following values: bats, drake, dwarf, elf, falcon, goblin, gryphon, human, khalifate, lizard, mechanical, merman, monster, naga, ogre, orc, troll, undead, wolf, wose. They are defined in /data/core/units.cfg.<br />
* '''undead_variation''': When a unit of this type is killed by a weapon with the plague special, this variation is applied to the new plague unit that is created, whatever its type. For example, if the plague special creates Walking Corpses and undead_variation is set to "troll", you'll get a troll Walking Corpse. Defaults to the undead_variation set in this unit type's race.<br />
* '''usage''': the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage:<br> ** ''scout'': Fast, mobile unit meant for exploration and village grabbing.<br> ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged.<br> ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee.<br> ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal.<br> ** ''healer'': Specialty 'heals' or 'cures'.<br>Note that this field primarily affects recruitment. It also has a small effect on unit movement (the AI tries to keep scouts away from enemies, to some extent). It does not affect the AI's behavior in combat; that is always computed from attack power and hitpoints. Non-standard usages may be used as well.<br />
* '''vision''': the number of vision points to calculate the unit's sight range. Defaults to ''movement'' if not present.<br />
* '''zoc''': if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).<br />
* '''die_sound''': sets the sound, which is used when the unit dies.<br />
* '''healed_sound''': sets the sound used when the unit is healed in any way (default: heal.wav).<br />
* '''hp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).<br />
* '''xp_bar_scaling''': Overrides the attribute in ([[GameConfigWML]]).<br />
<br />
== After max level advancement (AMLA) ==<br />
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.<br />
** '''id''': unique identifier for this advancement; ''Required'' if there are multiple advancement options, or if ''strict_amla=no''.<br />
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.<br />
** '''description''': a description displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.<br />
** '''image''': an image to display next to the description in the advancement menu.<br />
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement. Pass -1 for "unlimited".<br />
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.<br />
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.<br />
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.<br />
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.<br />
** '''exclude_amla''': {{DevFeature1.13|2}} An optional list of AMLA ''id'' keys that represent AMLAs that are mutually exclusive to this one. Order is not important, and an AMLA id can be repeated. If the unit already has any of the AMLAs that appear once in this list, then this AMLA will not be made available. If an AMLA id appears multiple times in the list, then this AMLA will be made available only if the other AMLA has been chosen less than the number of times it appears in the list. Of course, for this to really make two AMLAs mutually exclusive, you need to add ''exclude_amla'' to both AMLA defintions.<br />
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]<br />
<br />
== Attacks ==<br />
* '''[attack]''': one of the unit's attacks.<br />
** '''description''': a translatable text for name of the attack, to be displayed to the user.<br />
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (see below). Non-translatable. Used for the ''has_weapon'' key and animation filters; see [[StandardUnitFilter]] and [[AnimationWML]]<br />
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see {{tag|UnitsWML|movetype|resistance}}).<br />
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML#The_.5Bspecials.5D_tag|AbilitiesWML]].<br />
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory. Defaults to the attack's name in the attacks directory (Ex. if ''name=sword'' then default is ''icon=attacks/sword.png''). <br />
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. Also displayed on the status table in parentheses; 'melee'(default) displays "melee", while 'ranged' displays "ranged". Range can be anything. Standard values are now "melee" and "ranged". From now on, ''short'' and ''long'' will be treated as totally different ranges. You can create any number of ranges now (with any name), and units can only retaliate against attacks for which they have a corresponding attack of the same range. This value is translatable.<br />
** '''damage''': the damage of this attack<br />
** '''number''': the number of strikes per attack this weapon has<br />
** '''accuracy''': a number added to the chance to hit whenever using this weapon offensively (i.e. during a strike with this attack, regardless of who initiated the combat); negative values work too<br />
** '''parry''': a number deducted from the enemy chance to hit whenever using this weapon defensively (i.e. during the enemy's strike, regardless of who initiated the combat); negative values work too<br />
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.<br />
** '''attack_weight''': helps the AI to choose which attack to use when attacking; highly weighted attacks are more likely to be used. Setting it to 0 disables the attack on attack<br />
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense <br />
For the weight settings, the engine usually chooses the attack with the best average total damages * weight (default weight = 1.0).<br />
<br />
== Other tags ==<br />
* '''[base_unit]''': Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitTypeWML for that unit is copied into this one, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Additionally, the unit will be marked as variation of the base unit in its own help page, but not in the help page of the base unit.<br />
<br />
* '''[portrait]''': Describes a unit portrait for dialogue. However, generally you should use the profile key instead; [portrait] is mostly for internal use.<br />
** '''size''': The size of the portrait, in pixels.<br />
** '''side''': One of left or right.<br />
** '''mirror''': Whether to flip the image horizontally.<br />
** '''image''': The image path.<br />
<br />
* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]<br />
<br />
* '''[event]''': Any [event] written inside the [unit_type] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities]]<br />
<br />
* '''[variation]''': Defines a variation of a unit. Variations are invoked with an [effect] tag or the variation= attribute in [[SingleUnitWML]]. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.<br />
** '''variation_id''': The id of this variation. Defaults to ''variation_name''.<br />
** '''variation_name''': Translatable. The name of the variation.<br />
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to no.<br />
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.<br />
** All keys and tags of '''[unit_type]''', except ''[advancefrom]'', ''[base_unit]'', ''[female]'', ''[male]'', and ''[variation]''.<br />
<br />
* '''[male]''', '''[female]''': These can specify a variation based on gender for a unit. If these are provided, they will automatically apply based upon the gender of a unit.<br />
** '''inherit''': if ''yes'', inherits all the properties of the base unit, as if by [[InternalActionsWML#.5Bset_variables.5D|[set_variables]mode=merge]]. Defaults to yes.<br />
*** The '''id''' key is always inherited, regardless of the value of '''inherit'''.<br />
** All '''[unit_type]''' tags and keys, excluding ''[advancefrom]'', ''[base_unit]'', ''[female]'', and ''[male]''.<br />
<br />
== See Also ==<br />
<br />
* [[AnimationWML]]<br />
* [[ReferenceWML]]<br />
* [[TerrainWML]]<br />
<br />
[[Category: WML Reference]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=PblWML&diff=58739PblWML2017-08-07T11:43:35Z<p>Cannedfood: /* What goes into a .pbl file? */ mention which tags are required by the server to be non-null</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 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 />
: This value is required.<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 />
: 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 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 />
: This value is required.<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 />
: 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, 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>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=SyntaxWML&diff=58725SyntaxWML2017-07-29T03:58:56Z<p>Cannedfood: /* Special Attribute Values */ added cursory description of << >> quotation.</p>
<hr />
<div>{{SyntaxWML/Translations}}<br />
{{WML Tags}}<br />
<br />
The '''Wesnoth Markup Language''' ('''WML''') is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML.<br />
For guidelines on keeping these files easily human-readable, see [[ConventionsWML#Indentation|ConventionsWML]].<br />
<br />
== Tag and Attribute Structures ==<br />
<br />
WML has a syntax containing two basic elements: ''tags'' and ''attributes''. Furthermore, ''attributes'' consist of ''keys'' and ''values''. For example:<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key=value<br />
[/tag]<br />
</syntaxhighlight><br />
<br />
''Tags'' are used to partition information, while the data is contained in the ''attributes''. ''Keys'' identify the type of data to be stored and ''values'' are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each <code>key=value</code> line within a tag, the attribute identified by <code>key</code> has its data set to <code>value</code>.<br />
Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.<br />
<syntaxhighlight lang="wml"><br />
[parent_tag]<br />
key1=value1<br />
[child_tag]<br />
key2=value2<br />
[/child_tag]<br />
[/parent_tag]<br />
</syntaxhighlight><br />
<br />
Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "[[ReferenceWML#WML_toplevel_tags|top-level tags]]" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored.<br />
<br />
''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.<br />
<br />
Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they will not contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed.<br />
<br />
<br />
=== Tag Amendment Syntax ===<br />
<br />
Inserting a plus sign (<code>+</code>) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key=value<br />
[/tag]<br />
[+tag]<br />
key=value<br />
[/tag]<br />
</syntaxhighlight><br />
<br />
* All keys in the ''+tag'' will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].<br />
<br />
* Any child tags of the ''+tag'' will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."<br />
<br />
* It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.<br />
<br />
=== Multiple Assignment Syntax ===<br />
<br />
It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key1,key2,key3=value1,value2,value3<br />
[/tag]<br />
</syntaxhighlight><br />
would be the same as:<br />
<syntaxhighlight lang="wml"><br />
[tag]<br />
key1=value1<br />
key2=value2<br />
key3=value3<br />
[/tag]<br />
</syntaxhighlight><br />
* If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.<br />
<br />
=== Special Attribute Values ===<br />
<br />
Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.<br />
* '''key = "value"''': a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break inside quotes does not end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped. It is never wrong to use quotes with correct WML.<br />
* '''key = _"value"''': a ''[[translatable|translatable value]]'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data.<br />
* '''key = "value1" + "value2"''': ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left. To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes.<br />
* '''key = "quoted ""double quoted value"" value"''': ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)<br />
* '''key = $variable''': a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].<br />
* '''key = "$(formula-expression)"''': a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''<br />
* '''key = <<value>>''': similar to a quoted value but stronger: the value is hidden from the [[PreprocessorRef|preprocessor]], which will see all text therein as literal. Useful with [[LuaWML]] or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string.<br />
<br />
== Variables ==<br />
<br />
Variables in WML are used to store data for later retrieval. Each variable is identified by its name, which may contain only alphanumerics and underscores. Once created, a variable persists until the end of a campaign unless explicitly cleared.<br />
<br />
The three basic manipulations of WML variables are assigning a value, querying the value, and clearing the variable.<br />
* '''Assigning to a variable''': stores a value in the variable. This is done with tags like {{tag|InternalActionsWML|set_variable}} or with [[PreprocessorRef|macros]] like <tt>{VARIABLE}</tt>.<br />
* '''Querying a variable''': returns the last value stored in the variable (or the empty string, if no value was). This is done by prefixing the variable name with a dollar sign, as in <tt>$variable</tt>, and sometimes ending the variable name with a pipe character, as in <tt>$variable|</tt>.<br />
* '''Clearing a variable''': makes the WML engine forget about that variable. This is useful for reducing overhead, since all used variables are stored in saved games. This is done with {{tag|InternalActionsWML|clear_variable}} or the <tt>{CLEAR_VARIABLE}</tt> [[PreprocessorRef|macro]].<br />
<br />
=== Kinds of Variables ===<br />
==== Scalar ====<br />
A scalar variable can store a single string or number.<br />
<br />
<syntaxhighlight lang="wml"><br />
[set_variable]<br />
name=my_variable<br />
value="sample value"<br />
[/set_variable]<br />
</syntaxhighlight><br />
<br />
The full name of a scalar variable is its given name, in this case ''my_variable''. Note that the value of the variable can be translatable or even a formula expression ([http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values Special Attribute Values]).<br />
<br />
==== Array ====<br />
An array variable is a numbered sequence of container variables. There are some specific tags that assign array information, for example [store_unit] and [store_locations]. One could create an array using [set_variable] like this:<br />
<syntaxhighlight lang="wml"><br />
[set_variable]<br />
name=my_awesome_array[0].x<br />
value=10<br />
[/set_variable]<br />
[set_variable]<br />
name=my_awesome_array[1].x<br />
value=12<br />
[/set_variable]<br />
[set_variable]<br />
name=my_awesome_array[2].x<br />
value=14<br />
[/set_variable]<br />
</syntaxhighlight><br />
<br />
However, when working with arrays, it is usually easier to make use of [set_variables]. This would be written as follows:<br />
<syntaxhighlight lang="wml"><br />
[set_variables]<br />
name=my_awesome_array<br />
[value]<br />
x=10<br />
[/value]<br />
[value]<br />
x=12<br />
[/value]<br />
[value]<br />
x=14<br />
[/value]<br />
[/set_variables]<br />
</syntaxhighlight><br />
<br />
If <tt>foo</tt> is the name of an array, <tt>foo[0]</tt> is the full name of its first container variable, <tt>foo[1]</tt> the full name of its second, and so on. <tt>foo.length</tt> is the special variable that always stores the number of containers in the array <tt>foo</tt>. Hence, if the value stored in <tt>foo.length</tt> is 18, the last container in the array would be <tt>foo[17]</tt>. If you try to query an array as if it were a container, then it will simply use the first index[0]. Thus $foo.bar would be the same as $foo[0].bar<br />
<br />
''Note'': Do not attempt to store a scalar value to the explicit index of an array, which is a container of scalar variables. Hence referring to a variable named <tt>foo[3]</tt> as if it were a scalar one is illegal; instead, you would use <tt>foo[3].value</tt> to store a scalar value. (While it may appear to work to an extent if you ignore this rule, it may also cause undefined behavior. For example, loading a text save of a game that contains such variables will fail with a WML error.)<br />
<br />
==== Container ====<br />
A container variable can store any number of scalar and/or array variables. There are tags to assign specific information, for instance [store_side]. To refer to a variable <tt>bar</tt> stored in a container <tt>foo</tt> you would write <tt>foo.bar</tt>. An explicit index inside an array is also considered a container.<br />
<br />
=== Conditionals ===<br />
Variables may be compared by using [variable] within an [if] or [while] tag. For more information, please refer to [[ConditionalActionsWML]].<br />
<br />
=== Variable Substitution ===<br />
Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:<br />
<syntaxhighlight lang="wml"><br />
[event]<br />
name=turn 1<br />
[set_variable]<br />
name=my_variable<br />
value= _ "Konrad"<br />
[/set_variable]<br />
[message]<br />
speaker=Delfador<br />
message= _ "Hello, $my_variable|... How are you?"<br />
[/message]<br />
[/event]<br />
</syntaxhighlight><br />
<br />
The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.<br />
<br />
When writing scenario events ([[EventWML]]), a scalar variable can generally be substituted into the right-hand of any '''key=value''' assignment. If the provided value contains a <tt>$</tt>, the WML engine with interpret what is between the rightmost <tt>$</tt> and the next <tt>|</tt> as a full variable name to be queried, and replace <tt>$''variable''|</tt> with the result of this query.<br />
<br />
In certain situations, the <tt>|</tt> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no |, variable names span letters, digits, underlines, balanced square brackets and some periods. Doubled periods and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using $|), then it will be replaced by just $, giving you an easy way to include a dollar sign in an interpolated string.<br />
<br />
{{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, you can use the syntax <tt>$varname?default text|</tt>. In this case, the <tt>|</tt> is required.<br />
<br />
==== Literal Mode ====<br />
<br />
There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:<br />
* value of '''literal=''' inside [set_variable]<br />
* contents of '''[literal]''' inside [set_variables]<br />
* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start<br />
<br />
=== Automatically Stored Variables ===<br />
* '''side_number''': the number of the current player's side (may be empty during start or prestart events)<br />
* '''turn_number''': the number of the current turn (may be empty during start or prestart events)<br />
* '''x1''': this is the x-coordinate of the location where the most recent event was triggered<br />
* '''y1''': this is the y-coordinate of the location where the most recent event was triggered<br />
* '''x2''': this is the x-coordinate of the location that assisted in triggering the most recent event<br />
* '''y2''': this is the y-coordinate of the location that assisted in triggering the most recent event<br />
* '''unit''': inside an event, this is the unit at $x1,$y1<br />
* '''second_unit''': inside an event, this is the unit at $x2,$y2<br />
* '''this_unit''': inside a standard unit filter, this is the unit currently being considered for a possible match<br />
* '''other_unit''': inside some standard unit filters, this is an adjacent unit relevant to the match<br />
* '''damage_inflicted''': inside attacker_hits and defender_hits events, this is the amount of damage that was inflicted<br />
* '''weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x1,$y1. It contains the attributes from [attack], see [[UnitTypeWML]].<br />
* '''second_weapon''': inside attack, attack_end, attacker_hits, attacker_misses, defender_hits, defender_misses, die and last_breath events, this is some information about the weapon that is/was being used by the unit at $x2,$y2. It contains the attributes from [attack], see [[UnitTypeWML]].<br />
<br />
Note: Automatically stored container and array variables are only stored once that one of their attributes is accessed for the first time. This means that one can sometimes get wrong results, for instance by killing the unit at $x1,$y1 as first action in a moveto event and then accessing $unit.something. This can be worked around by previously making a dummy access, such as adding 0 to hitpoints.<br />
<br />
=== The [variables] tag ===<br />
<br />
The [variables] tag is used in saved games to describe the current value of each variable, and in scenario files for assigning initial values to variables at scenario start.<br />
<br />
A scalar variable is assigned using an attribute, where the attribute's key is the variable's given name, and the attribute's value is the value to be stored in the variable.<br />
<br />
A container variable with given name ''foo'' is assigned using a [foo] tag that contains the definitions for the contained variables.<br />
<br />
An array variable with given name ''foo'' is assigned using several [foo] tags, where the first tag describes foo[0], the second foo[1], ...<br />
<br />
=== Storing variables inside units ===<br />
<br />
Sometimes it is useful to store a custom WML variable inside a unit. Units stored with the [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]] command have a '''unit.variables''' sub-container where custom variables related to that unit may be saved. (Remember to [[DirectActionsWML#.5Bunstore_unit.5D|[unstore_unit]]] for the changes to be kept.) One benefit of this approach is that the unit may then be [[FilterWML|filtered]] based on the value, for example:<br />
<syntaxhighlight lang="wml"><br />
[filter]<br />
[filter_wml]<br />
[variables]<br />
my_variable="test"<br />
[/variables]<br />
[/filter_wml]<br />
[/filter]<br />
</syntaxhighlight><br />
<br />
=== Variable Usage Examples ===<br />
Consider a saved game with the following [variables] tag (or a freshly started scenario with that tag)<br />
<syntaxhighlight lang="wml"><br />
[variables]<br />
attitude_of_elves=hate<br />
attitude_of_dwarves=love<br />
attitude_of_humans=like<br />
current_opponent=elves<br />
[/variables]<br />
</syntaxhighlight><br />
<br />
Then,<br />
<syntaxhighlight lang="wml"><br />
[message]<br />
message="Oh, I see $current_opponent|! They surely $attitude_of_$current_opponent|| us!"<br />
[/message]<br />
</syntaxhighlight><br />
displays the message<br />
Oh, I see elves! They surely hate us!<br />
<br />
Consider another game with variables<br />
<syntaxhighlight lang="wml"><br />
[variables]<br />
our_side=1<br />
their_side=2<br />
[/variables]<br />
</syntaxhighlight><br />
where side 1 has 75 gold, and side 2 50 gold. Then, <br />
<syntaxhighlight lang="wml"><br />
[store_side]<br />
side=$our_side<br />
variable=we<br />
[/store_side]<br />
[store_side]<br />
side=$their_side<br />
variable=they<br />
[/store_side]<br />
[message]<br />
message=We have $we.gold gold, they have $they.gold gold.<br />
[/message]<br />
[if]<br />
[variable]<br />
name=we.gold<br />
greater_than=$they.gold<br />
[/variable]<br />
[then]<br />
[message]<br />
message=This should be easy!<br />
[/message]<br />
[/then]<br />
[else]<br />
[message]<br />
message=This will not be easy!<br />
[/message]<br />
[/else]<br />
[/if]<br />
[clear_variable]<br />
name=we<br />
[/clear_variable]<br />
[clear_variable]<br />
name=they<br />
[/clear_variable]<br />
</syntaxhighlight><br />
displays the messages<br />
We have 75 gold, they have 50 gold.<br />
This should be easy!<br />
If side 2 had 100 gold instead, the same code would display the messages<br />
We have 75 gold, they have 100 gold.<br />
This will not be easy!<br />
<br />
The code<br />
<syntaxhighlight lang="wml"><br />
[store_unit]<br />
[filter]<br />
canrecruit=yes<br />
side=1<br />
[/filter]<br />
variable=leader<br />
[/store_unit]<br />
[message]<br />
message=Our leader's first attack does $leader[0].attack[0].damage damage per hit.<br />
[/message]<br />
[clear_variable]<br />
name=leader<br />
[/clear_variable]<br />
</syntaxhighlight><br />
always displays a true sentence.<br />
<br />
You may find more complicated examples of variable use in the [[UsefulWMLFragments]] section.<br />
<br />
== Comments ==<br />
<br />
Comments are indicated by starting a line with a pound sign (<code>#</code>). Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine.<br />
<br />
It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.<br />
<br />
== Tutorial ==<br />
<br />
* [[VariablesWML/How_to_use_variables|How to use variables]]<br />
<br />
== See Also ==<br />
<br />
* [[PreprocessorRef]]<br />
* [[ConventionsWML]]<br />
* [[SavefileWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]</div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=User:Cannedfood&diff=58724User:Cannedfood2017-07-29T03:48:36Z<p>Cannedfood: Created page with "<nowiki>§ wiki.wesnoth.org ActionWML rather circular with Conditional: … AddonStructure the '_main.cfg' is required for the Add–on client to recognize it. you'd th..."</p>
<hr />
<div><nowiki>§ wiki.wesnoth.org<br />
<br />
ActionWML<br />
rather circular with Conditional: …<br />
<br />
AddonStructure<br />
the '_main.cfg' is required for the Add–on client to recognize it.<br />
you'd think that a '_server.pbl' would suffice, but it does not.<br />
<br />
AI_Recruitment<br />
“Tests have shown that it plays slightly better (against other AIs, at least)”<br />
hmm. how did they qualify that?<br />
<br />
BinaryPathWML<br />
the default is …<br />
<br />
ConditionalActionsWML<br />
The [while] tag is useful for iterating over an array. An array is a list of values. The numberth value in the array array is stored in the WML variable array[number]. Note that if number is the value of the variable variable, the expression $array[$variable] will return the numberth value in array.<br />
? an array not used as a container?<br />
<br />
ConventionsWML<br />
my AvernumScript style of indenting works well in these such uses — though for different reason:<br />
can_recruit = yes<br />
[and]<br />
side = $side_number<br />
[/and]<br />
<br />
Editingwesnoth<br />
garbage.<br />
<br />
EffectWML<br />
it should be clearer that most of these are not “keys” but are values for<br />
apply_to=<br />
status:<br />
it should indent the “Beware” and make it more visible.<br />
<br />
EraWML<br />
[era] [multiplayer_side] type=<br />
this defaults with "random".<br />
<br />
EventWML<br />
side turn end<br />
$side_number hasn't changed yet, so it is at the very end of turn, not sursequent to it? when it does not accept input of troop commands, but that Side is yet active.<br />
<br />
GameConfigWML<br />
village_support is not described here!<br />
<br />
IGNFileFormat<br />
lines such as these aren't registered:<br />
folder/filename<br />
<br />
ImagePathFunctionWML<br />
#BLIT:_Blit_Function<br />
! all this is erroneous. i was mis-using the CROP function's 'width' and 'height' args.<br />
• this doesn't hierate any functions applied to the 'src' arg prior to applying the image on the background. i.e. if the original would exceed the boundaries of the background prior to any cropping, the blit will fail. e.g.:<br />
_~BLIT( _~CROP( N1,N1,N3,N4 ),N5,N6 )<br />
workaround is to envelope the operation in adjusted CROP or SCALE, et simila, as necessary. e.g.:<br />
…<br />
? this also means that it will forget, beneath the blit prior to and resizing or cropping of it, any layers — at least those above the background.<br />
? i haven't examined the C++ code.<br />
this limitation can be always applying BLIT from top–left to bottom–right if the blits would overlap.<br />
! no — this may yet be a problem, but it wasn't what was vexing my trials.<br />
the problem, apparently, was with it blitting the second<br />
<br />
InterfaceActionsWML<br />
#.5Bwml_message.5D<br />
badly written Note paragraph.<br />
#.5Bmessage.5D<br />
0x27? nope: i tested that with other strings.<br />
0x27 does not work for a cartouchier. try these and see:<br />
• [message]<br />
message='<br />
• [message]<br />
message='<br />
test'<br />
• [message]<br />
message='<br />
'<br />
#.5Bset_menu_item.5D<br />
[command]<br />
first_time_only=no this is the default. however, does setting this =yes make it so the menu item no longer appears?<br />
<br />
LuaWML<br />
immideately<br />
<br />
OptionWML<br />
[options]<br />
[combo]<br />
if the [item] which matches the default= has a null value= then the dropdown menu box will show no choice.<br />
[slider]<br />
default = 100<br />
min = 1<br />
max = 100<br />
step = 3<br />
it jumps to 99, not 100, and the minimum is 0. obviously, therefore, it instantiates at 0 first, proceeds to the $max via the $step, and then goes to some minimum value which it can reach via the $step again.<br />
[campaign] [options]<br />
apparently this only is possible with 1.13 and not 1.12 edition.<br />
<br />
PblWML<br />
icon=<br />
max is 72x72 — correct? anything which would go outside is omitted; e.g., attempting to BLIT something that would extend beyond 72 in either axis is not BLITted.<br />
<br />
PreprocessorRef<br />
you can't provide an empty arg by doing {example ""}<br />
#.23define<br />
it does not substitute for its ‘symbol’. e.g.<br />
#define example<br />
shoyu#enddef<br />
#define {example}_test A B<br />
"something,anything,{A},{B}"<br />
#enddef<br />
{shoyu_test a b}<br />
¶ Macro/file 'shoyu_test' is missing<br />
! feature request pending to be pending<br />
does not allow 0x09 as delimiter between symbol and arguments; it works between trigger #define and ‘symbol’, though.<br />
#Preprocessor_directives<br />
it recognizes any of these, even when they don't begin a new word. some syntax highlighters don't recognize that fact.<br />
<br />
SavefileWML<br />
you can view them with 'zless', WinRAR, or any such thing.<br />
<br />
ScenarioWML<br />
experience_modifier<br />
looks like IFDEF MULTIPLAYER then this is 70<br />
#The_.5Bscenario.5D_tag<br />
[multiplayer] name=<br />
value type is a literal<br />
<br />
SideWML<br />
team_name=<br />
literal<br />
[village]<br />
• you can't do this format:<br />
x = 1, 2<br />
y = 2, 1<br />
if you do, only the first in the set is recognized<br />
<br />
StandardUnitFilter<br />
[filter_wml]<br />
this is described very badly.<br />
<br />
SyntaxWML<br />
e.g. for secondary expansion, where it does the piped ones first<br />
$$Vx|_$Vy|_$vill_slot_sur|<br />
$villconq__$Vx|_$Vy|_$vill_slot_sur|<br />
the 0x2D causes “Invalid” savegames when present in other id= Remarks than the unit_type ones. envars too, at least.<br />
it doesn't strip cartouchiers like most shells do.<br />
0x5E in a string of text will cause it and all text preceding it in that string to be not displayed. it becomes the new Start–Of.<br />
<p>The full name of a scalar variable is its given name, in this case <i>my_variable</i>. Note that the value of the variable can be translatable or even a formula expression (<a rel="nofollow" class="external text" href="http://wiki.wesnoth.org/SyntaxWML#Special_Attribute_Values">Special Attribute Values</a>).<br />
wrong wiki link form<br />
automatically stored envars, e.g.<br />
x1<br />
are cleared regularly and often.<br />
the newline is preserved within the cartouche and it isn't treated as a partition in these cases:<br />
#define _fac coject nation variant edition<br />
{~add-ons/{coject}/rsrc/faction/{nation}_{variant}_ed-{edition} }<br />
#enddef<br />
#define mne-Merf<br />
faction_TBFW-Merfolk_CnF<br />
#enddef<br />
{_fac {mne-Merf} Merfolk shallows 1-0 }<br />
0x20 & 0x5F<br />
• i've seen some Add–on which appeared as though they expected that Wesnoth substituted the two freely. however, when i attempted something which referenced a [unit_type]id=Vampire_Bat<br />
Error loading game configuration files. The game will now exit.<br />
Details:<br />
unit type not found: Vampire_Bat<br />
then, again, with [advancefrom]unit=Vampire_Bat<br />
Error loading game configuration files. The game will now exit.<br />
Details:<br />
unit type 'Vampire_Bat' not found when resolving [advancefrom] tag for 'test'<br />
the Add–on was one from Wesnoth_1-10 or earlier or so, and i can't remember exactly where i saw it use the 0x5F in a type ident, but i did see it use that in the [ai]recruitment_pattern= when it had<br />
mixed_fighter<br />
or so. that was probably a simple error which, of course, wouldn't be terminal.<br />
• it does convert the two for Event names, as noted already.<br />
<br />
ThemeWML<br />
index.php?title=ThemeWML&oldid=56254<br />
doesn't mention the ‘whiteboard’ actions, e.g.<br />
wbexecuteallactions<br />
wbexecuteaction<br />
wbdeleteaction<br />
<br />
UnitTypeWML<br />
level: the amount of upkeep the unit costs. After this unit fights, its opponent gains 'level' experience. See also kill_experience (GameConfigWML), and leadership (AbilitiesWML).<br />
? so this is the gains when an enemy survives? why not give it a more intuitive name, then? is this also the gold upkeep?<br />
[attack] parry=<br />
the wiki says this is used offensively. ugh. please tell me that it is incorrect.<br />
<br />
UnitsWML<br />
[movetype] [movement_costs]<br />
the range is 0..100?<br />
giving this a value of 0, is interpreted as a 1.<br />
if a type is not declared here, then it defaults to some value which make movement impossible.<br />
<br />
WML_for_Complete_Beginners:_Chapter_11<br />
“ Talk about basic parts of loops, variations of loops (do/while, etc.)<br />
“ heh. anyway, the problem is that it lacks a TODO prefix or header.<br />
<br />
§ § overall, the root of many paths is rarely given.<br />
! this is the [binary_path], as i understand it.<br />
all this section is useless.<br />
<br />
[message] image=<br />
apparently, these are rooted at $(wesnoth --data-path)/data/core/images/. but such is only inferrable, not documented.<br />
<br />
PblWML<br />
icon=<br />
this is rooted at $(wesnoth --data-path)/images/. — i do remember noting this when i studied it.<br />
this is the sequence, more or less, at which the Add–on server expected the requisite items and either complained or suppled them (passphrase); icon= was already provided:<br />
passphrase=<br />
"viczuggt"<br />
title=<br />
"do_not_download"<br />
description=<br />
"this is a cheap way to avoid use of the image tester."<br />
type=<br />
"other"<br />
author=<br />
"anonymous"<br />
version=<br />
"0"<br />
email=<br />
"slarti.blartfast@magrathea.plt"<br />
<br />
§ §<br />
<br />
[binary_path]<br />
each new addition in a scope|theater is …<br />
<br />
[color_range]<br />
from team-colors.cfg<br />
<br />
recruit<br />
extra_recruit<br />
the one belongs to a Side, whereas the other belongs to a Cmdr<br />
<br />
Wesnoth reads, and applies in the scope|theater, Modifications by the order that they are enabled.<br />
<br />
scope | theater scenario<br />
this concept should be discussed. …<br />
<br />
minimap_terrain_coding=no<br />
this is counterintuitive. you'd expect that “terrain coding” is what it does when the above condition is set: show terrain by its major type, not a smaller tile. impassable and unwalkable are variations of red, flat is green, paths are cyan, water is blue, et c.<br />
these must be defined somewhere with the terraintypes. they can't be hardcoded.<br />
concurrent with this is the icon for a Side during their Turn. rather than show their flag, it will then show a little bevelled square with their color in a bar.<br />
<br />
<span> mark–up does not work with<br />
[multiplayer] description=<br />
shown verbatim — no parsing.<br />
[era] name=<br />
"<span color='#0000FF'>Watery theme:</span><br />
<span color<br />
Kate accenting the syntax also shows a single Error underline for the text–unit immediately succeeding the 0x3D. it doesn't do so when the span is used deep in the description= trial (previous).<br />
and probably so for others; [message] is probably the only one that uses it.<br />
using the older <0,0,0> for color doesn't work with<br />
[era] description=<br />
but it did somewhat work with<br />
[multiplayer] name=<br />
shows the color but also displays the code.<br />
the <i></i> was tested with<br />
[era] description=<br />
no parsing.<br />
! but why, then, does the Kate syntax Highlighting show the <i> as not colored with the cartouched text?<br />
i also recall that it <0,0,0> did not show any color for<br />
[era] name=<br />
maybe color only works for start of a string? alas, you can't do<br />
[multiplayer_side] name="EotF - " + <255,255,0>"Brungar"<br />
EotF - <255,255,0>Brungar<br />
<br />
values for gold are rounded to the 25.<br />
<br />
map editor<br />
? the Map Editor will remember placement of participant sites even if you resize the map and lose those.<br />
How can we create hilly forest in map editor now?<br />
Place the hills, then hold down [Shift] while you place the trees. In the same way, you can place any overlay terrain (like forests, bridges or villages) on top of any base terrain (like mountains, caves or oceans).<br />
<br />
if you have several Eras which use the same identifier, then you will see each distinct entity in the list — showing any differences in their internal data i.e. Name — but will only be able to select the first one.<br />
<br />
identifier names<br />
sometimes it seems that it tolerates non-ASCII — but i wasn't thorough it verifying that it did. other times it seemed to cause problems much like invalid envar names.<br />
<br />
§ § “error config: Unexpected characters at line start”<br />
<br />
! first, it should be reporting what is the unexpected text, yes? as shown below, sometimes it is not obvious.<br />
<br />
#define example<br />
_ "this"<br />
#enddef<br />
[something]<br />
\ description = _"example<br />
<br />
"+ {example}<br />
<br />
#define example<br />
example<br />
#enddef<br />
description=_"test<br />
"+{example}<br />
◊ okay, but the 0x09 doesn't display properly.<br />
<br />
#define example<br />
_ "example"<br />
#enddef<br />
description=_"test<br />
"+{example}<br />
◊ okay.<br />
<br />
#define example<br />
_ "example"<br />
#enddef<br />
description=_"test<br />
"+{example}<br />
◊ okay.<br />
<br />
#define example<br />
_ "example"<br />
#enddef<br />
description=_ "test<br />
"+{example}<br />
◊ okay.<br />
<br />
#define example<br />
_ "example"<br />
#enddef<br />
description= _ "test<br />
"+{example}<br />
◊ okay<br />
<br />
#define example<br />
_ "example"<br />
#enddef<br />
description = _ "test<br />
"+{example}<br />
◊ okay<br />
<br />
#define example<br />
_ "example"<br />
#enddef<br />
description = _ "test<br />
<br />
"+{example}<br />
◊ okay<br />
<br />
#define example<br />
_ "example"<br />
#enddef<br />
description = _ "test<br />
<br />
"+ {example}<br />
◊ okay<br />
<br />
#define CnF_mod_village-conquest_read-order-instruction<br />
_ "example"<br />
#enddef<br />
description = _ "test<br />
<br />
"+ {CnF_mod_village-conquest_read-order-instruction}<br />
◊ okay<br />
<br />
{example}+<br />
◊ that's it.<br />
◊ i suppose that it is inserting the newline prior to the 0x2B.<br />
◊ you can always simply include the snippet inside the cartouche, but that would make you unable to prefix it as a translatable string.<br />
◊ best thing to do is to provide the + in the snippet.<br />
</nowiki></div>Cannedfoodhttps://wiki.wesnoth.org/index.php?title=ScenarioWML&diff=58723ScenarioWML2017-07-27T11:11:37Z<p>Cannedfood: /* Scenario End Conditions */ corrected typo “of” -> ‘or’</p>
<hr />
<div>{{WML Tags}}<br />
== the toplevel tags [multiplayer], [test], [tutorial], [scenario] ==<br />
<br />
The top level tags '''[multiplayer]''', '''[test]''', '''[tutorial]''' and '''[scenario]''' are all formatted the same way.<br />
The difference between these tags is the way that the scenarios they describe are accessed.<br />
<br />
The keys '''id''' and '''next_scenario''' affect how scenarios can be accessed.<br />
Whenever a scenario is won, the scenario with id=''next_scenario'' of the same tag type will be played.<br />
Units from the first scenario will be available for recall in the second.<br />
<br />
Some scenarios can be played without playing other scenarios first<br />
(in this case there is nothing on the recall list).<br />
These scenarios are called ''initial scenario''s.<br />
<br />
A list of initial scenarios, and how to access them:<br />
<br />
* All '''[multiplayer]''' scenarios (without ''allow_new_game=no'') are initial scenarios listed in the multiplayer scenario selector screen (accessed by the "multiplayer" button).<br />
<br />
* Any '''[test]''' scenario is an initial scenario. A test scenario can be accessed by running the game in test mode. (note: this is NOT the same as debug mode. It can be accessed using -t or --test followed by an optional scenario ID which defaults to 'test'.)<br />
<br />
* The '''[tutorial]''' scenario with the attribute '''id=tutorial''' is an initial scenario. The tutorial is accessed by clicking on the "tutorial" button.<br />
<br />
* Any '''[scenario]''' scenario with an id listed in the value of ''first_scenario'' in a campaign tag (see [[CampaignWML]]) is an initial scenario accessed by selecting that campaign after clicking on the "campaign" button.<br />
<br />
== The [scenario] tag ==<br />
<br />
The following keys and tags are recognized in '''[scenario]''' tags:<br />
<br />
* '''id''': A unique identifier for this scenario. All scenarios must have an id. Can't clash with '''id''' used in '''[multiplayer]''' tags.<br />
<br />
* '''next_scenario''': The id of the scenario to load when the current one is won. This can be changed dynamically, to build non-linear campaigns.<br />
<br />
* '''description''': (translatable) only for multiplayer maps. Will show up as a tooltip when mousing over the minimap in the multiplayer setup screen.<br />
<br />
* '''name''': (translatable) is shown in several places in the level, including the intro screen. It is also the default name for saves on the level.<br />
<br />
* '''map_data''': inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.<br />
<br />
* '''turns''': sets an event on turn ''turns'' causing the player to lose. Use ''-1'' to have no turn limit (default). See also [[EventWML]]<br />
<br />
* '''turn_at''': the turn to start on (default=1)<br />
<br />
: Note that none of the regular start-of-turn behavior, including poison damage, healing, income and refreshing unit movement and status, will occur before the start of turn 2. All start-of-turn [[EventWML|WML events]] will still be fired, however.<br />
<br />
* '''random_start_time''': controls random starting time of day. Possible values are yes and no or list of possible start times; starting from 1 to number of times. for example ''random_start_time=2,3,5,6'' (default depends on version and mp/sp, better include this key)<br />
<br />
* '''music''': the music file relative to ''./music/'' to play during the scenario<br />
<br />
* '''[music]''': specifies the music tracks to play during this scenario, see [[MusicListWML]].<br />
<br />
* '''defeat_music''': specifies a comma-separated list of music tracks which may be chosen to play on defeat. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.<br />
<br />
* '''victory_music''': specifies a comma-separated list of music tracks which may be chosen to play on victory. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.<br />
<br />
* '''theme''': the name of the UI theme that should be used when playing this scenario.<br />
<br />
* '''victory_when_enemies_defeated''': when this is set to '''yes''' (default), the player wins once all non-allied units with '''canrecruit=yes''' (aka leaders) are killed. (Currently this only controls the win condition for when all enemies are defeated; it does not prevent the player from losing if he has no leader.) See Also [[SideWML]]. When this value is true the following keys can be used:<br />
** '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.<br />
** '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.<br />
<br />
* '''remove_from_carryover_on_defeat''': when this is set to '''yes''' (default), for sides who got defeated (according to the side.defeat_condition), carryover will be removed.<br />
<br />
* '''disallow_recall''': when this is set to 'no'(default), the player is allowed to recall units from previous scenarios.<br />
<br />
* '''experience_modifier''': the percentage that required XP to level up (for all units in the scenario) is multiplied by. Default 100. Note that when used in a campaign, weird things (like units being above the required XP to level up) can happen if this value is different for different scenarios.<br />
<br />
* '''[story]''': describes the intro screen. See [[IntroWML]]<br />
<br />
* '''[label]''': sets a label<br />
** '''x''', '''y''': location to set label<br />
** '''text''': the label<br />
<br />
* '''[item]''': places an item on map. See [[InterfaceActionsWML#.5Bitem.5D|InterfaceActionsWML]].<br />
<br />
* '''[time]''': how a day should progress. See [[TimeWML]]<br />
<br />
* '''current_time''': The time of day slot number (starting from zero) active at scenario start.<br />
<br />
* '''[time_area]''': how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag<br />
** takes x and y coordinates.<br />
** '''[time]''': how a day should progress in those locations. See [[TimeWML]]<br />
** '''current_time''': The time slot number (starting with zero) active at the creation of the area.<br />
** time areas can be used in events, assigned identifiers, and removed at discretion. They also accept complete Standard Location Filters. See [[DirectActionsWML]].<br />
<br />
* '''[side]''': describes one player. See [[SideWML]]<br />
<br />
* '''[event]''': describes an event that may be triggered at a certain point of the scenario. See [[EventWML]]<br />
<br />
* '''map_generation''': another way to generate a map. The map will be generated randomly<br />
** '''default''': the default random map generator<br />
<br />
* '''[generator]''' if this is present, the map and scenario will be generated randomly. See [[MapGeneratorWML]]<br />
<br />
== The [multiplayer] tag ==<br />
<br />
The following keys and subtags are additionally recognized in '''[multiplayer]''' scenarios:<br />
<br />
* '''force_lock_settings''': provides a default value for [[SideWML]] ''lock'' attributes and forces the "Use map settings" to be checked and disabled. This is useful if author wants to limit game customization in order to keep the scenario/campaign balanced. Individual options can still be enabled if this key is set to '''yes'''. E.g. color selection can be enabled by explicitly setting ''color_lock=yes'' in [[SideWML]].<br />
* '''new_game_title''': if provided will be used instead of '''name''' for campaign entry points.<br />
* '''allow_new_game''': (default=yes) allow/prevent the scenario to be listed in the game configuration screen. This is intended for multiplayer campaigns with multiple entry points.<br />
* '''allow_era''': a list of era ids. Only the eras with matching ids will be allowed to be played with this scenario.<br />
* '''disallow_era''': a list of era ids. Only the eras with matching ids will not be allowed to be played with this scenario. Cannot be used in parallel with allow_era.<br />
* '''ignore_incompatible_era''': a list of era ids. The eras with matching ids will be considered compatible with this scenario regardless their dependencies.<br />
* '''allow_modification''': same as allow_era, but for modifications.<br />
* '''disallow_modification''': same as disallow_era, but for modifications. Cannot be used in parallel with allow_modification.<br />
* '''ignore_incompatible_modification''': same as ignore_incompatible_era, but for modifications.<br />
* '''force_modification''': a list of modification ids. The specified modifications must be enabled to play this scenario.<br />
* '''[options]''': custom options. See [[OptionWML]] for details.<br />
* '''require_scenario''': {{DevFeature1.13|0}} In a multiplayer scenario, this indicates that the scenario file is not enough (you have custom assets like terrain or additional unit art) and other player must download the full add-on not just the scenario WML to join a game. This will also mean that the '''addon_min_version''' attribute will control the minimum version number of your add-on which is compatible with this version.<br />
<br />
== The [test] tag ==<br />
<br />
The following keys and subtags are additionally recognized in '''[test]''' scenarios:<br />
<br />
* '''is_unit_test''': {{DevFeature1.13|8}} If set to 'yes', this scenario will not appear in the list of test scenarios. The list of test scenarios can be reached from the titlescreen via the Start Test Scenario hotkey. This hotkey is not set by default.<br />
<br />
== Scenario End Conditions ==<br />
<br />
In this section we will give a more precise explanation of things that can cause a scenario to end.<br />
<br />
* At the '''end of every turn''', the turn number will be compared with the turn limit. <br />
** If we pass the limit, the ''time over'' event will fire. If turns are not added by WML in response to this event, then the scenario will immediately end in defeat. [[EventWML#The_.27name.27_Key_.28Mandatory.29]]<br />
* At the '''beginning of any turn''', and at '''the end of any user or ai action''', the victory conditions will be checked. This will result either in the scenario ending or continuing. The procedure for this is as follows:<br />
** Every side will have its ''defeat_condition'' evaluated based on the units it currently has on the board. [[SideWML]]<br />
*** At this time, villages of defeated sides will be unflagged, and if ''remove_from_carryover_on_defeat = yes'' then their carryover will be cleared as well.<br />
** If any two not-defeated sides are enemies, the scenario will continue.<br />
*** At this time, the ''enemies defeated'' event will fire.<br />
** Furthermore, if ''victory_when_enemies_defated=no'' and there exists a human controlled side, then the scenario will continue.<br />
*** The human controlled side may be local or remote, for networked mp play.<br />
** If neither of these conditions is met then the scenario will end. <br />
***In victory or defeat according to whether a local human-controlled side is not defeated.<br />
<br />
== See Also ==<br />
<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Cannedfood