https://wiki.wesnoth.org/api.php?action=feedcontributions&user=Voris&feedformat=atomThe Battle for Wesnoth Wiki - User contributions [en]2024-03-28T12:49:24ZUser contributionsMediaWiki 1.31.16https://wiki.wesnoth.org/index.php?title=PblWML&diff=30048PblWML2009-04-08T23:24:27Z<p>Voris: Added examples section, added warning about version numbrers.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
To upload a campaign you have made, you need a .pbl file.<br />
<br />
This is a file with name '''data/campaigns/''campaign-name''.pbl'''. [http://exong.net/wesnoth-attach/files/pblexample_111.png Click here for an example of what we're talking about.]<br />
<br />
When you upload a campaign, the file '''data/campaigns/''campaign-name''.cfg'''<br />
and the directory '''data/campaigns/''campaign-name''/''' will be published.<br />
Your campaign must be based entirely on these files.<br />
This may cause your campaign not to upload properly,<br />
for example, if you have custom campaign units in '''data/units/'''.<br />
Be aware that translations in the .pbl-files are '''not''' working, so don't mark these strings translateable.<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 on the "download campaigns" screen. It must be a standard Wesnoth graphic and not a custom one. (Well, a custom graphic will work if the user already has the campaign installed, or if it is a custom graphic from a different campaign that the user has installed.) (Note that the icon used to display your campaign for when it is played can be custom; for more information see [[CampaignWML]].) If the icon is a unit with magenta color, please use [[ImagePathFunctionWML]] to team-color 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 campaign when it is played.<br />
<br />
=== version ===<br />
: Displayed to the right of the title, it is just text. However, starting with Wesnoth 1.6, the ''required'' format is x.y.z where x, y and z are numbers and a value for x greater than 0 implies the campaign is complete and balanced. Trailing non-numeric elements are ok, but nothing should appear ''before'' the numbers. This is necessary for the ''Update add-ons'' button to work correctly. ([[#Version Key Examples|See Examples]])<br />
<br />
=== author ===<br />
: Displayed to the right of the version, it is just text. Put your name or nickname here. If several people have contributed significantly to the campaign you should list all of their names and perhaps describe what each person was responsible for.<br />
<br />
=== passphrase ===<br />
: Not displayed, it prevents others from modifying the version of your campaign on the campaign server. You do not need to input a passphrase when initially publishind a campaign; if you do not, one will be randomly generated for you.<br />
<br />
=== description ===<br />
: Is not displayed in the client but it ''is'' visible on the web interface to the campaign server. It can be used to give a brief description of your campaign and, for pre 1.0 versions, let people know how playable it is.<br />
<br />
=== dependencies ===<br />
: An optional list of dependencies. ([[#Dependency Key Example|See Example]])<br />
<br />
=== translate ===<br />
: If set to '''true''', the campaign will be sent to and updated with Wescamp (NOTE: this is a new and experimental function, which will automatically update the translations in your campaign. Make sure you make backups of your campaign in case of problems.)<br />
<br />
=== type ===<br />
: Indicates the type of the add-on, used for the downloads manager dialog. Possible values are:<br />
<br />
:* ''campaign'': single player campaign.<br />
:* ''scenario'': single player scenario.<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.<br />
:* media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.<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 ''highly'' recommended that you provide one in case you need to be contacted about your addon.<br />
<br />
<br />
The campaign server keeps track of some other information about uploaded campaigns, 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 addon 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 />
<br />
version="0.11.4"<br />
<br />
version="0.1.4beta"<br />
<br />
version="1.5c"<br />
<br />
<br />
The following are examples of '''bad''' version values:<br />
<br />
version="Beta1.5"<br />
<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 />
<br />
1.5 < 1.5c<br />
<br />
1.0 < 1.0.1<br />
<br />
1.0c < 1.0.1a<br />
<br />
1.0.1a < 1.0.1c<br />
<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"<br />
description="You get to kill a lot of bad guys. But only the first map is done."<br />
email="name@example.com"<br />
<br />
== See Also ==<br />
<br />
* [[ReferenceWML]]<br />
* [[BuildingCampaignsThePBLFile]]<br />
* [[CampaignServerWML]]<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=PblWML&diff=30046PblWML2009-04-08T22:25:09Z<p>Voris: /* What goes into a .pbl file? */</p>
<hr />
<div>{{WML Tags}}<br />
== .pbl files ==<br />
<br />
=== What is a .pbl file? ===<br />
To upload a campaign you have made, you need a .pbl file.<br />
<br />
This is a file with name '''data/campaigns/''campaign-name''.pbl'''. [http://exong.net/wesnoth-attach/files/pblexample_111.png Click here for an example of what we're talking about.]<br />
<br />
When you upload a campaign, the file '''data/campaigns/''campaign-name''.cfg'''<br />
and the directory '''data/campaigns/''campaign-name''/''' will be published.<br />
Your campaign must be based entirely on these files.<br />
This may cause your campaign not to upload properly,<br />
for example, if you have custom campaign units in '''data/units/'''.<br />
Be aware that translations in the .pbl-files are '''not''' working, so don't mark these strings translateable.<br />
<br />
=== What goes into a .pbl file? ===<br />
<br />
'''Note: ''You should ''not'' use special formatting or coloring in any fields when uploading to the official server.'''''<br />
<br />
The following keys are recognized for .pbl files:<br />
<br />
* '''icon''': An image, displayed leftmost on the "download campaigns" screen. It must be a standard Wesnoth graphic and not a custom one. (Well, a custom graphic will work if the user already has the campaign installed, or if it is a custom graphic from a different campaign that the user has installed.) (Note that the icon used to display your campaign for when it is played can be custom; for more information see [[CampaignWML]].) If the icon is a unit with magenta color, please use [[ImagePathFunctionWML]] to team-color it.<br />
<br />
* '''title''': Displayed to the right of the icon, it is just text. It should usually be the same as the name of your campaign when it is played.<br />
<br />
* '''version''': 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 campaign is complete and balanced. Trailing non-numeric elements are ok, but nothing should appear ''before'' the numbers! ([[#Version Key Example|See Examples]])<br />
<br />
* '''author''': 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 campaign you should list all of their names and perhaps describe what each person was responsible for.<br />
<br />
* '''passphrase''': Not displayed, it prevents others from modifying the version of your campaign on the campaign server. You do not need to input a passphrase when initially publishind a campaign; if you do not, one will be randomly generated for you.<br />
<br />
* '''description''': Is not displayed in the client but it ''is'' visible on the web interface to the campaign server. It can be used to give a brief description of your campaign and, for pre 1.0 versions, let people know how playable it is.<br />
<br />
* '''dependencies''': An optional list of dependencies. For example:<br />
dependencies=Imperial_Era,Era_of_Myths <br />
: This could be used when the two specified add-ons need to be installed for a campaign to work.<br />
<br />
* '''translate''': If set to '''true''', the campaign will be sent to and updated with Wescamp (NOTE: this is a new and experimental function, which will automatically update the translations in your campaign. Make sure you make backups of your campaign in case of problems.)<br />
<br />
* '''type''': Indicates the type of the add-on, used for the downloads manager dialog. Possible values are:<br />
** ''campaign'': single player campaign.<br />
** ''scenario'': single player scenario.<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.<br />
** ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.<br />
<br />
* '''email''': 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 '''highly''' recommended that you provide one in case you need to be contacted about your addon.<br />
<br />
Example:<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"<br />
description="You get to kill a lot of bad guys. But only the first map is done."<br />
email="name@domain.ltd"<br />
<br />
The campaign server keeps track of some other information about uploaded campaigns, 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 />
== See Also ==<br />
<br />
* [[ReferenceWML]]<br />
* [[BuildingCampaignsThePBLFile]]<br />
* [[CampaignServerWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InterfaceActionsWML&diff=29721InterfaceActionsWML2009-04-03T02:42:06Z<p>Voris: /* Macros */ Updated links for macro examples.</p>
<hr />
<div>{{WML Tags}}<br />
== Interface actions ==<br />
<br />
Interface actions are actions that do not have an 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 />
== [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. 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 description 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''': 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 />
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.<br />
* '''image''': (default: profile image of speaker) the image to display next to the message.<br />
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed.<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]''': zero or more '''[option]''' elements may be present. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.<br />
** ''message'' (translatable) the text displayed for the option (see [[DescriptionWML]])<br />
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[InternalActionsWML]])<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.<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_chars''': 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 />
* note that '''[option]''' and '''[text_input]''' can only be used in moveto events in MP, otherwise they cause OOS<br />
<br />
Text formatting options for '''[message]'''. These can also be used in unit names (user_description), objectives, and such.<br />
* A tilde (~) as the first character causes the line to be boldfaced.<br />
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.<br />
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.<br />
* An asterisk (*) as the first character causes the line to be bigger.<br />
* A backquote (`) as the first character causes the line to be smaller.<br />
* If used, the caption key text is boldfaced.<br />
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''<br />
<br />
{{DevFeature}} In the 1.7 branch these formatting codes are being discarded in favor of [http://pygtk.org/docs/pygtk/pango-markup-language.html Pango] markup. Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand. At the mement, Pango markup only works in '''message=''' attributes within '''[message]''' tags. More attributes within other tags will be enabled in the future.<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 />
This tag renders the ''objectives'' attribute of [scenario] obsolete (see ''objectives'', [[ScenarioWML]]).<br />
Instead of using ''objectives'', use '''[objectives]''' to set scenario objectives inside a prestart event.<br />
It can also be used to overwrite the starting objectives mid-scenario.<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.<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.<br />
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives.<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 />
<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 />
** '''description''': text for the specific win or loss condition.<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 />
<br />
=== Macros ===<br />
There are a few predefined macros for Objectives that you can use to shorten the code: [http://www.wesnoth.org/macro-reference.xhtml#SET_OBJECTIVES SET_OBJECTIVES], [http://www.wesnoth.org/macro-reference.xhtml#VICTORY_CONDITION VICTORY_CONDITION], and [http://www.wesnoth.org/macro-reference.xhtml#DEFEAT_CONDITION DEFEAT_CONDITION]. Follow the links for each one to see complete syntax and example usage.<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.<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 false.<br />
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[InternalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.<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 />
* '''[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 />
<br />
== Other interface tags ==<br />
<br />
The following tags are also action tags:<br />
* '''[item]''': makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros))''</tt><br />
** '''x''', '''y''': the location to place the item.<br />
** '''image''': the image (in ''images/'' as .png) to place on the hex.<br />
** '''halo''': an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex.<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 />
* '''[removeitem]''': removes any graphical items on a given hex<br />
** '''x''', '''y''': the hex to remove items off<br />
** '''image''' if specified, only removes the given image item<br />
* '''[print]''': 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.<br />
* '''[move_unit_fake]''': moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.<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 />
* '''[hide_unit]''': makes the given unit become invisible. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Each '''[hide_unit]''' tag only hides one unit.<br />
** '''x''', '''y''': location of the unit to be hidden. (NOT a standard unit filter! Just x and y.)<br />
* '''[unhide_unit]''': stops the currently hidden unit from being hidden.<br />
* '''[scroll]''': 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 />
* '''[scroll_to]''': Scroll to a given hex<br />
** '''x''', '''y''': the hex to scroll to<br />
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.<br />
* '''[scroll_to_unit]''' Scroll to a given unit<br />
** [[StandardUnitFilter]]<br />
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.<br />
* '''[sound]''': Plays a sound<br />
** '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)<br />
** '''repeat''': repeats the sound for a specified additional number of times (default=0)<br />
* '''[sound_source]''': Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.<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 "true" and "false" - if true the source will not play if its locations are fogged/shrouded<br />
** '''x,y''': a [[StandardLocationFilter]] for 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 />
* '''[remove_sound_source]''': Removes a previously defined sound source.<br />
** '''id''': the identification key of the sound source to remove<br />
* '''[music]''': 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 />
* '''[colour_adjust]''': tints the colour of the screen.<br />
** '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each colour<br />
* '''[delay]''': pauses the game<br />
** '''time''': the time to pause in milliseconds<br />
* '''[redraw]''': redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).<br />
** '''side''': if used, recalculates fog and shroud for that side. Useful if you for example spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).<br />
* '''[unit_overlay]''': sets an image that will be drawn over a particular unit, and follow it around<br />
** '''x''', '''y''': the location of the unit to overlay on<br />
** '''image''': the image to place on the unit<br />
* '''[remove_unit_overlay]''': removes a particular overlayed image from a unit<br />
** '''x''', '''y''': the location of the unit to remove an overlay from<br />
** '''image''': the image to remove from the unit<br />
* '''[animate_unit]''': uses the custom animation of a unit to animate it on screen (if the unit has the corresponding animation)<br />
** '''flag''': the key to find the good custom animation in the unit description see the '''[extra_anim]''' description in [[AnimationWML]] Standar anims can be triggered with the following keywors ''leading recruited standing idling levelin levelout healing healed poisoned movement defend attack death victory pre_teleport post_teleport''<br />
** '''[filter]''': a [[StandardUnitFilter]] 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<br />
** '''[secondary_attack]''': same for the second attack<br />
** '''hits''': the hit type to filter unit on<br />
** '''text''': a text to hover during the animation<br />
** '''red''': red value for the text color<br />
** '''green''': green value for the text color<br />
** '''blue''': blue value for the text color<br />
** '''with_bars''': whether to display the status bars or not.<br />
** '''[animate]''': a sub block with the same syntax as the '''[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 />
* '''[label]''' places a label on the map.<br />
** '''x''', '''y''': the location of the label<br />
** '''text''': what the label should say<br />
** '''team_name''': if specified, the label will only be visible to the given team.<br />
** '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.<br />
* '''[deprecated_message]''' shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.<br />
** '''message''': the message to show.<br />
* '''[wml_message]''' outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.<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 />
* '''[open_help]''' opens the in-game help.<br />
** '''topic''': the id of the topic to open<br />
* '''[show_objectives]''': {{DevFeature}} shows the objectives screen. Has the same effect as if [objectives] were used to replace them with an exact duplicate.<br />
** '''side''': the side to show the objectives. If not set, all sides are used.<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 />
* '''{FLOATING_TEXT}''' Float some text over a unit similar to the damage numbers.<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>. ('''{TREMOR}''' is a deprecated version, equivalent to '''{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>Vorishttps://wiki.wesnoth.org/index.php?title=EventWML&diff=29275EventWML2009-03-25T13:49:07Z<p>Voris: /* Valid 'name' Key Values */ Strengthened the language noting the requirement for first_time_only=no for preload.</p>
<hr />
<div>{{WML Tags}}<br />
== The [event] Tag ==<br />
<br />
This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.<br />
<br />
This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.<br />
<br />
=== The 'name' Key (Mandatory) ===<br />
<br />
Usage:<br />
name=<value><br />
<br />
This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.<br />
<br />
'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''<br />
<br />
The '''name''' key can accept a list of comma separated values describing when the event will be triggered.*<br />
<br />
For example:<br />
<br />
name=attacker_misses,defender_misses<br />
<br />
''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''<br />
<br />
==== Valid 'name' Key Values ====<br />
<br />
All valid values are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here will '''not''' work ''no matter how logical or awesome you think it sounds.''<br />
<br />
; preload {{DevFeature}}<br />
: Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.<br />'''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.<br />
<br />
; prestart<br />
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.<br />'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''<br />
<br />
; start<br />
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.<br />'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''<br />
<br />
; new turn<br />
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.<br />
<br />
; side turn<br />
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.<br />
<br />
; ai turn<br />
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.<br />
<br />
; turn refresh<br />
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.<br />
<br />
; turn ''X''<br />
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.<br />
<br />
; time over<br />
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])<br />
<br />
; enemies defeated<br />
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.<br />
<br />
; victory<br />
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])<br />
<br />
; defeat<br />
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])<br />
<br />
<br />
Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true. <br />
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]<br />
<br />
; moveto<br />
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.<br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' {{DevFeature}} $x2 and $y2 refer to the hex the unit came from.<br />
<br />
; sighted<br />
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)<br />
<br />
; attack<br />
: Triggers when the primary unit attacks the secondary unit.<br />
<br />
; attack_end<br />
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.<br />
<br />
; attacker_hits<br />
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.<br />
<br />
; attacker_misses<br />
: Same as ''attacker_hits'', but is triggered when the attacker misses.<br />
<br />
; defender_hits<br />
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.<br />
<br />
; defender_misses<br />
: Same as ''defender_hits'', but is triggered when the defender misses.<br />
<br />
; stone<br />
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).<br />
<br />
; last breath<br />
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.<br />
<br />
; die<br />
: Triggers when the primary unit is killed by the secondary unit.<br />
<br />
; capture<br />
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.<br />
<br />
; recruit<br />
: Triggers when the primary unit is recruited. (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).<br />
<br />
; prerecruit<br />
: Triggers when the primary unit is recruited but before it is displayed.<br />
<br />
; recall<br />
: Triggers after a unit is recalled.<br />
<br />
; prerecall<br />
: Triggers when a unit is recalled but before it is displayed.<br />
<br />
; advance<br />
: Triggers just before the primary unit is going to advance to another unit.<br />
<br />
; post_advance<br />
: Triggers just after the primary unit has advanced to another unit.<br />
<br />
; select<br />
: Triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''<br />
<br />
; menu item X<br />
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''<br />
<br />
; Other events with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag.<br />
<br />
=== Optional Keys and Tags ===<br />
<br />
These keys and tags are more complex ways to filter when an event should trigger:<br />
<br />
==== first_time_only ====<br />
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:<br />
: ''first_time_only=yes''<br />
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.<br />
: ''first_time_only=no''<br />
:: The event will every time the criteria are met instead of only the first time.<br />
<br />
==== [filter] ====<br />
: The event will only trigger if the primary unit matches this filter.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_second] ====<br />
: Like [filter], but for the secondary unit.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_attack] ====<br />
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''.<br />
:* '''name''': the name of the weapon used.<br />
:* '''range''': the range of the weapon used. <br />
<br />
==== [filter_second_attack] ====<br />
: Like [filter_attack], but for the secondary unit.<br />
:* '''name''': the name of the weapon used.<br />
:* '''range''': the range of the weapon used.<br />
<br />
==== [event] ====<br />
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].<br />
<br />
==== delayed_variable_substitution ====<br />
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.<br />
<br />
=== Actions triggered by [event] ===<br />
<br />
After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.<br />
<br />
There are 3 main types of actions:<br />
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay<br />
* display actions ([[InterfaceActionsWML]]) which show something to the user<br />
* internal actions ([[InternalActionsWML]]) which are used by WML internally<br />
<br />
Several actions use standard filters to find out which units<br />
to execute the command on. These are denoted by the phrases<br />
"standard unit filter" and "standard location filter".<br />
<br />
=== Nested Events ===<br />
<br />
There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).<br />
<br />
([[#Nested Event Example|See Examples]])<br />
<br />
==== Delayed Variable Substitution ====<br />
<br />
Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.<br />
<br />
If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.<br />
<br />
This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.<br />
<br />
([[#Delayed Variable Substitution Example|See Examples]])<br />
<br />
== Miscellaneous Notes and Examples ==<br />
<br />
=== Primary/Secondary Unit Speaker Example ===<br />
<br />
In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:<br />
<br />
[event]<br />
name=die<br />
[message]<br />
speaker='''second_unit'''<br />
message= _ "Hahaha! I finally killed you!"<br />
[/message]<br />
<br />
[message]<br />
speaker='''unit'''<br />
message= _ "It's not over yet! I'll come back to haunt you!"<br />
[/message]<br />
[/event]<br />
<br />
=== Nested Event Example ===<br />
<br />
An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
# moving to 5,8 will trigger this event only on turn 10 and after<br />
[/event]<br />
[/event]<br />
<br />
An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.<br />
<br />
=== Delayed Variable Substitution Example ===<br />
<br />
This code will display the turn on which the nested ''moveto'' event happens.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=yes<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
This code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Finally, this example is identical to the first two, in that it will display the turn on which the nested ''moveto'' event happens despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $|turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
== See Also ==<br />
<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[FilterWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=EventWML&diff=29249EventWML2009-03-25T01:47:03Z<p>Voris: /* Valid 'name' Key Values */ Added clarification about first_time_only to (pre)load/start events.</p>
<hr />
<div>{{WML Tags}}<br />
== The [event] Tag ==<br />
<br />
This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.<br />
<br />
This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.<br />
<br />
=== The 'name' Key (Mandatory) ===<br />
<br />
Usage:<br />
name=<value><br />
<br />
This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.<br />
<br />
'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''<br />
<br />
The '''name''' key can accept a list of comma separated values describing when the event will be triggered.*<br />
<br />
For example:<br />
<br />
name=attacker_misses,defender_misses<br />
<br />
''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''<br />
<br />
==== Valid 'name' Key Values ====<br />
<br />
All valid values are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here will '''not''' work ''no matter how logical or awesome you think it sounds.''<br />
<br />
; preload {{DevFeature}}<br />
: Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.<br />'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''<br />
<br />
; prestart<br />
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.<br />'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''<br />
<br />
; start<br />
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.<br />'''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''<br />
<br />
; new turn<br />
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.<br />
<br />
; side turn<br />
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.<br />
<br />
; ai turn<br />
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.<br />
<br />
; turn refresh<br />
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.<br />
<br />
; turn ''X''<br />
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.<br />
<br />
; time over<br />
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])<br />
<br />
; enemies defeated<br />
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.<br />
<br />
; victory<br />
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])<br />
<br />
; defeat<br />
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])<br />
<br />
<br />
Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true. <br />
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]<br />
<br />
; moveto<br />
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.<br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' {{DevFeature}} $x2 and $y2 refer to the hex the unit came from.<br />
<br />
; sighted<br />
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)<br />
<br />
; attack<br />
: Triggers when the primary unit attacks the secondary unit.<br />
<br />
; attack_end<br />
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.<br />
<br />
; attacker_hits<br />
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.<br />
<br />
; attacker_misses<br />
: Same as ''attacker_hits'', but is triggered when the attacker misses.<br />
<br />
; defender_hits<br />
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.<br />
<br />
; defender_misses<br />
: Same as ''defender_hits'', but is triggered when the defender misses.<br />
<br />
; stone<br />
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).<br />
<br />
; last breath<br />
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.<br />
<br />
; die<br />
: Triggers when the primary unit is killed by the secondary unit.<br />
<br />
; capture<br />
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.<br />
<br />
; recruit<br />
: Triggers when the primary unit is recruited. (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).<br />
<br />
; prerecruit<br />
: Triggers when the primary unit is recruited but before it is displayed.<br />
<br />
; recall<br />
: Triggers after a unit is recalled.<br />
<br />
; prerecall<br />
: Triggers when a unit is recalled but before it is displayed.<br />
<br />
; advance<br />
: Triggers just before the primary unit is going to advance to another unit.<br />
<br />
; post_advance<br />
: Triggers just after the primary unit has advanced to another unit.<br />
<br />
; select<br />
: Triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''<br />
<br />
; menu item X<br />
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''<br />
<br />
; Other events with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag.<br />
<br />
=== Optional Keys and Tags ===<br />
<br />
These keys and tags are more complex ways to filter when an event should trigger:<br />
<br />
==== first_time_only ====<br />
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:<br />
: ''first_time_only=yes''<br />
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.<br />
: ''first_time_only=no''<br />
:: The event will every time the criteria are met instead of only the first time.<br />
<br />
==== [filter] ====<br />
: The event will only trigger if the primary unit matches this filter.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_second] ====<br />
: Like [filter], but for the secondary unit.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_attack] ====<br />
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''.<br />
:* '''name''': the name of the weapon used.<br />
:* '''range''': the range of the weapon used. <br />
<br />
==== [filter_second_attack] ====<br />
: Like [filter_attack], but for the secondary unit.<br />
:* '''name''': the name of the weapon used.<br />
:* '''range''': the range of the weapon used.<br />
<br />
==== [event] ====<br />
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].<br />
<br />
==== delayed_variable_substitution ====<br />
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.<br />
<br />
=== Actions triggered by [event] ===<br />
<br />
After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.<br />
<br />
There are 3 main types of actions:<br />
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay<br />
* display actions ([[InterfaceActionsWML]]) which show something to the user<br />
* internal actions ([[InternalActionsWML]]) which are used by WML internally<br />
<br />
Several actions use standard filters to find out which units<br />
to execute the command on. These are denoted by the phrases<br />
"standard unit filter" and "standard location filter".<br />
<br />
=== Nested Events ===<br />
<br />
There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).<br />
<br />
([[#Nested Event Example|See Examples]])<br />
<br />
==== Delayed Variable Substitution ====<br />
<br />
Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.<br />
<br />
If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.<br />
<br />
This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.<br />
<br />
([[#Delayed Variable Substitution Example|See Examples]])<br />
<br />
== Miscellaneous Notes and Examples ==<br />
<br />
=== Primary/Secondary Unit Speaker Example ===<br />
<br />
In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:<br />
<br />
[event]<br />
name=die<br />
[message]<br />
speaker='''second_unit'''<br />
message= _ "Hahaha! I finally killed you!"<br />
[/message]<br />
<br />
[message]<br />
speaker='''unit'''<br />
message= _ "It's not over yet! I'll come back to haunt you!"<br />
[/message]<br />
[/event]<br />
<br />
=== Nested Event Example ===<br />
<br />
An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
# moving to 5,8 will trigger this event only on turn 10 and after<br />
[/event]<br />
[/event]<br />
<br />
An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.<br />
<br />
=== Delayed Variable Substitution Example ===<br />
<br />
This code will display the turn on which the nested ''moveto'' event happens.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=yes<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
This code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Finally, this example is identical to the first two, in that it will display the turn on which the nested ''moveto'' event happens despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $|turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
== See Also ==<br />
<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[FilterWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=EventWML&diff=29248EventWML2009-03-25T01:28:43Z<p>Voris: /* Valid 'name' Key Values */ Added link to fire_event tag.</p>
<hr />
<div>{{WML Tags}}<br />
== The [event] Tag ==<br />
<br />
This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.<br />
<br />
This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.<br />
<br />
=== The 'name' Key (Mandatory) ===<br />
<br />
Usage:<br />
name=<value><br />
<br />
This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.<br />
<br />
'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''<br />
<br />
The '''name''' key can accept a list of comma separated values describing when the event will be triggered.*<br />
<br />
For example:<br />
<br />
name=attacker_misses,defender_misses<br />
<br />
''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''<br />
<br />
==== Valid 'name' Key Values ====<br />
<br />
All valid values are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here will '''not''' work ''no matter how logical or awesome you think it sounds.''<br />
<br />
; preload {{DevFeature}}<br />
: Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc. It hardly makes sense without [[#first_time_only|first_time_only=no]].<br />
<br />
; prestart<br />
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.<br />
<br />
; start<br />
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.<br />
<br />
; new turn<br />
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.<br />
<br />
; side turn<br />
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.<br />
<br />
; ai turn<br />
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.<br />
<br />
; turn refresh<br />
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.<br />
<br />
; turn ''X''<br />
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.<br />
<br />
; time over<br />
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])<br />
<br />
; enemies defeated<br />
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.<br />
<br />
; victory<br />
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])<br />
<br />
; defeat<br />
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])<br />
<br />
<br />
Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true. <br />
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]<br />
<br />
; moveto<br />
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.<br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' {{DevFeature}} $x2 and $y2 refer to the hex the unit came from.<br />
<br />
; sighted<br />
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)<br />
<br />
; attack<br />
: Triggers when the primary unit attacks the secondary unit.<br />
<br />
; attack_end<br />
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.<br />
<br />
; attacker_hits<br />
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.<br />
<br />
; attacker_misses<br />
: Same as ''attacker_hits'', but is triggered when the attacker misses.<br />
<br />
; defender_hits<br />
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.<br />
<br />
; defender_misses<br />
: Same as ''defender_hits'', but is triggered when the defender misses.<br />
<br />
; stone<br />
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).<br />
<br />
; last breath<br />
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.<br />
<br />
; die<br />
: Triggers when the primary unit is killed by the secondary unit.<br />
<br />
; capture<br />
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.<br />
<br />
; recruit<br />
: Triggers when the primary unit is recruited. (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).<br />
<br />
; prerecruit<br />
: Triggers when the primary unit is recruited but before it is displayed.<br />
<br />
; recall<br />
: Triggers after a unit is recalled.<br />
<br />
; prerecall<br />
: Triggers when a unit is recalled but before it is displayed.<br />
<br />
; advance<br />
: Triggers just before the primary unit is going to advance to another unit.<br />
<br />
; post_advance<br />
: Triggers just after the primary unit has advanced to another unit.<br />
<br />
; select<br />
: Triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''<br />
<br />
; menu item X<br />
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''<br />
<br />
; Other events with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag.<br />
<br />
=== Optional Keys and Tags ===<br />
<br />
These keys and tags are more complex ways to filter when an event should trigger:<br />
<br />
==== first_time_only ====<br />
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:<br />
: ''first_time_only=yes''<br />
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.<br />
: ''first_time_only=no''<br />
:: The event will every time the criteria are met instead of only the first time.<br />
<br />
==== [filter] ====<br />
: The event will only trigger if the primary unit matches this filter.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_second] ====<br />
: Like [filter], but for the secondary unit.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_attack] ====<br />
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''.<br />
:* '''name''': the name of the weapon used.<br />
:* '''range''': the range of the weapon used. <br />
<br />
==== [filter_second_attack] ====<br />
: Like [filter_attack], but for the secondary unit.<br />
:* '''name''': the name of the weapon used.<br />
:* '''range''': the range of the weapon used.<br />
<br />
==== [event] ====<br />
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].<br />
<br />
==== delayed_variable_substitution ====<br />
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.<br />
<br />
=== Actions triggered by [event] ===<br />
<br />
After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.<br />
<br />
There are 3 main types of actions:<br />
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay<br />
* display actions ([[InterfaceActionsWML]]) which show something to the user<br />
* internal actions ([[InternalActionsWML]]) which are used by WML internally<br />
<br />
Several actions use standard filters to find out which units<br />
to execute the command on. These are denoted by the phrases<br />
"standard unit filter" and "standard location filter".<br />
<br />
=== Nested Events ===<br />
<br />
There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).<br />
<br />
([[#Nested Event Example|See Examples]])<br />
<br />
==== Delayed Variable Substitution ====<br />
<br />
Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.<br />
<br />
If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.<br />
<br />
This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.<br />
<br />
([[#Delayed Variable Substitution Example|See Examples]])<br />
<br />
== Miscellaneous Notes and Examples ==<br />
<br />
=== Primary/Secondary Unit Speaker Example ===<br />
<br />
In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:<br />
<br />
[event]<br />
name=die<br />
[message]<br />
speaker='''second_unit'''<br />
message= _ "Hahaha! I finally killed you!"<br />
[/message]<br />
<br />
[message]<br />
speaker='''unit'''<br />
message= _ "It's not over yet! I'll come back to haunt you!"<br />
[/message]<br />
[/event]<br />
<br />
=== Nested Event Example ===<br />
<br />
An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
# moving to 5,8 will trigger this event only on turn 10 and after<br />
[/event]<br />
[/event]<br />
<br />
An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.<br />
<br />
=== Delayed Variable Substitution Example ===<br />
<br />
This code will display the turn on which the nested ''moveto'' event happens.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=yes<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
This code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Finally, this example is identical to the first two, in that it will display the turn on which the nested ''moveto'' event happens despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $|turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
== See Also ==<br />
<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[FilterWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWMLUnitTags&diff=29118InternalActionsWMLUnitTags2009-03-23T02:39:41Z<p>Voris: Polished page with {{WML Tags}}, See Also section, and Category links.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with '''[set_variable]'''. Here is a sample list. (If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.)<br />
<br />
* advances_to<br />
* alignment<br />
* alpha<br />
* attacks_left<br />
* canrecruit<br />
* cost<br />
* experience<br />
* facing<br />
* flying<br />
* gender<br />
* goto_x<br />
* goto_y<br />
* hitpoints<br />
* id<br />
* language_name (same as the name key in the unit config)<br />
* max_experience<br />
* max_hitpoints<br />
* max_moves<br />
* moves<br />
* overlays<br />
* resting<br />
* side<br />
* type<br />
* unit_description<br />
* unrenamable<br />
* upkeep<br />
* x<br />
* y<br />
* zoc<br />
* [advancement]<br />
* [movement_costs]<br />
* [defense]<br />
* [resistance]<br />
* [variables]<br />
* [status]<br />
* [attack]<br />
* [modifications_description]<br />
* [modifications]<br />
<br />
These values are all children of the stored unit variable (it is a [[VariablesWML#Container|container]] variable) and the bracketed values (advancement, movement_costs, defense, etc.) are, themselves, container variables. Example:<br />
[set_variable]<br />
name=unit_store.status.poisoned<br />
value=yes<br />
[/set_variable]<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[InternalActionsWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWMLUnitTags&diff=29117InternalActionsWMLUnitTags2009-03-23T02:32:37Z<p>Voris: Initial creation.</p>
<hr />
<div>When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with '''[set_variable]'''. Here is a sample list. (If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.)<br />
<br />
* advances_to<br />
* alignment<br />
* alpha<br />
* attacks_left<br />
* canrecruit<br />
* cost<br />
* experience<br />
* facing<br />
* flying<br />
* gender<br />
* goto_x<br />
* goto_y<br />
* hitpoints<br />
* id<br />
* language_name (same as the name key in the unit config)<br />
* max_experience<br />
* max_hitpoints<br />
* max_moves<br />
* moves<br />
* overlays<br />
* resting<br />
* side<br />
* type<br />
* unit_description<br />
* unrenamable<br />
* upkeep<br />
* x<br />
* y<br />
* zoc<br />
* [advancement]<br />
* [movement_costs]<br />
* [defense]<br />
* [resistance]<br />
* [variables]<br />
* [status]<br />
* [attack]<br />
* [modifications_description]<br />
* [modifications]<br />
<br />
These values are all children of the stored unit variable (it is a [[VariablesWML#Container|container]] variable) and the bracketed values (advancement, movement_costs, defense, etc.) are, themselves, container variables. Example:<br />
[set_variable]<br />
name=unit_store.status.poisoned<br />
value=yes<br />
[/set_variable]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWML&diff=29116InternalActionsWML2009-03-23T02:31:10Z<p>Voris: /* [store_unit] */ Added link to page with list of store_unit tags and keys.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Internal actions are actions that WML uses internally that do not directly affect game play (or, at least, are not readily apparent to the player). For example, storing a variable is an internal action.<br />
<br />
== Variable Actions ==<br />
<br />
These actions are focused, in one way or another, on [[VariablesWML|variables]]. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.<br />
<br />
=== [set_variable] ===<br />
<br />
The '''[set_variable]''' tag is used to create and manipulate WML variables. The [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE VARIABLE] macro is a quick syntactic shortcut for simple variable creation and the [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE_OP VARIABLE_OP] macro is a quick syntactic shortcut for performing simple mathematical operations on variables.<br />
<br />
* '''name''': the name of the variable to manipulate<br />
<br />
* '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])<br />
<br />
* '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.<br />
<br />
* '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.<br />
<br />
* '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.<br />
<br />
* '''add''': add the given amount to the variable. To subtract, add a negative number.<br />
<br />
* '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. Floating point values are not rounded.<br />
<br />
* '''divide''': divide the variable by the given number. The result is an integer. Floating point results are not rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.<br />
<br />
* '''modulo''': returns the remainder of a division.<br />
<br />
* '''random''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.<br />
<br />
* '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''<br />
<br />
* '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.<br />
<br />
* '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).<br />
<br />
* '''[join]''' joins an array of strings to create a textual list<br />
** '''variable''': name of the array<br />
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored<br />
** '''separator''': separator to connect the elements<br />
** '''remove_empty''': whether to ignore empty elements<br />
<br />
* '''ipart''': Assigns the integer part (the part to the left of the comma) of the referenced variable.<br />
<br />
* '''fpart''': Assigns the decimal part (the part to the right of the comma) of the referenced variable.<br />
<br />
* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:<br />
**'''ceil''': Rounds upward to the nearest integer.<br />
**'''floor''': Rounds down to the nearest integer.<br />
<br />
=== [set_variables] ===<br />
<br />
Manipulates a WML array<br />
<br />
* '''name''': the name of the container to manipulate<br />
<br />
* '''mode''': one of the following values:<br />
** ''replace'': will clean the array '''name''' and replace it with given data<br />
** ''append'': will append given data to the current array<br />
** ''merge'': will merge in the given data into '''name'''<br />
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.<br />
<br />
* '''to_variable''': data will be set to the given array<br />
<br />
* '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags. ([[#Using_.5Bset_variables.5D_to_Create_Arrays_of_WML|See Example]])<br />
<br />
* '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags<br />
<br />
*'''[split]''' splits a textual list into an array which will then be set to data<br />
** '''list''': textual list to split<br />
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored<br />
** '''separator''': separator to separate the elements<br />
** '''remove_empty''': wether to ignore empty elements<br />
<br />
=== Capturing Game Data ===<br />
<br />
These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.<br />
<br />
==== [store_gold] ====<br />
<br />
Stores a side's gold into a variable.<br />
<br />
* '''side''': (default=1) the side for which the gold should be stored<br />
<br />
* '''variable''': (default='gold') the name of the variable to store the gold in<br />
<br />
==== [store_locations] ====<br />
<br />
Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only).<br />
<br />
* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.<br />
<br />
* '''variable''': the name of the variable (array) into which to store the locations<br />
<br />
* '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.<br />
<br />
* '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored<br />
<br />
* '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.<br />
<br />
==== [store_map_dimensions] ====<br />
<br />
Stores the map dimensions in a variable.<br />
<br />
* '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.<br />
<br />
==== [store_side] ====<br />
<br />
Stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.<br />
<br />
* '''side''': the side whose information should be stored<br />
<br />
* '''variable''': the name of the variable to store the information in<br />
<br />
==== [store_starting_location] ====<br />
<br />
Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and 'owner_side' (villages only)<br />
<br />
* '''side''': the side whose starting location is to be stored<br />
<br />
* '''variable''': (default='location'): the name of the variable to store the location in<br />
<br />
==== [store_time_of_day] ====<br />
<br />
Stores time of day information from the current scenario into a WML variable container.<br />
<br />
* '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].<br />
<br />
* '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.<br />
<br />
==== [store_unit] ====<br />
<br />
Stores details about units into a [[VariablesWML#Container|container]] variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]. A sample list of these tags and keys can be found [[InternalActionsWMLUnitTags|here]]. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the '''[unit]''' tag(s) in any save file).<br />
<br />
Common usage is to manipulate a unit by using '''[store_unit]''' to store it into a variable, followed by manipulation of the variable, and then [[DirectActionsWML|[unstore_unit]]] to re-create the unit with the modified variables.<br />
<br />
''Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [[DirectActionsWML|[unstore_unit]]] and [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH].''<br />
<br />
* '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.<br />
<br />
* '''variable''': the name of the variable into which to store the unit(s)<br />
<br />
* '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.<br />
<br />
* '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.<br />
<br />
==== [store_villages] ====<br />
<br />
Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.<br />
<br />
* '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages. <br />
<br />
* '''variable''': the name of the variable (array) into which to store the locations<br />
<br />
* '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.<br />
<br />
=== [clear_variable] ===<br />
<br />
This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.<br />
<br />
* '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.<br />
<br />
== Other Internal Actions ==<br />
<br />
Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.<br />
<br />
=== [fire_event] ===<br />
<br />
Trigger a WML event<br />
<br />
* '''name''': the name of event to trigger<br />
<br />
* '''[primary_unit]''': ''(Optional)'' Primary unit for the event (usually the attacker). Will never match on a recall list unit. If it matches multiple units, only one will be chosen.<br />
** '''x,y''': ''(Optional)'' The location of this unit.<br />
<br />
* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary unit.<br />
<br />
* '''[primary_attack]''': Information passed to the primary attack filter and $weapon variable on the new event.<br />
<br />
* '''[secondary_attack]''': Information passed to the second attack filter and $second_weapon variable on the new event.<br />
<br />
=== [insert_tag] ===<br />
<br />
Inserts a variable as WML. In other words, the value of the passed variable will be injected into the game as if they had been written out in WML form. ([[#.5Binsert_tag.5D_Example|See Example]])<br />
<br />
*'''name''': The ["name"] to be given to the tag. This must be a valid WML tag name for anything to happen.<br />
<br />
*'''variable''': Name of the variable which will have it's value inserted into the tag.<br />
<br />
=== [role] ===<br />
<br />
Tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.<br />
<br />
* '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.<br />
<br />
* '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.<br />
<br />
== Examples ==<br />
<br />
=== Using [set_variables] to Create Arrays of WML ===<br />
<br />
[set_variables]<br />
name=arr<br />
mode=replace<br />
[value]<br />
foo=bar<br />
[/value]<br />
[value]<br />
foo=more<br />
[/value]<br />
[/set_variables]<br />
{DEBUG_MSG $arr[0].foo}<br />
{DEBUG_MSG $arr[1].foo}<br />
<br />
This will produce two output messages, first one saying '''bar''' and next one saying '''more'''.<br />
<br />
=== [insert_tag] Example ===<br />
<br />
[event]<br />
name=moveto<br />
<br />
[set_variable]<br />
name=temp.speaker<br />
value=Konrad<br />
[/set_variable]<br />
<br />
[set_variable]<br />
name=temp.message<br />
value= _ "Yo Kalenz!"<br />
[/set_variable] <br />
<br />
[insert_tag]<br />
name=message<br />
variable=temp<br />
[/insert_tag]<br />
[/event]<br />
<br />
This is effectively identical to:<br />
<br />
[event]<br />
name=moveto<br />
<br />
[message]<br />
speaker=Konrad<br />
message= _ "Yo Kalenz!"<br />
[/message]<br />
[/event]<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[ConditionalWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=DirectActionsWML&diff=29067DirectActionsWML2009-03-22T17:33:14Z<p>Voris: Updated some InternalActionsWML and ConditionalActionsWML links.</p>
<hr />
<div>{{WML Tags}}<br />
== Direct actions ==<br />
<br />
Direct actions are actions that have a direct effect on gameplay.<br />
<br />
The following tags are actions:<br />
* '''[endlevel]''': ends the scenario.<br />
** '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless ''result=defeat'', the following keys can also be used:<br />
** '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.<br />
** '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.<br />
** '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes.<br />
** '''linger_mode''': whether the game should switch to linger_mode before advancing to the next scenario, the default is linger_mode=yes.<br />
** '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.<br />
** When the result is "victory" 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 />
** '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.<br />
** '''end_text''': Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].<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. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].<br />
* '''[unit]''': places a unit on the map. For syntax see [[SingleUnitWML]].<br />
** {{Short Note:Predefined Macro|GENERIC_UNIT}}<br />
** '''to_variable''': spawn directly into a variable instead of on the map.<br />
* '''[recall]''': recalls a unit. The unit is recalled free of charge, and is placed near the leader.<br />
** [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored.<br />
** '''x,y''': the unit is placed here instead of next to the leader.<br />
** '''show''': if not "no", display the unit being recalled.<br />
* '''[teleport]''': teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}<br />
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be teleported.<br />
** '''x,y''': the position to teleport to.<br />
** '''clear_shroud''': should shroud be cleared on arrival<br />
** '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)<br />
* '''[terrain_mask]''': changes the terrain on the map. See [[TerrainMaskWML]].<br />
* '''[terrain]''': changes the terrain on the map.<br />
** '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.<br />
** '''x,y''': the position (or range of positions) to change.<br />
** '''layer''': (overlay|base|both, default=both) only change the specified layer.<br />
** '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.<br />
* '''[gold]''': give one side gold.<br />
** '''amount''': the amount of gold to give.<br />
** '''side''': (default=1) the number of the side to give the gold to.<br />
* '''[unstore_unit]''': creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.<br />
** '''variable''': the name of the variable.<br />
** '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.<br />
** '''text''': (translatable) floating text to display above the unit, such as a damage amount<br />
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)<br />
** '''advance''': if the XP has been modified then there will be tried to advance the unit, default true. <br />
** '''x''' ,'''y''': override unit location<br />
* '''[allow_recruit]''': allows a side to recruit units it couldn't previously recruit.<br />
** '''type''': the types of units that the side can now recruit.<br />
** '''side''': (default=1) the number of the side that is being allowed to recruit the units.<br />
* '''[disallow_recruit]''': prevents a side from recruiting units it could previously recruit.<br />
** '''type''': the types of units that the side can no longer recruit.<br />
** '''side''': (default=1) the number of the side that may no longer recruit the units.<br />
* '''[set_recruit]''': sets the units a side can recruit.<br />
** '''recruit''': the types of units that the side can now recruit.<br />
** '''side''': (default=1) the number of the side that is having its recruitment set.<br />
* '''[modify_side]''': modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'<br />
** '''side''': (default=1) the number of the side that is to be changed.<br />
** '''income''': the income given at the begining of each turn.<br />
** '''team_name''': the team in which the side plays the scenario.<br />
** '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.<br />
** '''gold''': the amount of gold the side owns.<br />
** '''village_gold''': the income setting per village for the side.<br />
** '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.<br />
** '''fog''': a boolean string (yes/no) describing the status of Fog for the side.<br />
** '''shroud''': a boolean string describing the status of Shroud for the side.<br />
** '''hidden''': a boolean string specifying whether side is shown in status table.<br />
** '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].<br />
* '''[modify_turns]''': modifies the turn limit in the middle of a scenario.<br />
** '''value''': the new turn limit.<br />
** '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).<br />
** '''current''': changes the current turn number after applying turn limit modifications, if any. It is possible to change the current turn number to a greater one than the current only; also, it is not possible to change the turn number to exceed the turn limit.<br />
* '''[capture_village]''': changes the ownership of a village.<br />
** '''side''': the side that takes control of the village. If not given, the village will become neutral.<br />
** '''x, y''': the location of the village.<br />
* '''[kill]''': Removes all units (including units in a recall list) that match the filter from the game.<br />
** [[StandardUnitFilter]]: selection criterion<br />
** '''animate''': if 'yes', displays the unit dying (fading away).<br />
** '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'last breath' and 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event.<br />
* '''[unstone]''': Unstones all units that match the filter.<br />
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be unstoned. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unstoned.<br />
* '''[object]''': gives some unit an object and removes all items on the tile the unit is on.<br />
** '''id''': when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.<br />
** '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].<br />
** '''duration''': if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).<br />
** '''[filter]''': [[StandardUnitFilter]] the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.<br />
** '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.<br />
** '''silent''': whether or not messages should be suppressed. Default is "no".<br />
** '''image''': the displayed image of the object.<br />
** '''name''': (translatable) displayed as a caption of the image.<br />
<br />
** '''user_description''': (translatable) displayed as a message of the image. In 1.4 and older versions this is just '''description'''; that will still be expected for compatibility.<br />
** '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.<br />
** If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.<br />
** The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.<br />
* '''[remove_shroud]''': removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).<br />
** '''side''': (default=1) the side for which to remove shroud.<br />
** [[StandardLocationFilter]]: the range of tiles for which shroud should be removed.<br />
* '''[place_shroud]''': places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).<br />
** '''side''': (default=1) the side for which to place shroud.<br />
** [[StandardLocationFilter]]: the range of tiles on which shroud should be placed.<br />
* '''[allow_undo]''': allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.<br />
** Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.<br />
* '''[heal_unit]''': heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed).<br />
** '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed. <br />
** '''[secondary_unit_filter]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true).<br />
** '''amount''': the maximum points the unit will be healed.<br />
** '''animate''': a boolean which indicate if the healing animations must be played.<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] and [illuminated_time] tags in the [scenario] tag<br />
** [[StandardLocationFilter]]: the locations to affect.<br />
** [[TimeWML]]: the new schedule.<br />
** '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. Can be a comma-separated list when removing time_areas, see below.<br />
** '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.<br />
<br />
* '''[end_turn]''': end the current side's turn.<br />
<br />
== Useful Macros ==<br />
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].<br />
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])<br />
* '''{FULL_HEAL}''': Brings a unit to full HP<br />
* '''{LOYAL_UNIT}''': Create a loyal unit<br />
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain<br />
<br />
== See Also ==<br />
<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWML&diff=29066InternalActionsWML2009-03-22T17:22:29Z<p>Voris: Sorted most items and added examples section.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Internal actions are actions that WML uses internally that do not directly affect game play (or, at least, are not readily apparent to the player). For example, storing a variable is an internal action.<br />
<br />
== Variable Actions ==<br />
<br />
These actions are focused, in one way or another, on [[VariablesWML|variables]]. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.<br />
<br />
=== [set_variable] ===<br />
<br />
The '''[set_variable]''' tag is used to create and manipulate WML variables. The [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE VARIABLE] macro is a quick syntactic shortcut for simple variable creation and the [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE_OP VARIABLE_OP] macro is a quick syntactic shortcut for performing simple mathematical operations on variables.<br />
<br />
* '''name''': the name of the variable to manipulate<br />
<br />
* '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])<br />
<br />
* '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.<br />
<br />
* '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.<br />
<br />
* '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.<br />
<br />
* '''add''': add the given amount to the variable. To subtract, add a negative number.<br />
<br />
* '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. Floating point values are not rounded.<br />
<br />
* '''divide''': divide the variable by the given number. The result is an integer. Floating point results are not rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.<br />
<br />
* '''modulo''': returns the remainder of a division.<br />
<br />
* '''random''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.<br />
<br />
* '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''<br />
<br />
* '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.<br />
<br />
* '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).<br />
<br />
* '''[join]''' joins an array of strings to create a textual list<br />
** '''variable''': name of the array<br />
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored<br />
** '''separator''': separator to connect the elements<br />
** '''remove_empty''': whether to ignore empty elements<br />
<br />
* '''ipart''': Assigns the integer part (the part to the left of the comma) of the referenced variable.<br />
<br />
* '''fpart''': Assigns the decimal part (the part to the right of the comma) of the referenced variable.<br />
<br />
* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:<br />
**'''ceil''': Rounds upward to the nearest integer.<br />
**'''floor''': Rounds down to the nearest integer.<br />
<br />
=== [set_variables] ===<br />
<br />
Manipulates a WML array<br />
<br />
* '''name''': the name of the container to manipulate<br />
<br />
* '''mode''': one of the following values:<br />
** ''replace'': will clean the array '''name''' and replace it with given data<br />
** ''append'': will append given data to the current array<br />
** ''merge'': will merge in the given data into '''name'''<br />
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.<br />
<br />
* '''to_variable''': data will be set to the given array<br />
<br />
* '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags. ([[#Using_.5Bset_variables.5D_to_Create_Arrays_of_WML|See Example]])<br />
<br />
* '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags<br />
<br />
*'''[split]''' splits a textual list into an array which will then be set to data<br />
** '''list''': textual list to split<br />
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored<br />
** '''separator''': separator to separate the elements<br />
** '''remove_empty''': wether to ignore empty elements<br />
<br />
=== Capturing Game Data ===<br />
<br />
These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.<br />
<br />
==== [store_gold] ====<br />
<br />
Stores a side's gold into a variable.<br />
<br />
* '''side''': (default=1) the side for which the gold should be stored<br />
<br />
* '''variable''': (default='gold') the name of the variable to store the gold in<br />
<br />
==== [store_locations] ====<br />
<br />
Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only).<br />
<br />
* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.<br />
<br />
* '''variable''': the name of the variable (array) into which to store the locations<br />
<br />
* '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.<br />
<br />
* '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored<br />
<br />
* '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.<br />
<br />
==== [store_map_dimensions] ====<br />
<br />
Stores the map dimensions in a variable.<br />
<br />
* '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.<br />
<br />
==== [store_side] ====<br />
<br />
Stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.<br />
<br />
* '''side''': the side whose information should be stored<br />
<br />
* '''variable''': the name of the variable to store the information in<br />
<br />
==== [store_starting_location] ====<br />
<br />
Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and 'owner_side' (villages only)<br />
<br />
* '''side''': the side whose starting location is to be stored<br />
<br />
* '''variable''': (default='location'): the name of the variable to store the location in<br />
<br />
==== [store_time_of_day] ====<br />
<br />
Stores time of day information from the current scenario into a WML variable container.<br />
<br />
* '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].<br />
<br />
* '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.<br />
<br />
==== [store_unit] ====<br />
<br />
Stores details about units into a [[VariablesWML#Container|container]] variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the '''[unit]''' tag(s) in any save file).<br />
<br />
Common usage is to manipulate a unit by using '''[store_unit]''' to store it into a variable, followed by manipulation of the variable, and then [[DirectActionsWML|[unstore_unit]]] to re-create the unit with the modified variables.<br />
<br />
''Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [[DirectActionsWML|[unstore_unit]]] and [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH].''<br />
<br />
* '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.<br />
<br />
* '''variable''': the name of the variable into which to store the unit(s)<br />
<br />
* '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.<br />
<br />
* '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.<br />
<br />
==== [store_villages] ====<br />
<br />
Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.<br />
<br />
* '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages. <br />
<br />
* '''variable''': the name of the variable (array) into which to store the locations<br />
<br />
* '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.<br />
<br />
=== [clear_variable] ===<br />
<br />
This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.<br />
<br />
* '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.<br />
<br />
== Other Internal Actions ==<br />
<br />
Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.<br />
<br />
=== [fire_event] ===<br />
<br />
Trigger a WML event<br />
<br />
* '''name''': the name of event to trigger<br />
<br />
* '''[primary_unit]''': ''(Optional)'' Primary unit for the event (usually the attacker). Will never match on a recall list unit. If it matches multiple units, only one will be chosen.<br />
** '''x,y''': ''(Optional)'' The location of this unit.<br />
<br />
* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary unit.<br />
<br />
* '''[primary_attack]''': Information passed to the primary attack filter and $weapon variable on the new event.<br />
<br />
* '''[secondary_attack]''': Information passed to the second attack filter and $second_weapon variable on the new event.<br />
<br />
=== [insert_tag] ===<br />
<br />
Inserts a variable as WML. In other words, the value of the passed variable will be injected into the game as if they had been written out in WML form. ([[#.5Binsert_tag.5D_Example|See Example]])<br />
<br />
*'''name''': The ["name"] to be given to the tag. This must be a valid WML tag name for anything to happen.<br />
<br />
*'''variable''': Name of the variable which will have it's value inserted into the tag.<br />
<br />
=== [role] ===<br />
<br />
Tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.<br />
<br />
* '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.<br />
<br />
* '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.<br />
<br />
== Examples ==<br />
<br />
=== Using [set_variables] to Create Arrays of WML ===<br />
<br />
[set_variables]<br />
name=arr<br />
mode=replace<br />
[value]<br />
foo=bar<br />
[/value]<br />
[value]<br />
foo=more<br />
[/value]<br />
[/set_variables]<br />
{DEBUG_MSG $arr[0].foo}<br />
{DEBUG_MSG $arr[1].foo}<br />
<br />
This will produce two output messages, first one saying '''bar''' and next one saying '''more'''.<br />
<br />
=== [insert_tag] Example ===<br />
<br />
[event]<br />
name=moveto<br />
<br />
[set_variable]<br />
name=temp.speaker<br />
value=Konrad<br />
[/set_variable]<br />
<br />
[set_variable]<br />
name=temp.message<br />
value= _ "Yo Kalenz!"<br />
[/set_variable] <br />
<br />
[insert_tag]<br />
name=message<br />
variable=temp<br />
[/insert_tag]<br />
[/event]<br />
<br />
This is effectively identical to:<br />
<br />
[event]<br />
name=moveto<br />
<br />
[message]<br />
speaker=Konrad<br />
message= _ "Yo Kalenz!"<br />
[/message]<br />
[/event]<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[ConditionalWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWML&diff=29064InternalActionsWML2009-03-22T16:52:54Z<p>Voris: /* [store_unit] */ Killed the long (and begging to be outdated) list of unit keys that can be manipulated.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Internal actions are actions that WML uses internally that do not directly affect game play (or, at least, are not readily apparent to the player). For example, storing a variable is an internal action.<br />
<br />
== Variable Actions ==<br />
<br />
These actions are focused, in one way or another, on [[VariablesWML|variables]]. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.<br />
<br />
=== [set_variable] ===<br />
<br />
The '''[set_variable]''' tag is used to create and manipulate WML variables. The [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE VARIABLE] macro is a quick syntactic shortcut for simple variable creation and the [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE_OP VARIABLE_OP] macro is a quick syntactic shortcut for performing simple mathematical operations on variables.<br />
<br />
* '''name''': the name of the variable to manipulate<br />
<br />
* '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])<br />
<br />
* '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.<br />
<br />
* '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.<br />
<br />
* '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.<br />
<br />
* '''add''': add the given amount to the variable. To subtract, add a negative number.<br />
<br />
* '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. Floating point values are not rounded.<br />
<br />
* '''divide''': divide the variable by the given number. The result is an integer. Floating point results are not rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.<br />
<br />
* '''modulo''': returns the remainder of a division.<br />
<br />
* '''random''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.<br />
<br />
* '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''<br />
<br />
* '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.<br />
<br />
* '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).<br />
<br />
* '''[join]''' joins an array of strings to create a textual list<br />
** '''variable''': name of the array<br />
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored<br />
** '''separator''': separator to connect the elements<br />
** '''remove_empty''': whether to ignore empty elements<br />
<br />
* '''ipart''': Assigns the integer part (the part to the left of the comma) of the referenced variable.<br />
<br />
* '''fpart''': Assigns the decimal part (the part to the right of the comma) of the referenced variable.<br />
<br />
* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:<br />
**'''ceil''': Rounds upward to the nearest integer.<br />
**'''floor''': Rounds down to the nearest integer.<br />
<br />
=== [set_variables] ===<br />
<br />
Manipulates a WML array<br />
<br />
* '''name''': the name of the container to manipulate<br />
<br />
* '''mode''': one of the following values:<br />
** ''replace'': will clean the array '''name''' and replace it with given data<br />
** ''append'': will append given data to the current array<br />
** ''merge'': will merge in the given data into '''name'''<br />
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.<br />
<br />
* '''to_variable''': data will be set to the given array<br />
<br />
* '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags, example:<br />
[set_variables]<br />
name=arr<br />
mode=replace<br />
[value]<br />
foo=bar<br />
[/value]<br />
[value]<br />
foo=more<br />
[/value]<br />
[/set_variables]<br />
{DEBUG_MSG $arr[0].foo}<br />
{DEBUG_MSG $arr[1].foo}<br />
=>bar; more<br />
<br />
* '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags<br />
<br />
*'''[split]''' splits a textual list into an array which will then be set to data<br />
**list: textual list to split<br />
**key: the key of each array element(array[$i].foo) in which the strings are stored<br />
**separator: separator to separate the elements<br />
**remove_empty: wether to ignore empty elements<br />
<br />
=== Capturing Game Data ===<br />
<br />
These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.<br />
<br />
==== [store_unit] ====<br />
<br />
Stores details about units into a [[VariablesWML#Container|container]] variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]]. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the '''[unit]''' tag(s) in any save file).<br />
<br />
Common usage is to manipulate a unit by using '''[store_unit]''' to store it into a variable, followed by manipulation of the variable, and then [[DirectActionsWML|[unstore_unit]]] to re-create the unit with the modified variables.<br />
<br />
''Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [[DirectActionsWML|[unstore_unit]]] and [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH].''<br />
<br />
* '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.<br />
<br />
* '''variable''': the name of the variable into which to store the unit(s)<br />
<br />
* '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.<br />
<br />
* '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.<br />
<br />
==== [store_starting_location] ====<br />
<br />
Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and 'owner_side' (villages only)<br />
<br />
* '''side''': the side whose starting location is to be stored<br />
<br />
* '''variable''': (default='location'): the name of the variable to store the location in<br />
<br />
==== [store_locations] ====<br />
<br />
Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only).<br />
<br />
* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.<br />
<br />
* '''variable''': the name of the variable (array) into which to store the locations<br />
<br />
* '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.<br />
<br />
* '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored<br />
<br />
* '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.<br />
<br />
==== [store_villages] ====<br />
<br />
Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.<br />
<br />
* '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages. <br />
<br />
* '''variable''': the name of the variable (array) into which to store the locations<br />
<br />
* '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.<br />
<br />
==== [store_gold] ====<br />
<br />
Stores a side's gold into a variable.<br />
<br />
* '''side''': (default=1) the side for which the gold should be stored<br />
<br />
* '''variable''': (default='gold') the name of the variable to store the gold in<br />
<br />
==== [store_side] ====<br />
<br />
Stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.<br />
<br />
* '''side''': the side whose information should be stored<br />
<br />
* '''variable''': the name of the variable to store the information in<br />
<br />
==== [store_map_dimensions] ====<br />
<br />
Stores the map dimensions in a variable.<br />
<br />
* '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.<br />
<br />
==== [store_time_of_day] ====<br />
<br />
Stores time of day information from the current scenario into a WML variable container.<br />
<br />
* '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].<br />
<br />
* '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.<br />
<br />
=== [clear_variable] ===<br />
<br />
This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.<br />
<br />
* '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.<br />
<br />
== Other Internal Actions ==<br />
<br />
Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.<br />
<br />
=== [fire_event] ===<br />
<br />
Trigger a WML event<br />
<br />
* '''name''': the name of event to trigger<br />
<br />
* '''[primary_unit]''': ''(Optional)'' Primary unit for the event (usually the attacker). Will never match on a recall list unit. If it matches multiple units, only one will be chosen.<br />
** '''x,y''': ''(Optional)'' The location of this unit.<br />
<br />
* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary unit.<br />
<br />
* '''[primary_attack]''': Information passed to the primary attack filter and $weapon variable on the new event.<br />
<br />
* '''[secondary_attack]''': Information passed to the second attack filter and $second_weapon variable on the new event.<br />
<br />
=== [role] ===<br />
<br />
Tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.<br />
<br />
* '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.<br />
<br />
* '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.<br />
<br />
=== [insert_tag] ===<br />
<br />
Inserts a variable as WML. In other words, the value of the passed variable will be injected into the game as if they had been written out in WML form.<br />
<br />
*'''name''': The ["name"] to be given to the tag. This must be a valid WML tag name for anything to happen.<br />
<br />
*'''variable''': Name of the variable which will have it's value inserted into the tag.<br />
<br />
For example:<br />
<br />
[event]<br />
name=moveto<br />
<br />
[set_variable]<br />
name=temp.speaker<br />
value=Konrad<br />
[/set_variable]<br />
<br />
[set_variable]<br />
name=temp.message<br />
value= _ "Yo Kalenz!"<br />
[/set_variable] <br />
<br />
[insert_tag]<br />
name=message<br />
variable=temp<br />
[/insert_tag]<br />
[/event]<br />
<br />
This is effectively identical to:<br />
<br />
[event]<br />
name=moveto<br />
<br />
[message]<br />
speaker=Konrad<br />
message= _ "Yo Kalenz!"<br />
[/message]<br />
[/event]<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[ConditionalWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWML&diff=29057InternalActionsWML2009-03-22T16:41:35Z<p>Voris: Internal link updates.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Internal actions are actions that WML uses internally that do not directly affect game play (or, at least, are not readily apparent to the player). For example, storing a variable is an internal action.<br />
<br />
== Variable Actions ==<br />
<br />
These actions are focused, in one way or another, on [[VariablesWML|variables]]. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.<br />
<br />
=== [set_variable] ===<br />
<br />
The '''[set_variable]''' tag is used to create and manipulate WML variables. The [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE VARIABLE] macro is a quick syntactic shortcut for simple variable creation and the [http://www.wesnoth.org/macro-reference.xhtml#VARIABLE_OP VARIABLE_OP] macro is a quick syntactic shortcut for performing simple mathematical operations on variables.<br />
<br />
* '''name''': the name of the variable to manipulate<br />
<br />
* '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])<br />
<br />
* '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.<br />
<br />
* '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.<br />
<br />
* '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.<br />
<br />
* '''add''': add the given amount to the variable. To subtract, add a negative number.<br />
<br />
* '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. Floating point values are not rounded.<br />
<br />
* '''divide''': divide the variable by the given number. The result is an integer. Floating point results are not rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.<br />
<br />
* '''modulo''': returns the remainder of a division.<br />
<br />
* '''random''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.<br />
<br />
* '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''<br />
<br />
* '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.<br />
<br />
* '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).<br />
<br />
* '''[join]''' joins an array of strings to create a textual list<br />
** '''variable''': name of the array<br />
** '''key''': the key of each array element(array[$i].foo) in which the strings are stored<br />
** '''separator''': separator to connect the elements<br />
** '''remove_empty''': whether to ignore empty elements<br />
<br />
* '''ipart''': Assigns the integer part (the part to the left of the comma) of the referenced variable.<br />
<br />
* '''fpart''': Assigns the decimal part (the part to the right of the comma) of the referenced variable.<br />
<br />
* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:<br />
**'''ceil''': Rounds upward to the nearest integer.<br />
**'''floor''': Rounds down to the nearest integer.<br />
<br />
=== [set_variables] ===<br />
<br />
Manipulates a WML array<br />
<br />
* '''name''': the name of the container to manipulate<br />
<br />
* '''mode''': one of the following values:<br />
** ''replace'': will clean the array '''name''' and replace it with given data<br />
** ''append'': will append given data to the current array<br />
** ''merge'': will merge in the given data into '''name'''<br />
** ''insert'': will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.<br />
<br />
* '''to_variable''': data will be set to the given array<br />
<br />
* '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags, example:<br />
[set_variables]<br />
name=arr<br />
mode=replace<br />
[value]<br />
foo=bar<br />
[/value]<br />
[value]<br />
foo=more<br />
[/value]<br />
[/set_variables]<br />
{DEBUG_MSG $arr[0].foo}<br />
{DEBUG_MSG $arr[1].foo}<br />
=>bar; more<br />
<br />
* '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags<br />
<br />
*'''[split]''' splits a textual list into an array which will then be set to data<br />
**list: textual list to split<br />
**key: the key of each array element(array[$i].foo) in which the strings are stored<br />
**separator: separator to separate the elements<br />
**remove_empty: wether to ignore empty elements<br />
<br />
=== Capturing Game Data ===<br />
<br />
These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.<br />
<br />
==== [store_unit] ====<br />
<br />
Stores details about units into game variables.<br>Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.<br>Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [[DirectActionsWML|[unstore_unit]]] and [http://www.wesnoth.org/macro-reference.xhtml#FOREACH FOREACH].<br />
<br />
* '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.<br />
<br />
* '''variable''': the name of the variable into which to store the unit(s)<br />
<br />
* '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.<br />
<br />
* '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.<br />
<br />
:When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with '''[set_variable]'''. Here is a sample list. (If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.)<br />
<br />
:* advances_to<br />
:* alignment<br />
:* alpha<br />
:* attacks_left<br />
:* canrecruit<br />
:* cost<br />
:* experience<br />
:* facing<br />
:* flying<br />
:* gender<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* id<br />
:* language_name (same as the name key in the unit config)<br />
:* max_experience<br />
:* max_hitpoints<br />
:* max_moves<br />
:* moves<br />
:* overlays<br />
:* resting<br />
:* side<br />
:* type<br />
:* unit_description<br />
:* unrenamable<br />
:* upkeep<br />
:* x<br />
:* y<br />
:* zoc<br />
:* [advancement]<br />
:* [movement_costs]<br />
:* [defense]<br />
:* [resistance]<br />
:* [variables]<br />
:* [status]<br />
:* [attack]<br />
:* [modifications_description]<br />
:* [modifications]<br />
<br />
These values are all children of the stored unit variable (it is a [[VariablesWML#Container|container]] variable) and the bracketed values (advancement, movement_costs, defense, etc.) are, themselves, container variables. Example:<br />
[set_variable]<br />
name=unit_store.status.poisoned<br />
value=yes<br />
[/set_variable]<br />
<br />
==== [store_starting_location] ====<br />
<br />
Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and 'owner_side' (villages only)<br />
<br />
* '''side''': the side whose starting location is to be stored<br />
<br />
* '''variable''': (default='location'): the name of the variable to store the location in<br />
<br />
==== [store_locations] ====<br />
<br />
Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only).<br />
<br />
* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.<br />
<br />
* '''variable''': the name of the variable (array) into which to store the locations<br />
<br />
* '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.<br />
<br />
* '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored<br />
<br />
* '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.<br />
<br />
==== [store_villages] ====<br />
<br />
Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.<br />
<br />
* '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages. <br />
<br />
* '''variable''': the name of the variable (array) into which to store the locations<br />
<br />
* '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.<br />
<br />
==== [store_gold] ====<br />
<br />
Stores a side's gold into a variable.<br />
<br />
* '''side''': (default=1) the side for which the gold should be stored<br />
<br />
* '''variable''': (default='gold') the name of the variable to store the gold in<br />
<br />
==== [store_side] ====<br />
<br />
Stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.<br />
<br />
* '''side''': the side whose information should be stored<br />
<br />
* '''variable''': the name of the variable to store the information in<br />
<br />
==== [store_map_dimensions] ====<br />
<br />
Stores the map dimensions in a variable.<br />
<br />
* '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.<br />
<br />
==== [store_time_of_day] ====<br />
<br />
Stores time of day information from the current scenario into a WML variable container.<br />
<br />
* '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].<br />
<br />
* '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.<br />
<br />
=== [clear_variable] ===<br />
<br />
This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.<br />
<br />
* '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.<br />
<br />
== Other Internal Actions ==<br />
<br />
Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.<br />
<br />
=== [fire_event] ===<br />
<br />
Trigger a WML event<br />
<br />
* '''name''': the name of event to trigger<br />
<br />
* '''[primary_unit]''': ''(Optional)'' Primary unit for the event (usually the attacker). Will never match on a recall list unit. If it matches multiple units, only one will be chosen.<br />
** '''x,y''': ''(Optional)'' The location of this unit.<br />
<br />
* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary unit.<br />
<br />
* '''[primary_attack]''': Information passed to the primary attack filter and $weapon variable on the new event.<br />
<br />
* '''[secondary_attack]''': Information passed to the second attack filter and $second_weapon variable on the new event.<br />
<br />
=== [role] ===<br />
<br />
Tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.<br />
<br />
* '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.<br />
<br />
* '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.<br />
<br />
=== [insert_tag] ===<br />
<br />
Inserts a variable as WML. In other words, the value of the passed variable will be injected into the game as if they had been written out in WML form.<br />
<br />
*'''name''': The ["name"] to be given to the tag. This must be a valid WML tag name for anything to happen.<br />
<br />
*'''variable''': Name of the variable which will have it's value inserted into the tag.<br />
<br />
For example:<br />
<br />
[event]<br />
name=moveto<br />
<br />
[set_variable]<br />
name=temp.speaker<br />
value=Konrad<br />
[/set_variable]<br />
<br />
[set_variable]<br />
name=temp.message<br />
value= _ "Yo Kalenz!"<br />
[/set_variable] <br />
<br />
[insert_tag]<br />
name=message<br />
variable=temp<br />
[/insert_tag]<br />
[/event]<br />
<br />
This is effectively identical to:<br />
<br />
[event]<br />
name=moveto<br />
<br />
[message]<br />
speaker=Konrad<br />
message= _ "Yo Kalenz!"<br />
[/message]<br />
[/event]<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[ConditionalWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWML&diff=29051InternalActionsWML2009-03-22T16:15:27Z<p>Voris: First pass cleanup of page organization.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Internal actions are actions that WML uses internally that do not directly affect game play (or, at least, are not readily apparent to the player). For example, storing a variable is an internal action.<br />
<br />
== Variable Actions ==<br />
<br />
These actions are focused, in one way or another, on [[VariablesWML|variables]]. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.<br />
<br />
=== [set_variable] ===<br />
<br />
The '''[set_variable]''' tag is used to create and manipulate WML variables. The following keys are used with this tag:<br />
<br />
* '''name''': the name of the variable to manipulate<br />
<br />
* '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])<br />
<br />
* '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.<br />
<br />
* '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.<br />
<br />
* '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.<br />
<br />
* '''add''': add the given amount to the variable. To subtract, add a negative number.<br />
<br />
* '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. Floating point values are not rounded.<br />
<br />
* '''divide''': divide the variable by the given number. The result is an integer. Floating point results are not rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.<br />
<br />
* '''modulo''': returns the remainder of a division.<br />
<br />
* '''random''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.<br />
<br />
* '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''<br />
<br />
* '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.<br />
<br />
* '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).<br />
<br />
* '''[join]''' joins an array of strings to create a textual list<br />
**variable: name of the array<br />
**key: the key of each array element(array[$i].foo) in which the strings are stored<br />
**separator: separator to connect the elements<br />
**remove_empty: whether to ignore empty elements<br />
<br />
* '''ipart''': Assigns the integer part (the part to the left of the comma) of the referenced variable.<br />
<br />
* '''fpart''': Assigns the decimal part (the part to the right of the comma) of the referenced variable.<br />
<br />
* '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:<br />
**'''ceil''': Rounds upward to the nearest integer.<br />
**'''floor''': Rounds down to the nearest integer.<br />
<br />
=== [set_variables] ===<br />
<br />
Manipulates a WML array<br />
<br />
* '''name''': the name of the container to manipulate<br />
<br />
* '''mode''': one of the following values:<br />
**replace: will clean the array '''name''' and replace it with given data<br />
**append: will append given data to the current array<br />
**merge: will merge in the given data into '''name'''<br />
**insert: will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.<br />
<br />
* '''to_variable''': data will be set to the given array<br />
<br />
* '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags, example:<br />
[set_variables]<br />
name=arr<br />
mode=replace<br />
[value]<br />
foo=bar<br />
[/value]<br />
[value]<br />
foo=more<br />
[/value]<br />
[/set_variables]<br />
{DEBUG_MSG $arr[0].foo}<br />
{DEBUG_MSG $arr[1].foo}<br />
=>bar; more<br />
<br />
* '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags<br />
<br />
*'''[split]''' splits a textual list into an array which will then be set to data<br />
**list: textual list to split<br />
**key: the key of each array element(array[$i].foo) in which the strings are stored<br />
**separator: separator to separate the elements<br />
**remove_empty: wether to ignore empty elements<br />
<br />
=== Capturing Game Data ===<br />
<br />
These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.<br />
<br />
==== [store_unit] ====<br />
<br />
Stores details about units into game variables.<br>Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.<br>Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]<br />
<br />
* '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.<br />
<br />
* '''variable''': the name of the variable into which to store the unit(s)<br />
<br />
* '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.<br />
<br />
* '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.<br />
:When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with '''[set_variable]'''. Here is a sample list. (If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.)<br />
<br />
:* advances_to<br />
:* alignment<br />
:* alpha<br />
:* attacks_left<br />
:* canrecruit<br />
:* cost<br />
:* experience<br />
:* facing<br />
:* flying<br />
:* gender<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* id<br />
:* language_name (same as the name key in the unit config)<br />
:* max_experience<br />
:* max_hitpoints<br />
:* max_moves<br />
:* moves<br />
:* overlays<br />
:* resting<br />
:* side<br />
:* type<br />
:* unit_description<br />
:* unrenamable<br />
:* upkeep<br />
:* x<br />
:* y<br />
:* zoc<br />
:* [advancement]<br />
:* [movement_costs]<br />
:* [defense]<br />
:* [resistance]<br />
:* [variables]<br />
:* [status]<br />
:* [attack]<br />
:* [modifications_description]<br />
:* [modifications]<br />
<br />
The bracketed values (advancement, movement_costs, defense, etc.) are children of the stored unit variable. Example:<br />
[set_variable]<br />
name=unit_store.status.poisoned<br />
value=yes<br />
[/set_variable]<br />
<br />
==== [store_starting_location] ====<br />
<br />
Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and 'owner_side' (villages only)<br />
<br />
* '''side''': the side whose starting location is to be stored<br />
<br />
* '''variable''': (default='location'): the name of the variable to store the location in<br />
<br />
==== [store_locations] ====<br />
<br />
Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only).<br />
<br />
* [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.<br />
<br />
* '''variable''': the name of the variable (array) into which to store the locations<br />
<br />
* '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.<br />
<br />
* '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored<br />
<br />
* '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.<br />
<br />
==== [store_villages] ====<br />
<br />
Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.<br />
<br />
* '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages. <br />
<br />
* '''variable''': the name of the variable (array) into which to store the locations<br />
<br />
* '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.<br />
<br />
==== [store_gold] ====<br />
<br />
Stores a side's gold into a variable.<br />
<br />
* '''side''': (default=1) the side for which the gold should be stored<br />
<br />
* '''variable''': (default='gold') the name of the variable to store the gold in<br />
<br />
==== [store_side] ====<br />
<br />
Stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.<br />
<br />
* '''side''': the side whose information should be stored<br />
<br />
* '''variable''': the name of the variable to store the information in<br />
<br />
==== [store_map_dimensions] ====<br />
<br />
Stores the map dimensions in a variable.<br />
<br />
* '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.<br />
<br />
==== [store_time_of_day] ====<br />
<br />
Stores time of day information from the current scenario into a WML variable container.<br />
<br />
* '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].<br />
<br />
* '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.<br />
<br />
=== [clear_variable] ===<br />
<br />
This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.<br />
<br />
* '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.<br />
<br />
== Other Internal Actions ==<br />
<br />
Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.<br />
<br />
=== [fire_event] ===<br />
<br />
Trigger a WML event<br />
<br />
* '''name''': the name of event to trigger<br />
<br />
* '''[primary_unit]''': ''(Optional)'' Primary unit for the event (usually the attacker). Will never match on a recall list unit. If it matches multiple units, only one will be chosen.<br />
** '''x,y''': ''(Optional)'' The location of this unit.<br />
<br />
* '''[secondary_unit]''': ''(Optional)'' Same as '''[primary_unit]''' except for the secondary unit.<br />
<br />
* '''[primary_attack]''': Information passed to the primary attack filter and $weapon variable on the new event.<br />
<br />
* '''[secondary_attack]''': Information passed to the second attack filter and $second_weapon variable on the new event.<br />
<br />
=== [role] ===<br />
<br />
Tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.<br />
<br />
* '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.<br />
<br />
* '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.<br />
<br />
=== [insert_tag] ===<br />
<br />
Inserts a variable as WML. In other words, the value of the passed variable will be injected into the game as if they had been written out in WML form.<br />
<br />
*'''name''': The ["name"] to be given to the tag. This must be a valid WML tag name for anything to happen.<br />
<br />
*'''variable''': Name of the variable which will have it's value inserted into the tag.<br />
<br />
For example:<br />
<br />
[event]<br />
name=moveto<br />
<br />
[set_variable]<br />
name=temp.speaker<br />
value=Konrad<br />
[/set_variable]<br />
<br />
[set_variable]<br />
name=temp.message<br />
value= _ "Yo Kalenz!"<br />
[/set_variable] <br />
<br />
[insert_tag]<br />
name=message<br />
variable=temp<br />
[/insert_tag]<br />
[/event]<br />
<br />
This is effectively identical to:<br />
<br />
[event]<br />
name=moveto<br />
<br />
[message]<br />
speaker=Konrad<br />
message= _ "Yo Kalenz!"<br />
[/message]<br />
[/event]<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[ConditionalWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWML&diff=29022InternalActionsWML2009-03-22T14:31:22Z<p>Voris: Killed [event] reference. It was describing nested events which are not really internal actions and already covered in EventWML.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Internal actions are actions that WML uses internally that do not directly affect game play. For example, storing a variable is an internal action.<br />
<br />
== Variable Actions ==<br />
<br />
These tags describe actions that affect the values of WML variables<br />
(see [[VariablesWML]] for information on WML variables,<br />
and [[UtilWML]] for convenient macro shortcuts for some of these):<br />
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}}<br />
** '''name''': the name of the variable to manipulate<br />
** '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])<br />
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.<br />
** '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.<br />
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.<br />
** '''add''': add the given amount to the variable. To subtract, add a negative number.<br />
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. Floating point values are not rounded.<br />
** '''divide''': divide the variable by the given number. The result is an integer. Floating point results are not rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.<br />
** '''modulo''': returns the remainder of a division.<br />
** '''random''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.<br />
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''<br />
** '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.<br />
** '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).<br />
** '''[join]''' joins an array of strings to create a textual list<br />
***variable: name of the array<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to connect the elements<br />
***remove_empty: whether to ignore empty elements<br />
** '''ipart''': Assigns the integer part (the part to the left of the comma) of the referenced variable.<br />
** '''fpart''': Assigns the decimal part (the part to the right of the comma) of the referenced variable.<br />
** '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:<br />
***'''ceil''': Rounds upward to the nearest integer.<br />
***'''floor''': Rounds down to the nearest integer.<br />
<br />
* '''[set_variables]''': manipulates a WML array<br />
** '''name''': the name of the container to manipulate<br />
** '''mode''': one of the following values:<br />
***replace: will clean the array '''name''' and replace it with given data<br />
***append: will append given data to the current array<br />
***merge: will merge in the given data into '''name'''<br />
***insert: will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.<br />
** '''to_variable''': data will be set to the given array<br />
** '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags, example:<br />
[set_variables]<br />
name=arr<br />
mode=replace<br />
[value]<br />
foo=bar<br />
[/value]<br />
[value]<br />
foo=more<br />
[/value]<br />
[/set_variables]<br />
{DEBUG_MSG $arr[0].foo}<br />
{DEBUG_MSG $arr[1].foo}<br />
=>bar; more<br />
** '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags<br />
**'''[split]''' splits a textual list into an array which will then be set to data<br />
***list: textual list to split<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to separate the elements<br />
***remove_empty: wether to ignore empty elements<br />
<br />
* '''[fire_event]''': trigger a WML event<br />
** '''name''': the name of event to trigger<br />
** '''[primary_unit]''': (optional) primary unit for the event (usually the attacker). Will never match on a recall list unit. If it matches multiple units, only one will be chosen.<br />
** '''[secondary_unit]''': (optional) same as '''[primary_unit]''' except for the secondary unit.<br />
** both tags have some keys which are optional :<br />
*** '''x,y''': location of this unit<br />
** '''[primary_attack]''': information passed to the primary attack filter and $weapon variable on the new event.<br />
** '''[secondary_attack]''': information passed to the second attack filter and $second_weapon variable on the new event.<br />
<br />
* '''[store_unit]''': stores details about units into game variables.<br>Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.<br>Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]<br />
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.<br />
** '''variable''': the name of the variable into which to store the unit(s)<br />
** '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.<br />
** '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.<br />
:When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with '''[set_variable]'''. Here is a sample list. (If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.)<br />
<br />
:* advances_to<br />
:* alignment<br />
:* alpha<br />
:* attacks_left<br />
:* canrecruit<br />
:* controller<br />
:* cost<br />
:* description<br />
:* experience<br />
:* facing<br />
:* flying<br />
:* fog<br />
:* gender<br />
:* get_hit_sound<br />
:* gold<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* id<br />
:* image<br />
:* image_defensive<br />
:* income<br />
:* language_name (same as the name key in the unit config)<br />
:* level<br />
:* max_attacks<br />
:* max_experience<br />
:* max_hitpoints<br />
:* max_moves<br />
:* movement<br />
:* movement_type<br />
:* moves<br />
:* overlays<br />
:* race<br />
:* resting<br />
:* shroud<br />
:* side<br />
:* type<br />
:* unit_description<br />
:* unrenamable<br />
:* usage<br />
:* upkeep<br />
:* value<br />
:* x<br />
:* y<br />
:* zoc<br />
:* [advancement]<br />
:* [movement_costs]<br />
:* [defense]<br />
:* [resistance]<br />
:* [variables]<br />
:* [status]<br />
:* [attack]<br />
:* [modifications_description]<br />
:* [modifications]<br />
<br />
The bracketed values (advancement, movement_costs, defense, etc.) are children of the stored unit variable. Example:<br />
[set_variable]<br />
name=unit_store.status.poisoned<br />
value=yes<br />
[/set_variable]<br />
<br />
:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.<br />
<br />
* '''[store_starting_location]''': Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and 'owner_side' (villages only)<br />
** '''side''': the side whose starting location is to be stored<br />
** '''variable''': (default='location'): the name of the variable to store the location in<br />
* '''[store_locations]''': Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only).<br />
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.<br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.<br />
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored<br />
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.<br />
* '''[store_villages]''': Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.<br />
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages. <br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.<br />
* '''[store_gold]''': Stores a side's gold into a variable.<br />
** '''side''': (default=1) the side for which the gold should be stored<br />
** '''variable''': (default='gold') the name of the variable to store the gold in<br />
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.<br />
** '''side''': the side whose information should be stored<br />
** '''variable''': the name of the variable to store the information in<br />
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.<br />
** '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.<br />
* '''[role]''': tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.<br />
** '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.<br />
** '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.<br />
* '''[store_map_dimensions]''': Stores the map dimensions in a variable.<br />
** '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.<br />
* '''[insert_tag]''': inserts a variable as WML<br />
**'''name''': the ["name"] to be given to the tag<br />
**'''variable''': name of the variable to be inserted<br />
* '''[store_time_of_day]''': stores time of day information from the current scenario into a WML variable container.<br />
** '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].<br />
** '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[ConditionalWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWML&diff=29020InternalActionsWML2009-03-22T14:22:58Z<p>Voris: Killed redundant unit keys listing.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Internal actions are actions that WML uses internally that do not directly affect game play. For example, storing a variable is an internal action.<br />
<br />
== [event] ==<br />
<br />
This adds a new event to the scenario.<br />
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).<br />
This is useful if you want an event that can only be triggered when a prior event is fulfilled<br />
<br />
== Variable Actions ==<br />
<br />
These tags describe actions that affect the values of WML variables<br />
(see [[VariablesWML]] for information on WML variables,<br />
and [[UtilWML]] for convenient macro shortcuts for some of these):<br />
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}}<br />
** '''name''': the name of the variable to manipulate<br />
** '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])<br />
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.<br />
** '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.<br />
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.<br />
** '''add''': add the given amount to the variable. To subtract, add a negative number.<br />
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. Floating point values are not rounded.<br />
** '''divide''': divide the variable by the given number. The result is an integer. Floating point results are not rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.<br />
** '''modulo''': returns the remainder of a division.<br />
** '''random''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.<br />
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''<br />
** '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.<br />
** '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).<br />
** '''[join]''' joins an array of strings to create a textual list<br />
***variable: name of the array<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to connect the elements<br />
***remove_empty: whether to ignore empty elements<br />
** '''ipart''': Assigns the integer part (the part to the left of the comma) of the referenced variable.<br />
** '''fpart''': Assigns the decimal part (the part to the right of the comma) of the referenced variable.<br />
** '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:<br />
***'''ceil''': Rounds upward to the nearest integer.<br />
***'''floor''': Rounds down to the nearest integer.<br />
<br />
* '''[set_variables]''': manipulates a WML array<br />
** '''name''': the name of the container to manipulate<br />
** '''mode''': one of the following values:<br />
***replace: will clean the array '''name''' and replace it with given data<br />
***append: will append given data to the current array<br />
***merge: will merge in the given data into '''name'''<br />
***insert: will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.<br />
** '''to_variable''': data will be set to the given array<br />
** '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags, example:<br />
[set_variables]<br />
name=arr<br />
mode=replace<br />
[value]<br />
foo=bar<br />
[/value]<br />
[value]<br />
foo=more<br />
[/value]<br />
[/set_variables]<br />
{DEBUG_MSG $arr[0].foo}<br />
{DEBUG_MSG $arr[1].foo}<br />
=>bar; more<br />
** '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags<br />
**'''[split]''' splits a textual list into an array which will then be set to data<br />
***list: textual list to split<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to separate the elements<br />
***remove_empty: wether to ignore empty elements<br />
<br />
* '''[fire_event]''': trigger a WML event<br />
** '''name''': the name of event to trigger<br />
** '''[primary_unit]''': (optional) primary unit for the event (usually the attacker). Will never match on a recall list unit. If it matches multiple units, only one will be chosen.<br />
** '''[secondary_unit]''': (optional) same as '''[primary_unit]''' except for the secondary unit.<br />
** both tags have some keys which are optional :<br />
*** '''x,y''': location of this unit<br />
** '''[primary_attack]''': information passed to the primary attack filter and $weapon variable on the new event.<br />
** '''[secondary_attack]''': information passed to the second attack filter and $second_weapon variable on the new event.<br />
<br />
* '''[store_unit]''': stores details about units into game variables.<br>Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.<br>Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]<br />
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.<br />
** '''variable''': the name of the variable into which to store the unit(s)<br />
** '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.<br />
** '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.<br />
:When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with '''[set_variable]'''. Here is a sample list. (If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.)<br />
<br />
:* advances_to<br />
:* alignment<br />
:* alpha<br />
:* attacks_left<br />
:* canrecruit<br />
:* controller<br />
:* cost<br />
:* description<br />
:* experience<br />
:* facing<br />
:* flying<br />
:* fog<br />
:* gender<br />
:* get_hit_sound<br />
:* gold<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* id<br />
:* image<br />
:* image_defensive<br />
:* income<br />
:* language_name (same as the name key in the unit config)<br />
:* level<br />
:* max_attacks<br />
:* max_experience<br />
:* max_hitpoints<br />
:* max_moves<br />
:* movement<br />
:* movement_type<br />
:* moves<br />
:* overlays<br />
:* race<br />
:* resting<br />
:* shroud<br />
:* side<br />
:* type<br />
:* unit_description<br />
:* unrenamable<br />
:* usage<br />
:* upkeep<br />
:* value<br />
:* x<br />
:* y<br />
:* zoc<br />
:* [advancement]<br />
:* [movement_costs]<br />
:* [defense]<br />
:* [resistance]<br />
:* [variables]<br />
:* [status]<br />
:* [attack]<br />
:* [modifications_description]<br />
:* [modifications]<br />
<br />
The bracketed values (advancement, movement_costs, defense, etc.) are children of the stored unit variable. Example:<br />
[set_variable]<br />
name=unit_store.status.poisoned<br />
value=yes<br />
[/set_variable]<br />
<br />
:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.<br />
<br />
* '''[store_starting_location]''': Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and 'owner_side' (villages only)<br />
** '''side''': the side whose starting location is to be stored<br />
** '''variable''': (default='location'): the name of the variable to store the location in<br />
* '''[store_locations]''': Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only).<br />
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.<br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.<br />
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored<br />
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.<br />
* '''[store_villages]''': Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.<br />
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages. <br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.<br />
* '''[store_gold]''': Stores a side's gold into a variable.<br />
** '''side''': (default=1) the side for which the gold should be stored<br />
** '''variable''': (default='gold') the name of the variable to store the gold in<br />
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden', 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.<br />
** '''side''': the side whose information should be stored<br />
** '''variable''': the name of the variable to store the information in<br />
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.<br />
** '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.<br />
* '''[role]''': tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.<br />
** '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.<br />
** '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.<br />
* '''[store_map_dimensions]''': Stores the map dimensions in a variable.<br />
** '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.<br />
* '''[insert_tag]''': inserts a variable as WML<br />
**'''name''': the ["name"] to be given to the tag<br />
**'''variable''': name of the variable to be inserted<br />
* '''[store_time_of_day]''': stores time of day information from the current scenario into a WML variable container.<br />
** '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].<br />
** '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[ConditionalWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=Template:WML_Tags&diff=29015Template:WML Tags2009-03-22T13:26:30Z<p>Voris: Putting back in a few clobbered additions.</p>
<hr />
<div>{| class="gallery" style="width:225px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 7pt;margin-left;10px;"<br />
|-<br />
|<br />
<span style="float: right;"><small class="editlink noprint plainlinksneverexpand">[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit ]</small></span><br />
'''WML Tags'''<br />
<br />
|-<br />
|''A:'' <br />
[[AbilitiesWML|abilities]],<br />
[[CampaignWML|about]],<br />
[[UnitWML|advancefrom]],<br />
[[UnitWML|advancement]],<br />
[[StatisticalScenarioWML|advances]],<br />
[[AiWML|ai]],<br />
[[DirectActionsWML|allow_recruit]],<br />
[[DirectActionsWML|allow_undo]],<br />
[[ConditionalActionsWML#Meta_Condition_Tags|and]],<br />
[[InterfaceActionsWML|animate_unit]],<br />
[[AnimationWML|animation]],<br />
[[VariablesWML|array]],<br />
[[UnitWML|attack]],<br />
[[AnimationWML|attack_filter]], <br />
[[StatisticalScenarioWML|attacks]],<br />
[[AiWML|avoid]];<br />
|-<br />
|''B:'' <br />
[[UnitWML|base_unit]], [[CampaignWML#The_.5Bbinary_path.5D_tag|binary_path]], [[HelpWML|bold]], [[EditorWML|brush]];<br />
|-<br />
|''C:'' <br />
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],<br />
[[DirectActionsWML|capture_village]],<br />
[[ConditionalActionsWML#.5Bswitch.5D|case]],<br />
[[ReplayWML|choose]],<br />
[[InternalActionsWML|clear_variable]],<br />
[[InterfaceActionsWML|colour_adjust]],<br />
command([[InterfaceActionsWML|action]], [[ReplayWML|replay]]);<br />
|-<br />
|''D:'' <br />
[[AbilitiesWML|damage]],<br />
[[StatisticalScenarioWML|deaths]],<br />
[[InterfaceActionsWML|debug_message]],<br />
[[UnitWML|defend]],<br />
[[StatisticalScenarioWML|defends]],<br />
[[UnitWML|defense]],<br />
[[InterfaceActionsWML|delay]],<br />
[[ReplayWML|destination]],<br />
[[DirectActionsWML|disallow_recruit]],<br />
[[ConditionalActionsWML#.5Bwhile.5D|do]];<br />
|-<br />
|''E:'' <br />
[[EditorWML|editor_group]],<br />
[[EditorWML|editor_music]], <br />
[[EditorWML|editor_times]],<br />
[[EditorWML|editor_tool_hint]],<br />
[[EffectWML|effect]],<br />
[[ConditionalActionsWML#Conditional_Actions|else]],<br />
[[ReplayWML|end_turn]],<br />
[[DirectActionsWML|endlevel]],<br />
end_turn&nbsp;([[DirectActionsWML|action]], [[ReplayWML|replay]]),<br />
[[EraWML|era]],<br />
[[EventWML|event]],<br />
[[ThemeWML|expenses]];<br />
|-<br />
|''F:'' <br />
[[EventWML#.5Bfilter.5D|filter]],<br />
[[FilterWML|filter]],<br />
[[AnimationWML|filter_attack]],<br />
[[EventWML#.5Bfilter_attack.5D|filter_attack]],<br />
[[FilterWML|filter_location]],<br />
[[EventWML#.5Bfilter_second.5D|filter_second]],<br />
[[FilterWML|filter_second]],<br />
[[AnimationWML|filter_second_attack]],<br />
[[EventWML#.5Bfilter_second_attack.5D|filter_second_attack]],<br />
[[FilterWML|filter_vision]],<br />
[[StandardUnitFilter|filter_wml]],<br />
[[InternalActionsWML|fire_event]],<br />
[[HelpWML|format]],<br />
[[AnimationWML|frame]];<br />
|-<br />
|''G:'' <br />
[[GameConfigWML|game_config]],<br />
[[ScenarioWML|generator]],<br />
[[DirectActionsWML|gold]],<br />
[[ThemeWML|gold]];<br />
|-<br />
|''H:'' <br />
[[ConditionalActionsWML#Condition_Tags|have_location]],<br />
[[ConditionalActionsWML#Condition_Tags|have_unit]],<br />
[[HelpWML|header]],<br />
[[DirectActionsWML|heal_unit]],<br />
[[InterfaceActionsWML|hide_unit]];<br />
|-<br />
|''I:'' <br />
[[ConditionalActionsWML#.5Bif.5D|if]],<br />
[[TimeWML|illuminated_time]],<br />
[[TerrainGraphicsWML|image]],<br />
[[HelpWML|img]],<br />
[[ThemeWML|income]],<br />
[[InternalActionsWML|insert_tag]],<br />
[[HelpWML|italic]],<br />
[[InterfaceActionsWML|item]];<br />
|-<br />
|''J:''<br />
[[HelpWML|jump]],<br />
[[InternalActionsWML|join]];<br />
|-<br />
|''K:'' <br />
[[DirectActionsWML|kill]],<br />
[[StatisticalScenarioWML|killed]];<br />
|-<br />
|''L:'' <br />
[[LabelWML|label]] ([[InterfaceActionsWML|map]], [[ThemeWML|theme]]),<br />
[[LanguageWML|language]],<br />
[[AiWML|leader_goal]];<br />
|-<br />
|''M:'' <br />
[[ThemeWML|main_map]],<br />
[[ThemeWML|menu]],<br />
[[InterfaceActionsWML|message]],<br />
[[ThemeWML|mini_map]],<br />
[[AnimationWML|missile_frame]],<br />
[[SingleUnitWML|modifications]],<br />
[[DirectActionsWML|modify_side]],<br />
[[DirectActionsWML|modify_turns]],<br />
[[ReplayWML|move]],<br />
[[InterfaceActionsWML|move_unit_fake]],<br />
[[UnitWML|movement costs]],<br />
[[UnitsWML|movetype]],<br />
[[ScenarioWML|multiplayer]],<br />
[[EraWML|multiplayer_side]],<br />
[[InterfaceActionsWML|music]];<br />
|-<br />
|''N:'' <br />
[[AnimationWML|neighbour_unit_filter]],<br />
[[ConditionalActionsWML#Meta_Condition_Tags|not]],<br />
[[FilterWML|not]],<br />
[[ThemeWML|num_units]];<br />
|-<br />
|''O:'' <br />
[[DirectActionsWML|object]],<br />
[[InterfaceActionsWML|objectives]],<br />
[[InterfaceActionsWML|objective]],<br />
[[ThemeWML|observers]],<br />
[[InterfaceActionsWML|open_help]],<br />
[[InterfaceActionsWML|option]],<br />
[[ConditionalActionsWML#Meta_Condition_Tags|or]];<br />
|-<br />
|''P:'' <br />
[[ThemeWML|panel]], [[IntroWML|part]], [[DirectActionsWML|place_shroud]], [[ThemeWML|position]],<br />
[[InterfaceActionsWML|print]], [[AiWML|protect_location]], [[AiWML|protect_unit]];<br />
|-<br />
|''R:'' <br />
[[UnitsWML|race]], [[ReplayWML|random]], recall&nbsp;([[DirectActionsWML|action]], <br />
[[ReplayWML|replay]]), [[StatisticalScenarioWML|recalls]],<br />
[[ReplayWML|recruit]], [[StatisticalScenarioWML|recruits]], [[InterfaceActionsWML|redraw]],<br />
[[HelpWML|ref]], [[DirectActionsWML|remove_shroud]], [[InterfaceActionsWML|remove_unit_overlay]],<br />
[[InterfaceActionsWML|removeitem]], [[InterfaceActionsWML|remove_sound_source]], <br />
[[ReplaceMapWML|replace_map]] [[SavefileWML|replay]], [[SavefileWML|replay_start]],<br />
[[UnitWML|resistance]], [[ThemeWML|resolution]], [[ReplayWML|results]], [[InternalActionsWML|role]];<br />
|-<br />
|''S:'' <br />
[[SavefileWML|save]], [[ScenarioWML|scenario]],<br />
[[InterfaceActionsWML|scroll]], [[InterfaceActionsWML|scroll_to]],<br />
[[InterfaceActionsWML|scroll_to_unit]], [[AnimationWML|secondary_attack_filter]], [[AnimationWML|secondary_unit_filter]], [[HelpWML|section]],<br />
[[InterfaceActionsWML#.5Bset_menu_item.5D_.28SVN_trunk_only.29|set_menu_item]], [[DirectActionsWML|set_recruit]],<br />
[[InternalActionsWML|set_variable]], [[InternalActionsWML|set_variables]], [[InterfaceActionsWML|show_objectives]],<br />
[[SideWML|side]], [[ThemeWML|side_playing]], [[SavefileWML|snapshot]],<br />
[[InterfaceActionsWML|sound]], [[InterfaceActionsWML|sound_source]], [[ReplayWML|source]], [[EventWML|special_filter]], [[EventWML|special_filter_second]],<br />
[[InternalActionsWML|split]],<br />
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],<br />
[[ThemeWML|status]], [[DirectActionsWML|stone]], [[InternalActionsWML|store_gold]], [[InternalActionsWML|store_locations]],<br />
[[InternalActionsWML|store_map_dimensions]],<br />
[[InternalActionsWML|store_starting_location]], [[InternalActionsWML|store_side]], [[InternalActionsWML|store_time_of_day]], [[InternalActionsWML|store_unit]], [[InternalActionsWML|store_villages]] [[IntroWML|story]],<br />
[[ConditionalActionsWML#.5Bswitch.5D|switch]];<br />
|-<br />
|''T:'' <br />
[[AiWML|target]],<br />
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],<br />
[[DirectActionsWML|teleport]], [[UnitWML|teleport_anim]],<br />
terrain([[TerrainWML|define]], [[DirectActionsWML|create]]), [[TerrainGraphicsWML|terrain_graphics]], [[TerrainMaskWML|terrain_mask]], [[ScenarioWML#Test_scenario|test]],<br />
[[WesCamp|textdomain]], [[InterfaceActionsWML|text_input]], [[ThemeWML|theme]], [[ConditionalActionsWML#.5Bif.5D|then]],<br />
[[TerrainGraphicsWML|tile]], [[TimeWML|time]], time_area&nbsp;([[DirectActionsWML|action]], [[ScenarioWML|scenario]]), <br />
[[ThemeWML|time_of_day]],<br />
[[HelpWML|topic]], [[HelpWML|toplevel]], [[SingleUnitWML|trait]], [[ThemeWML|turn]], [[ScenarioWML|tutorial]];<br />
|-<br />
|''U:'' <br />
[[InterfaceActionsWML|unhide_unit]], unit&nbsp;([[UnitWML|define]], [[SingleUnitWML|create]]),<br />
[[ThemeWML|unit_abilities]], [[ThemeWML|unit_alignment]], [[ThemeWML|unit_description]], [[AnimationWML|unit_filter]], [[ThemeWML|unit_hp]], [[ThemeWML|unit_image]], [[ThemeWML|unit_level]], [[ThemeWML|unit_moves]],<br />
[[InterfaceActionsWML|unit_overlay]], [[ThemeWML|unit_profile]], [[ThemeWML|unit_status]],<br />
[[ThemeWML|unit_traits]], [[ThemeWML|unit_type]], [[ThemeWML|unit_weapons]], [[ThemeWML|unit_xp]],<br />
[[UnitsWML|units]], [[DirectActionsWML|unstone]], [[DirectActionsWML|unstore_unit]], [[ThemeWML|upkeep]];<br />
|-<br />
| ''V:'' <br />
[[ConditionalActionsWML#Condition_Tags|variable]],<br />
[[VariablesWML|variables]],<br />
[[SideWML|village]],<br />
[[ThemeWML|villages]];<br />
|-<br />
| ''W:'' <br />
[[ConditionalActionsWML#.5Bwhile.5D|while]],<br />
[[InterfaceActionsWML|wml_message]];<br />
|}</div>Vorishttps://wiki.wesnoth.org/index.php?title=Template:WML_Tags&diff=28971Template:WML Tags2009-03-22T10:50:59Z<p>Voris: Updated for EventWML page renamed and missing tags.</p>
<hr />
<div>{| class="gallery" style="width:225px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 7pt;margin-left;10px;"<br />
|-<br />
|<br />
<span style="float: right;"><small class="editlink noprint plainlinksneverexpand">[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit ]</small></span><br />
'''WML Tags'''<br />
<br />
|-<br />
|''A:'' <br />
[[AbilitiesWML|abilities]],<br />
[[CampaignWML|about]],<br />
[[UnitWML|advancefrom]],<br />
[[UnitWML|advancement]],<br />
[[StatisticalScenarioWML|advances]],<br />
[[AiWML|ai]],<br />
[[DirectActionsWML|allow_recruit]],<br />
[[DirectActionsWML|allow_undo]],<br />
[[ConditionalActionsWML#Meta_Condition_Tags|and]],<br />
[[InterfaceActionsWML|animate_unit]],<br />
[[AnimationWML|animation]],<br />
[[VariablesWML|array]],<br />
[[UnitWML|attack]],<br />
[[AnimationWML|attack_filter]], <br />
[[StatisticalScenarioWML|attacks]],<br />
[[AiWML|avoid]];<br />
|-<br />
|''B:'' <br />
[[UnitWML|base_unit]], [[CampaignWML#The_.5Bbinary_path.5D_tag|binary_path]], [[HelpWML|bold]], [[EditorWML|brush]];<br />
|-<br />
|''C:'' <br />
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],<br />
[[DirectActionsWML|capture_village]],<br />
[[ConditionalActionsWML#.5Bswitch.5D|case]],<br />
[[ReplayWML|choose]],<br />
[[InternalActionsWML|clear_variable]],<br />
[[InterfaceActionsWML|colour_adjust]],<br />
command([[InterfaceActionsWML|action]], [[ReplayWML|replay]]);<br />
|-<br />
|''D:'' <br />
[[AbilitiesWML|damage]],<br />
[[StatisticalScenarioWML|deaths]],<br />
[[InterfaceActionsWML|debug_message]],<br />
[[UnitWML|defend]],<br />
[[StatisticalScenarioWML|defends]],<br />
[[UnitWML|defense]],<br />
[[InterfaceActionsWML|delay]],<br />
[[ReplayWML|destination]],<br />
[[DirectActionsWML|disallow_recruit]],<br />
[[ConditionalActionsWML#.5Bwhile.5D|do]];<br />
|-<br />
|''E:'' <br />
[[EditorWML|editor_group]],<br />
[[EditorWML|editor_music]], <br />
[[EditorWML|editor_times]],<br />
[[EditorWML|editor_tool_hint]],<br />
[[EffectWML|effect]],<br />
[[ConditionalActionsWML#Conditional_Actions|else]],<br />
[[ReplayWML|end_turn]],<br />
[[DirectActionsWML|endlevel]],<br />
end_turn&nbsp;([[DirectActionsWML|action]], [[ReplayWML|replay]]),<br />
[[EraWML|era]],<br />
[[EventWML|event]],<br />
[[ThemeWML|expenses]];<br />
|-<br />
|''F:'' <br />
[[EventWML#.5Bfilter.5D|filter]],<br />
[[FilterWML|filter]],<br />
[[EventWML#.5Bfilter_attack.5D|filter_attack]],<br />
[[FilterWML|filter_location]],<br />
[[EventWML#.5Bfilter_second.5D|filter_second]],<br />
[[FilterWML|filter_second]],<br />
[[EventWML#.5Bfilter_second_attack.5D|filter_second_attack]],<br />
[[FilterWML|filter_vision]],<br />
[[InternalActionsWML|fire_event]],<br />
[[HelpWML|format]],<br />
[[AnimationWML|frame]];<br />
|-<br />
|''G:'' <br />
[[GameConfigWML|game_config]],<br />
[[ScenarioWML|generator]],<br />
[[DirectActionsWML|gold]],<br />
[[ThemeWML|gold]];<br />
|-<br />
|''H:'' <br />
[[ConditionalActionsWML#Condition_Tags|have_location]],<br />
[[ConditionalActionsWML#Condition_Tags|have_unit]],<br />
[[HelpWML|header]],<br />
[[DirectActionsWML|heal_unit]],<br />
[[InterfaceActionsWML|hide_unit]];<br />
|-<br />
|''I:'' <br />
[[ConditionalActionsWML#.5Bif.5D|if]],<br />
[[TimeWML|illuminated_time]],<br />
[[TerrainGraphicsWML|image]],<br />
[[HelpWML|img]],<br />
[[ThemeWML|income]],<br />
[[InternalActionsWML|insert_tag]],<br />
[[HelpWML|italic]],<br />
[[InterfaceActionsWML|item]];<br />
|-<br />
|''J:''<br />
[[HelpWML|jump]],<br />
[[InternalActionsWML|join]];<br />
|-<br />
|''K:'' <br />
[[DirectActionsWML|kill]],<br />
[[StatisticalScenarioWML|killed]];<br />
|-<br />
|''L:'' <br />
[[LabelWML|label]] ([[InterfaceActionsWML|map]], [[ThemeWML|theme]]),<br />
[[LanguageWML|language]],<br />
[[AiWML|leader_goal]];<br />
|-<br />
|''M:'' <br />
[[ThemeWML|main_map]],<br />
[[ThemeWML|menu]],<br />
[[InterfaceActionsWML|message]],<br />
[[ThemeWML|mini_map]],<br />
[[AnimationWML|missile_frame]],<br />
[[SingleUnitWML|modifications]],<br />
[[DirectActionsWML|modify_side]],<br />
[[DirectActionsWML|modify_turns]],<br />
[[ReplayWML|move]],<br />
[[InterfaceActionsWML|move_unit_fake]],<br />
[[UnitWML|movement costs]],<br />
[[UnitsWML|movetype]],<br />
[[ScenarioWML|multiplayer]],<br />
[[EraWML|multiplayer_side]],<br />
[[InterfaceActionsWML|music]];<br />
|-<br />
|''N:'' <br />
[[AnimationWML|neighbour_unit_filter]],<br />
[[ConditionalActionsWML#Meta_Condition_Tags|not]],<br />
[[FilterWML|not]],<br />
[[ThemeWML|num_units]];<br />
|-<br />
|''O:'' <br />
[[DirectActionsWML|object]],<br />
[[InterfaceActionsWML|objectives]],<br />
[[InterfaceActionsWML|objective]],<br />
[[ThemeWML|observers]],<br />
[[InterfaceActionsWML|open_help]],<br />
[[InterfaceActionsWML|option]],<br />
[[ConditionalActionsWML#Meta_Condition_Tags|or]];<br />
|-<br />
|''P:'' <br />
[[ThemeWML|panel]], [[IntroWML|part]], [[DirectActionsWML|place_shroud]], [[ThemeWML|position]],<br />
[[InterfaceActionsWML|print]], [[AiWML|protect_location]], [[AiWML|protect_unit]];<br />
|-<br />
|''R:'' <br />
[[UnitsWML|race]], [[ReplayWML|random]], recall&nbsp;([[DirectActionsWML|action]], <br />
[[ReplayWML|replay]]), [[StatisticalScenarioWML|recalls]],<br />
[[ReplayWML|recruit]], [[StatisticalScenarioWML|recruits]], [[InterfaceActionsWML|redraw]],<br />
[[HelpWML|ref]], [[DirectActionsWML|remove_shroud]], [[InterfaceActionsWML|remove_unit_overlay]],<br />
[[InterfaceActionsWML|removeitem]], [[InterfaceActionsWML|remove_sound_source]], <br />
[[ReplaceMapWML|replace_map]] [[SavefileWML|replay]], [[SavefileWML|replay_start]],<br />
[[UnitWML|resistance]], [[ThemeWML|resolution]], [[ReplayWML|results]], [[InternalActionsWML|role]];<br />
|-<br />
|''S:'' <br />
[[SavefileWML|save]], [[ScenarioWML|scenario]],<br />
[[InterfaceActionsWML|scroll]], [[InterfaceActionsWML|scroll_to]],<br />
[[InterfaceActionsWML|scroll_to_unit]], [[AnimationWML|secondary_attack_filter]], [[AnimationWML|secondary_unit_filter]], [[HelpWML|section]],<br />
[[InterfaceActionsWML#.5Bset_menu_item.5D_.28SVN_trunk_only.29|set_menu_item]], [[DirectActionsWML|set_recruit]],<br />
[[InternalActionsWML|set_variable]], [[InternalActionsWML|set_variables]], <br />
[[SideWML|side]], [[ThemeWML|side_playing]], [[SavefileWML|snapshot]],<br />
[[InterfaceActionsWML|sound]], [[InterfaceActionsWML|sound_source]], [[ReplayWML|source]],<br />
[[InternalActionsWML|split]],<br />
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],<br />
[[ThemeWML|status]], [[DirectActionsWML|stone]], [[InternalActionsWML|store_gold]], [[InternalActionsWML|store_locations]],<br />
[[InternalActionsWML|store_map_dimensions]],<br />
[[InternalActionsWML|store_starting_location]], [[InternalActionsWML|store_side]], [[InternalActionsWML|store_time_of_day]], [[InternalActionsWML|store_unit]], [[InternalActionsWML|store_villages]] [[IntroWML|story]],<br />
[[ConditionalActionsWML#.5Bswitch.5D|switch]];<br />
|-<br />
|''T:'' <br />
[[AiWML|target]],<br />
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],<br />
[[DirectActionsWML|teleport]], [[UnitWML|teleport_anim]],<br />
terrain([[TerrainWML|define]], [[DirectActionsWML|create]]), [[TerrainGraphicsWML|terrain_graphics]], [[TerrainMaskWML|terrain_mask]], [[ScenarioWML#Test_scenario|test]],<br />
[[WesCamp|textdomain]], [[InterfaceActionsWML|text_input]], [[ThemeWML|theme]], [[ConditionalActionsWML#.5Bif.5D|then]],<br />
[[TerrainGraphicsWML|tile]], [[TimeWML|time]], time_area&nbsp;([[DirectActionsWML|action]], [[ScenarioWML|scenario]]), <br />
[[ThemeWML|time_of_day]],<br />
[[HelpWML|topic]], [[HelpWML|toplevel]], [[SingleUnitWML|trait]], [[ThemeWML|turn]], [[ScenarioWML|tutorial]];<br />
|-<br />
|''U:'' <br />
[[InterfaceActionsWML|unhide_unit]], unit&nbsp;([[UnitWML|define]], [[SingleUnitWML|create]]),<br />
[[ThemeWML|unit_abilities]], [[ThemeWML|unit_alignment]], [[ThemeWML|unit_description]], [[AnimationWML|unit_filter]], [[ThemeWML|unit_hp]], [[ThemeWML|unit_image]], [[ThemeWML|unit_level]], [[ThemeWML|unit_moves]],<br />
[[InterfaceActionsWML|unit_overlay]], [[ThemeWML|unit_profile]], [[ThemeWML|unit_status]],<br />
[[ThemeWML|unit_traits]], [[ThemeWML|unit_type]], [[ThemeWML|unit_weapons]], [[ThemeWML|unit_xp]],<br />
[[UnitsWML|units]], [[DirectActionsWML|unstone]], [[DirectActionsWML|unstore_unit]], [[ThemeWML|upkeep]];<br />
|-<br />
| ''V:'' <br />
[[ConditionalActionsWML#Condition_Tags|variable]],<br />
[[VariablesWML|variables]],<br />
[[SideWML|village]],<br />
[[ThemeWML|villages]];<br />
|-<br />
| ''W:'' <br />
[[ConditionalActionsWML#.5Bwhile.5D|while]],<br />
[[FilterWML|wml_filter]],<br />
[[InterfaceActionsWML|wml_message]];<br />
|}</div>Vorishttps://wiki.wesnoth.org/index.php?title=Template:WML_Tags&diff=28963Template:WML Tags2009-03-22T10:34:32Z<p>Voris: Added new and missing tags from ConditionalActionsWML page.</p>
<hr />
<div>{| class="gallery" style="width:225px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 7pt;margin-left;10px;"<br />
|-<br />
|<br />
<span style="float: right;"><small class="editlink noprint plainlinksneverexpand">[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit ]</small></span><br />
'''WML Tags'''<br />
<br />
|-<br />
|''A:'' <br />
[[AbilitiesWML|abilities]],<br />
[[CampaignWML|about]],<br />
[[UnitWML|advancefrom]],<br />
[[UnitWML|advancement]],<br />
[[StatisticalScenarioWML|advances]],<br />
[[AiWML|ai]],<br />
[[DirectActionsWML|allow_recruit]],<br />
[[DirectActionsWML|allow_undo]],<br />
[[ConditionalActionsWML#Meta_Condition_Tags|and]],<br />
[[InterfaceActionsWML|animate_unit]],<br />
[[AnimationWML|animation]],<br />
[[VariablesWML|array]],<br />
[[UnitWML|attack]],<br />
[[AnimationWML|attack_filter]], <br />
[[StatisticalScenarioWML|attacks]],<br />
[[AiWML|avoid]];<br />
|-<br />
|''B:'' <br />
[[UnitWML|base_unit]], [[CampaignWML#The_.5Bbinary_path.5D_tag|binary_path]], [[HelpWML|bold]], [[EditorWML|brush]];<br />
|-<br />
|''C:'' <br />
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],<br />
[[DirectActionsWML|capture_village]],<br />
[[ConditionalActionsWML#.5Bswitch.5D|case]],<br />
[[ReplayWML|choose]],<br />
[[InternalActionsWML|clear_variable]],<br />
[[InterfaceActionsWML|colour_adjust]],<br />
command([[InterfaceActionsWML|action]], [[ReplayWML|replay]]);<br />
|-<br />
|''D:'' <br />
[[AbilitiesWML|damage]],<br />
[[StatisticalScenarioWML|deaths]],<br />
[[InterfaceActionsWML|debug_message]],<br />
[[UnitWML|defend]],<br />
[[StatisticalScenarioWML|defends]],<br />
[[UnitWML|defense]],<br />
[[InterfaceActionsWML|delay]],<br />
[[ReplayWML|destination]],<br />
[[DirectActionsWML|disallow_recruit]],<br />
[[ConditionalActionsWML#.5Bwhile.5D|do]];<br />
|-<br />
|''E:'' <br />
[[EditorWML|editor_group]],<br />
[[EditorWML|editor_music]], <br />
[[EditorWML|editor_times]],<br />
[[EditorWML|editor_tool_hint]],<br />
[[EffectWML|effect]],<br />
[[ConditionalActionsWML#Conditional_Actions|else]],<br />
[[ReplayWML|end_turn]],<br />
[[DirectActionsWML|endlevel]],<br />
end_turn&nbsp;([[DirectActionsWML|action]], [[ReplayWML|replay]]),<br />
[[EraWML|era]],<br />
[[EventWML|event]],<br />
[[ThemeWML|expenses]];<br />
|-<br />
|''F:'' <br />
[[FilterWML|filter]], [[FilterWML|filter_location]], [[FilterWML|filter_second]], [[FilterWML|filter_vision]], [[InternalActionsWML|fire_event]], [[HelpWML|format]], [[AnimationWML|frame]];<br />
|-<br />
|''G:'' <br />
[[GameConfigWML|game_config]],<br />
[[ScenarioWML|generator]],<br />
[[DirectActionsWML|gold]],<br />
[[ThemeWML|gold]];<br />
|-<br />
|''H:'' <br />
[[ConditionalActionsWML#Condition_Tags|have_location]],<br />
[[ConditionalActionsWML#Condition_Tags|have_unit]],<br />
[[HelpWML|header]],<br />
[[DirectActionsWML|heal_unit]],<br />
[[InterfaceActionsWML|hide_unit]];<br />
|-<br />
|''I:'' <br />
[[ConditionalActionsWML#.5Bif.5D|if]],<br />
[[TimeWML|illuminated_time]],<br />
[[TerrainGraphicsWML|image]],<br />
[[HelpWML|img]],<br />
[[ThemeWML|income]],<br />
[[InternalActionsWML|insert_tag]],<br />
[[HelpWML|italic]],<br />
[[InterfaceActionsWML|item]];<br />
|-<br />
|''J:''<br />
[[HelpWML|jump]],<br />
[[InternalActionsWML|join]];<br />
|-<br />
|''K:'' <br />
[[DirectActionsWML|kill]],<br />
[[StatisticalScenarioWML|killed]];<br />
|-<br />
|''L:'' <br />
[[LabelWML|label]] ([[InterfaceActionsWML|map]], [[ThemeWML|theme]]),<br />
[[LanguageWML|language]],<br />
[[AiWML|leader_goal]];<br />
|-<br />
|''M:'' <br />
[[ThemeWML|main_map]],<br />
[[ThemeWML|menu]],<br />
[[InterfaceActionsWML|message]],<br />
[[ThemeWML|mini_map]],<br />
[[AnimationWML|missile_frame]],<br />
[[SingleUnitWML|modifications]],<br />
[[DirectActionsWML|modify_side]],<br />
[[DirectActionsWML|modify_turns]],<br />
[[ReplayWML|move]],<br />
[[InterfaceActionsWML|move_unit_fake]],<br />
[[UnitWML|movement costs]],<br />
[[UnitsWML|movetype]],<br />
[[ScenarioWML|multiplayer]],<br />
[[EraWML|multiplayer_side]],<br />
[[InterfaceActionsWML|music]];<br />
|-<br />
|''N:'' <br />
[[AnimationWML|neighbour_unit_filter]],<br />
[[ConditionalActionsWML#Meta_Condition_Tags|not]],<br />
[[FilterWML|not]],<br />
[[ThemeWML|num_units]];<br />
|-<br />
|''O:'' <br />
[[DirectActionsWML|object]],<br />
[[InterfaceActionsWML|objectives]],<br />
[[InterfaceActionsWML|objective]],<br />
[[ThemeWML|observers]],<br />
[[InterfaceActionsWML|open_help]],<br />
[[InterfaceActionsWML|option]],<br />
[[ConditionalActionsWML#Meta_Condition_Tags|or]];<br />
|-<br />
|''P:'' <br />
[[ThemeWML|panel]], [[IntroWML|part]], [[DirectActionsWML|place_shroud]], [[ThemeWML|position]],<br />
[[InterfaceActionsWML|print]], [[AiWML|protect_location]], [[AiWML|protect_unit]];<br />
|-<br />
|''R:'' <br />
[[UnitsWML|race]], [[ReplayWML|random]], recall&nbsp;([[DirectActionsWML|action]], <br />
[[ReplayWML|replay]]), [[StatisticalScenarioWML|recalls]],<br />
[[ReplayWML|recruit]], [[StatisticalScenarioWML|recruits]], [[InterfaceActionsWML|redraw]],<br />
[[HelpWML|ref]], [[DirectActionsWML|remove_shroud]], [[InterfaceActionsWML|remove_unit_overlay]],<br />
[[InterfaceActionsWML|removeitem]], [[InterfaceActionsWML|remove_sound_source]], <br />
[[ReplaceMapWML|replace_map]] [[SavefileWML|replay]], [[SavefileWML|replay_start]],<br />
[[UnitWML|resistance]], [[ThemeWML|resolution]], [[ReplayWML|results]], [[InternalActionsWML|role]];<br />
|-<br />
|''S:'' <br />
[[SavefileWML|save]], [[ScenarioWML|scenario]],<br />
[[InterfaceActionsWML|scroll]], [[InterfaceActionsWML|scroll_to]],<br />
[[InterfaceActionsWML|scroll_to_unit]], [[AnimationWML|secondary_attack_filter]], [[AnimationWML|secondary_unit_filter]], [[HelpWML|section]],<br />
[[InterfaceActionsWML#.5Bset_menu_item.5D_.28SVN_trunk_only.29|set_menu_item]], [[DirectActionsWML|set_recruit]],<br />
[[InternalActionsWML|set_variable]], [[InternalActionsWML|set_variables]], <br />
[[SideWML|side]], [[ThemeWML|side_playing]], [[SavefileWML|snapshot]],<br />
[[InterfaceActionsWML|sound]], [[InterfaceActionsWML|sound_source]], [[ReplayWML|source]], [[EventWML|special_filter]], [[EventWML|special_filter_second]],<br />
[[InternalActionsWML|split]],<br />
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],<br />
[[ThemeWML|status]], [[DirectActionsWML|stone]], [[InternalActionsWML|store_gold]], [[InternalActionsWML|store_locations]],<br />
[[InternalActionsWML|store_map_dimensions]],<br />
[[InternalActionsWML|store_starting_location]], [[InternalActionsWML|store_side]], [[InternalActionsWML|store_time_of_day]], [[InternalActionsWML|store_unit]], [[InternalActionsWML|store_villages]] [[IntroWML|story]],<br />
[[ConditionalActionsWML#.5Bswitch.5D|switch]];<br />
|-<br />
|''T:'' <br />
[[AiWML|target]],<br />
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],<br />
[[DirectActionsWML|teleport]], [[UnitWML|teleport_anim]],<br />
terrain([[TerrainWML|define]], [[DirectActionsWML|create]]), [[TerrainGraphicsWML|terrain_graphics]], [[TerrainMaskWML|terrain_mask]], [[ScenarioWML#Test_scenario|test]],<br />
[[WesCamp|textdomain]], [[InterfaceActionsWML|text_input]], [[ThemeWML|theme]], [[ConditionalActionsWML#.5Bif.5D|then]],<br />
[[TerrainGraphicsWML|tile]], [[TimeWML|time]], time_area&nbsp;([[DirectActionsWML|action]], [[ScenarioWML|scenario]]), <br />
[[ThemeWML|time_of_day]],<br />
[[HelpWML|topic]], [[HelpWML|toplevel]], [[SingleUnitWML|trait]], [[ThemeWML|turn]], [[ScenarioWML|tutorial]];<br />
|-<br />
|''U:'' <br />
[[InterfaceActionsWML|unhide_unit]], unit&nbsp;([[UnitWML|define]], [[SingleUnitWML|create]]),<br />
[[ThemeWML|unit_abilities]], [[ThemeWML|unit_alignment]], [[ThemeWML|unit_description]], [[AnimationWML|unit_filter]], [[ThemeWML|unit_hp]], [[ThemeWML|unit_image]], [[ThemeWML|unit_level]], [[ThemeWML|unit_moves]],<br />
[[InterfaceActionsWML|unit_overlay]], [[ThemeWML|unit_profile]], [[ThemeWML|unit_status]],<br />
[[ThemeWML|unit_traits]], [[ThemeWML|unit_type]], [[ThemeWML|unit_weapons]], [[ThemeWML|unit_xp]],<br />
[[UnitsWML|units]], [[DirectActionsWML|unstone]], [[DirectActionsWML|unstore_unit]], [[ThemeWML|upkeep]];<br />
|-<br />
| ''V:'' <br />
[[ConditionalActionsWML#Condition_Tags|variable]],<br />
[[VariablesWML|variables]],<br />
[[SideWML|village]],<br />
[[ThemeWML|villages]];<br />
|-<br />
| ''W:'' <br />
[[ConditionalActionsWML#.5Bwhile.5D|while]],<br />
[[FilterWML|wml_filter]],<br />
[[InterfaceActionsWML|wml_message]];<br />
|}</div>Vorishttps://wiki.wesnoth.org/index.php?title=Template:WML_Tags&diff=28958Template:WML Tags2009-03-22T10:07:23Z<p>Voris: Updated references to tags now on ConditionalActionsWML page.</p>
<hr />
<div>{| class="gallery" style="width:175px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 7pt;margin-left;10px;"<br />
|-<br />
|<br />
<span style="float: right;"><small class="editlink noprint plainlinksneverexpand">[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit ]</small></span><br />
'''WML Tags'''<br />
<br />
|-<br />
|''A:'' <br />
[[AbilitiesWML|abilities]],<br />
[[CampaignWML|about]],<br />
[[UnitWML|advancefrom]],<br />
[[UnitWML|advancement]],<br />
[[StatisticalScenarioWML|advances]],<br />
[[AiWML|ai]],<br />
[[DirectActionsWML|allow_recruit]],<br />
[[DirectActionsWML|allow_undo]],<br />
[[InterfaceActionsWML|animate_unit]],<br />
[[AnimationWML|animation]],<br />
[[VariablesWML|array]],<br />
[[UnitWML|attack]],<br />
[[AnimationWML|attack_filter]], <br />
[[StatisticalScenarioWML|attacks]],<br />
[[AiWML|avoid]];<br />
|-<br />
|''B:'' <br />
[[UnitWML|base_unit]],[[CampaignWML#The_.5Bbinary_path.5D_tag|binary_path]],[[HelpWML|bold]], [[EditorWML|brush]];<br />
|-<br />
|''C:'' <br />
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]], [[DirectActionsWML|capture_village]], [[ReplayWML|choose]],<br />
[[InternalActionsWML|clear_variable]],<br />
[[InterfaceActionsWML|colour_adjust]],<br />
command([[InterfaceActionsWML|action]], [[ReplayWML|replay]]);<br />
|-<br />
|''D:'' <br />
[[AbilitiesWML|damage]],[[StatisticalScenarioWML|deaths]],[[InterfaceActionsWML|debug_message]],[[UnitWML|defend]],[[StatisticalScenarioWML|defends]],<br />
[[UnitWML|defense]],<br />
[[InterfaceActionsWML|delay]],<br />
[[ReplayWML|destination]],<br />
[[DirectActionsWML|disallow_recruit]],<br />
[[ConditionalActionsWML#.5Bwhile.5D|do]];<br />
|-<br />
|''E:'' <br />
[[EditorWML|editor_group]], [[EditorWML|editor_music]], <br />
[[EditorWML|editor_times]], [[EditorWML|editor_tool_hint]],<br />
[[EffectWML|effect]],[[ConditionalActionsWML#Conditional_Actions|else]],[[ReplayWML|end_turn]],<br />
[[DirectActionsWML|endlevel]],<br />
end_turn&nbsp;([[DirectActionsWML|action]], [[ReplayWML|replay]]),<br />
[[EraWML|era]],<br />
[[EventWML|event]],<br />
[[ThemeWML|expenses]];<br />
|-<br />
|''F:'' <br />
[[FilterWML|filter]], [[FilterWML|filter_location]], [[FilterWML|filter_second]], [[FilterWML|filter_vision]], [[InternalActionsWML|fire_event]], [[HelpWML|format]], [[AnimationWML|frame]];<br />
|-<br />
|''G:'' <br />
[[GameConfigWML|game_config]], [[ScenarioWML|generator]], [[DirectActionsWML|gold]], [[ThemeWML|gold]];<br />
|-<br />
|''H:'' <br />
[[ConditionalActionsWML#Condition_Tags|have_unit]], [[HelpWML|header]], [[DirectActionsWML|heal_unit]],[[InterfaceActionsWML|hide_unit]];<br />
|-<br />
|''I:'' <br />
[[ConditionalActionsWML#.5Bif.5D|if]], [[TimeWML|illuminated_time]], [[TerrainGraphicsWML|image]],<br />
[[HelpWML|img]], [[ThemeWML|income]], [[InternalActionsWML|insert_tag]], [[HelpWML|italic]], [[InterfaceActionsWML|item]];<br />
|-<br />
|''J:''<br />
[[HelpWML|jump]], [[InternalActionsWML|join]];<br />
|-<br />
|''K:'' <br />
[[DirectActionsWML|kill]], [[StatisticalScenarioWML|killed]];<br />
|-<br />
|''L:'' <br />
[[LabelWML|label]] ([[InterfaceActionsWML|map]], [[ThemeWML|theme]]), [[LanguageWML|language]], [[AiWML|leader_goal]];<br />
|-<br />
|''M:'' <br />
[[ThemeWML|main_map]],[[ThemeWML|menu]], [[InterfaceActionsWML|message]], [[ThemeWML|mini_map]],<br />
[[AnimationWML|missile_frame]], [[SingleUnitWML|modifications]], [[DirectActionsWML|modify_side]],<br />
[[DirectActionsWML|modify_turns]], [[ReplayWML|move]], [[InterfaceActionsWML|move_unit_fake]], [[UnitWML|movement costs]],<br />
[[UnitsWML|movetype]], [[ScenarioWML|multiplayer]], [[EraWML|multiplayer_side]], [[InterfaceActionsWML|music]];<br />
|-<br />
|''N:'' <br />
[[AnimationWML|neighbour_unit_filter]], [[FilterWML|not]], [[ThemeWML|num_units]];<br />
|-<br />
|''O:'' <br />
[[DirectActionsWML|object]], [[InterfaceActionsWML|objectives]], [[InterfaceActionsWML|objective]],<br />
[[ThemeWML|observers]], [[InterfaceActionsWML|open_help]], [[InterfaceActionsWML|option]], [[ConditionalActionsWML#Meta_Condition_Tags|or]];<br />
|-<br />
|''P:'' <br />
[[ThemeWML|panel]], [[IntroWML|part]], [[DirectActionsWML|place_shroud]], [[ThemeWML|position]],<br />
[[InterfaceActionsWML|print]], [[AiWML|protect_location]], [[AiWML|protect_unit]];<br />
|-<br />
|''R:'' <br />
[[UnitsWML|race]], [[ReplayWML|random]], recall&nbsp;([[DirectActionsWML|action]], <br />
[[ReplayWML|replay]]), [[StatisticalScenarioWML|recalls]],<br />
[[ReplayWML|recruit]], [[StatisticalScenarioWML|recruits]], [[InterfaceActionsWML|redraw]],<br />
[[HelpWML|ref]], [[DirectActionsWML|remove_shroud]], [[InterfaceActionsWML|remove_unit_overlay]],<br />
[[InterfaceActionsWML|removeitem]], [[InterfaceActionsWML|remove_sound_source]], <br />
[[ReplaceMapWML|replace_map]] [[SavefileWML|replay]], [[SavefileWML|replay_start]],<br />
[[UnitWML|resistance]], [[ThemeWML|resolution]], [[ReplayWML|results]], [[InternalActionsWML|role]];<br />
|-<br />
|''S:'' <br />
[[SavefileWML|save]], [[ScenarioWML|scenario]],<br />
[[InterfaceActionsWML|scroll]], [[InterfaceActionsWML|scroll_to]],<br />
[[InterfaceActionsWML|scroll_to_unit]], [[AnimationWML|secondary_attack_filter]], [[AnimationWML|secondary_unit_filter]], [[HelpWML|section]],<br />
[[InterfaceActionsWML#.5Bset_menu_item.5D_.28SVN_trunk_only.29|set_menu_item]], [[DirectActionsWML|set_recruit]],<br />
[[InternalActionsWML|set_variable]], [[InternalActionsWML|set_variables]], <br />
[[SideWML|side]], [[ThemeWML|side_playing]], [[SavefileWML|snapshot]],<br />
[[InterfaceActionsWML|sound]], [[InterfaceActionsWML|sound_source]], [[ReplayWML|source]], [[EventWML|special_filter]], [[EventWML|special_filter_second]],<br />
[[InternalActionsWML|split]],<br />
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],<br />
[[ThemeWML|status]], [[DirectActionsWML|stone]], [[InternalActionsWML|store_gold]], [[InternalActionsWML|store_locations]],<br />
[[InternalActionsWML|store_map_dimensions]],<br />
[[InternalActionsWML|store_starting_location]], [[InternalActionsWML|store_side]], [[InternalActionsWML|store_time_of_day]], [[InternalActionsWML|store_unit]], [[InternalActionsWML|store_villages]] [[IntroWML|story]];<br />
|-<br />
|''T:'' <br />
[[AiWML|target]],<br />
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],<br />
[[DirectActionsWML|teleport]], [[UnitWML|teleport_anim]],<br />
terrain([[TerrainWML|define]], [[DirectActionsWML|create]]), [[TerrainGraphicsWML|terrain_graphics]], [[TerrainMaskWML|terrain_mask]], [[ScenarioWML#Test_scenario|test]],<br />
[[WesCamp|textdomain]], [[InterfaceActionsWML|text_input]], [[ThemeWML|theme]], [[ConditionalActionsWML#.5Bif.5D|then]],<br />
[[TerrainGraphicsWML|tile]], [[TimeWML|time]], time_area&nbsp;([[DirectActionsWML|action]], [[ScenarioWML|scenario]]), <br />
[[ThemeWML|time_of_day]],<br />
[[HelpWML|topic]], [[HelpWML|toplevel]], [[SingleUnitWML|trait]], [[ThemeWML|turn]], [[ScenarioWML|tutorial]];<br />
|-<br />
|''U:'' <br />
[[InterfaceActionsWML|unhide_unit]], unit&nbsp;([[UnitWML|define]], [[SingleUnitWML|create]]),<br />
[[ThemeWML|unit_abilities]], [[ThemeWML|unit_alignment]], [[ThemeWML|unit_description]], [[AnimationWML|unit_filter]], [[ThemeWML|unit_hp]], [[ThemeWML|unit_image]], [[ThemeWML|unit_level]], [[ThemeWML|unit_moves]],<br />
[[InterfaceActionsWML|unit_overlay]], [[ThemeWML|unit_profile]], [[ThemeWML|unit_status]],<br />
[[ThemeWML|unit_traits]], [[ThemeWML|unit_type]], [[ThemeWML|unit_weapons]], [[ThemeWML|unit_xp]],<br />
[[UnitsWML|units]], [[DirectActionsWML|unstone]], [[DirectActionsWML|unstore_unit]], [[ThemeWML|upkeep]];<br />
|-<br />
| ''V:'' <br />
[[InternalActionsWML|variable]], [[VariablesWML|variables]], [[SideWML|village]], [[ThemeWML|villages]];<br />
|-<br />
| ''W:'' <br />
[[ConditionalActionsWML#.5Bwhile.5D|while]], [[FilterWML|wml_filter]], [[InterfaceActionsWML|wml_message]];<br />
|}</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWML&diff=28948InternalActionsWML2009-03-22T01:26:46Z<p>Voris: Updated link-less reference to [if] with linked reference to conditionals page.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Internal actions are actions that WML uses internally that do not directly affect game play. For example, storing a variable is an internal action.<br />
<br />
== [event] ==<br />
<br />
This adds a new event to the scenario.<br />
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).<br />
This is useful if you want an event that can only be triggered when a prior event is fulfilled<br />
<br />
== Variable Actions ==<br />
<br />
These tags describe actions that affect the values of WML variables<br />
(see [[VariablesWML]] for information on WML variables,<br />
and [[UtilWML]] for convenient macro shortcuts for some of these):<br />
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}} {{DevFeature}} Floating-point arithmetic is now fully supported.<br />
** '''name''': the name of the variable to manipulate<br />
** '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])<br />
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.<br />
** '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.<br />
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.<br />
** '''add''': add the given amount to the variable. To subtract, add a negative number.<br />
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. {{DevFeature}} Floating point values are no longer rounded.<br />
** '''divide''': divide the variable by the given number. The result is an integer. {{DevFeature}} Floating point results are no longer rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.<br />
** '''modulo''': returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1. {{DevFeature}} Floating point variables also work.<br />
** '''random''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.<br />
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''<br />
** '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.<br />
** {{DevFeature}} '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).<br />
** {{DevFeature}} '''[join]''' joins an array of strings to create a textual list<br />
***variable: name of the array<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to connect the elements<br />
***remove_empty: whether to ignore empty elements<br />
** {{DevFeature}} '''ipart''': Assigns the integer part (the part to the left of the comma) of the referenced variable.<br />
** {{DevFeature}} '''fpart''': Assigns the decimal part (the part to the right of the comma) of the referenced variable.<br />
** {{DevFeature}} '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:<br />
***'''ceil''': Rounds upward to the nearest integer.<br />
***'''floor''': Rounds down to the nearest integer.<br />
<br />
* {{DevFeature}} '''[set_variables]''': manipulates a WML array<br />
** '''name''': the name of the container to manipulate<br />
** '''mode''': one of the following values:<br />
***replace: will clean the array '''name''' and replace it with given data<br />
***append: will append given data to the current array<br />
***merge: will merge in the given data into '''name'''<br />
***insert: will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.<br />
** '''to_variable''': data will be set to the given array<br />
** '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags, example:<br />
[set_variables]<br />
name=arr<br />
mode=replace<br />
[value]<br />
foo=bar<br />
[/value]<br />
[value]<br />
foo=more<br />
[/value]<br />
[/set_variables]<br />
{DEBUG_MSG $arr[0].foo}<br />
{DEBUG_MSG $arr[1].foo}<br />
=>bar; more<br />
** '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags<br />
**'''[split]''' splits a textual list into an array which will then be set to data<br />
***list: textual list to split<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to separate the elements<br />
***remove_empty: wether to ignore empty elements<br />
<br />
* {{DevFeature}} '''[fire_event]''': trigger a WML event<br />
** '''name''': the name of event to trigger<br />
** '''[primary_unit]''': primary unit for the event (usually the attacker) (optional)<br />
** '''[secondary_unit]''': secondary unit for the event (usually the defender) (optional)<br />
** both tags have some keys which are optional :<br />
*** '''x,y''': location of this unit<br />
*** In Wesnoth 1.5.9 and onwards, [primary_unit] and [secondary_unit] can take a [[FilterWML|Standard Unit Filter]], but it will never match on a recall list unit. If it matches multiple units, the first unit that would be obtained with [store_unit] will be used in the relevant event parameter ($unit or $secondary_unit) and event filter.<br />
** '''[primary_attack]''': information passed to the primary attack filter and $weapon variable on the new event.<br />
** '''[secondary_attack]''': information passed to the second attack filter and $second_weapon variable on the new event.<br />
<br />
* '''[store_unit]''': stores details about units into game variables.<br>Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.<br>Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]<br />
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.<br />
** '''variable''': the name of the variable into which to store the unit(s)<br />
** '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.<br />
** '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.<br />
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''<br />
:* description<br />
:* experience<br />
:* facing<br />
:* gender<br />
:* canrecruit<br />
:* overlays<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* moves<br />
:* resting<br />
:* side<br />
:* type<br />
:* unrenamable<br />
:* upkeep<br />
:* user_description<br />
:* x<br />
:* y<br />
:* [variables]<br />
:* [status]<br />
:* [modifications]<br />
Variables, status, and modifications are children of the stored unit variable. Example:<br />
[set_variable]<br />
name=unit_store.status.poisoned<br />
value=yes<br />
[/set_variable]<br />
<br />
:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.<br />
:* advances_to<br />
:* alignment<br />
:* alpha<br />
:* attacks_left<br />
:* canrecruit<br />
:* controller<br />
:* cost<br />
:* description<br />
:* experience<br />
:* facing<br />
:* flying<br />
:* fog<br />
:* gender<br />
:* get_hit_sound<br />
:* gold<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* id<br />
:* image<br />
:* image_defensive<br />
:* income<br />
:* language_name (same as the name key in the unit config)<br />
:* level<br />
:* max_attacks<br />
:* max_experience<br />
:* max_hitpoints<br />
:* max_moves<br />
:* movement<br />
:* movement_type<br />
:* moves<br />
:* race<br />
:* resting<br />
:* shroud<br />
:* side<br />
:* type<br />
:* unit_description<br />
:* unrenamable<br />
:* usage<br />
:* value<br />
:* x<br />
:* y<br />
:* zoc<br />
:* [advancement]<br />
:* [/advancement]<br />
:* [movement_costs]<br />
:* [/movement_costs]<br />
:* [defense]<br />
:* [/defense]<br />
:* [resistance]<br />
:* [/resistance]<br />
:* [variables]<br />
:* [/variables]<br />
:* [status]<br />
:* [/status]<br />
:* [attack]<br />
:* [/attack]<br />
:* [modifications_description]<br />
:* [/modifications_description]<br />
:* [modifications]<br />
:* [/modifications]<br />
<br />
* '''[store_starting_location]''': Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and {{DevFeature}} 'owner_side' (villages only)<br />
** '''side''': the side whose starting location is to be stored<br />
** '''variable''': (default='location'): the name of the variable to store the location in<br />
* '''[store_locations]''': Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and {{DevFeature}} 'owner_side' (villages only).<br />
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.<br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.<br />
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored<br />
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.<br />
* '''[store_villages]''': Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and {{DevFeature}} 'owner_side'.<br />
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages. <br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.<br />
* '''[store_gold]''': Stores a side's gold into a variable.<br />
** '''side''': (default=1) the side for which the gold should be stored<br />
** '''variable''': (default='gold') the name of the variable to store the gold in<br />
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden' {{DevFeature}}, 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)<br />
** '''side''': the side whose information should be stored<br />
** '''variable''': the name of the variable to store the information in<br />
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.<br />
** '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.<br />
* '''[role]''': tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [[ConditionalActionsWML#Condition_Tags|Condition Tags]]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.<br />
** '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.<br />
** '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.<br />
* {{DevFeature}} '''[store_map_dimensions]''': Stores the map dimensions in a variable.<br />
** '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.<br />
* {{DevFeature}} '''[insert_tag]''': inserts a variable as WML<br />
**'''name''': the ["name"] to be given to the tag<br />
**'''variable''': name of the variable to be inserted<br />
* {{DevFeature}} '''[store_time_of_day]''': stores time of day information from the current scenario into a WML variable container.<br />
** '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].<br />
** '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[ConditionalWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=ConditionalActionsWML&diff=28946ConditionalActionsWML2009-03-22T01:21:39Z<p>Voris: Updated some links, placed Conditional Actions at top.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
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 [[:Category:ActionsWML|actions]] which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.<br />
<br />
* '''[else]''': Contains [[:Category:ActionsWML|actions]] which should be executed if any condition evaluates as false ''and'' '''all''' of the '''[or]''' tags evaluate as false.<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.<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.<br />
** [[:Category:ActionsWML|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 [[:Category:ActionsWML|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 1024 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 [[:Category:ActionsWML|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 [[:Category:ActionsWML|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 />
== Condition Tags ==<br />
<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 />
; [have_unit]<br />
: A unit with greater than zero hit points matching this filter exists.<br />
:* [[StandardUnitFilter]] '''*''': Selection criteria. <br />'''* Note:''' ''Does '''not''' check for matching units in the recall list!''<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 />
<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 variable (see [[VariablesWML]]) 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 greater than this value.<br />
:** '''greater_than_equal_to''': ''$name'' is greater than or equal to this value.<br />
:** '''less_than''': ''$name'' is less than this value.<br />
:** '''less_than_equal_to''': ''$name'' is 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 />'''*''' When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.<br />These values are evaluated as ''false'': '''no''', '''false''', '''off''', '''0''', and '''0.0'''<br />These values are evaluated as ''true'': '''yes''', '''true''', '''on''', '''1''', and '''0.1''' (and any other non-zero number)<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 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 others. 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, if it evaluates to true, is all that is necessary for the conditions to be met. In other words, if all other conditions are false, but one '''[or]''' condition is true, the conditions have been met for an [[:Category:ActionsWML|action]] to take place. (See [[AdvancedConditionalWML|Example]])<br />
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true. <br />
<br />
; [not]<br />
: A condition which reverses the evaluation of the contained condition(s).<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 />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[InternalActionsWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=Category:ActionsWML&diff=28945Category:ActionsWML2009-03-22T00:44:35Z<p>Voris: Initial creation.</p>
<hr />
<div>Pages in this category all relate to the various types of actions that can be coded in WML.</div>Vorishttps://wiki.wesnoth.org/index.php?title=InterfaceActionsWML&diff=28944InterfaceActionsWML2009-03-22T00:42:49Z<p>Voris: Added page to the ActionsWML category.</p>
<hr />
<div>{{WML Tags}}<br />
== Interface actions ==<br />
<br />
Interface actions are actions that do not have an 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 />
== [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. 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 description 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''': 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 />
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.<br />
* '''image''': (default: profile image of speaker) the image to display next to the message.<br />
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed.<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]''': zero or more '''[option]''' elements may be present. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.<br />
** ''message'' (translatable) the text displayed for the option (see [[DescriptionWML]])<br />
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[InternalActionsWML]])<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.<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_chars''': 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 />
* note that '''[option]''' and '''[text_input]''' can only be used in moveto events in MP, otherwise they cause OOS<br />
<br />
Text formatting options for '''[message]'''. These can also be used in unit names (user_description), objectives, and such.<br />
* A tilde (~) as the first character causes the line to be boldfaced.<br />
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.<br />
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.<br />
* An asterisk (*) as the first character causes the line to be bigger.<br />
* A backquote (`) as the first character causes the line to be smaller.<br />
* If used, the caption key text is boldfaced.<br />
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''<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 />
This tag renders the ''objectives'' attribute of [scenario] obsolete (see ''objectives'', [[ScenarioWML]]).<br />
Instead of using ''objectives'', use '''[objectives]''' to set scenario objectives inside a prestart event.<br />
It can also be used to overwrite the starting objectives mid-scenario.<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.<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.<br />
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives.<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 />
<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 />
** '''description''': text for the specific win or loss condition.<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 />
<br />
=== Macros ===<br />
There are a few predefined macros for Objectives that you can use to shorten the code. '''{SET_OBJECTIVES}''', '''{VICTORY_CONDITION}''' and '''{DEFEAT_CONDITION}'''. There are all used together. For more information look [http://www.wesnoth.org/misc/macro-reference.xhtml here]<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.<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 false.<br />
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[InternalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.<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 />
* '''[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 />
<br />
== Other interface tags ==<br />
<br />
The following tags are also action tags:<br />
* '''[item]''': makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros))''</tt><br />
** '''x''', '''y''': the location to place the item.<br />
** '''image''': the image (in ''images/'' as .png) to place on the hex.<br />
** '''halo''': an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex.<br />
** '''team_name''' {{DevFeature}}: 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''' {{DevFeature}}: whether the item should be visible through fog or not. Default yes.<br />
* '''[removeitem]''': removes any graphical items on a given hex<br />
** '''x''', '''y''': the hex to remove items off<br />
** '''image''' {{DevFeature}} if specified, only removes the given image item<br />
* '''[print]''': 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.<br />
* '''[move_unit_fake]''': moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.<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 />
* '''[hide_unit]''': makes the given unit become invisible. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Each '''[hide_unit]''' tag only hides one unit.<br />
** '''x''', '''y''': location of the unit to be hidden. (NOT a standard unit filter! Just x and y.)<br />
* '''[unhide_unit]''': stops the currently hidden unit from being hidden.<br />
* '''[scroll]''': 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 />
* '''[scroll_to]''': Scroll to a given hex<br />
** '''x''', '''y''': the hex to scroll to<br />
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.<br />
* '''[scroll_to_unit]''' Scroll to a given unit<br />
** [[StandardUnitFilter]]<br />
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.<br />
* '''[sound]''': Plays a sound<br />
** '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)<br />
** '''repeat''': repeats the sound for a specified additional number of times (default=0)<br />
* '''[sound_source]''': Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.<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 "true" and "false" - if true the source will not play if its locations are fogged/shrouded<br />
** '''x,y''': a [[StandardLocationFilter]] for the locations associated with the sound source<br />
** {{DevFeature}}<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 />
* '''[remove_sound_source]''': Removes a previously defined sound source.<br />
** '''id''': the identification key of the sound source to remove<br />
* '''[music]''': 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 />
* '''[colour_adjust]''': tints the colour of the screen.<br />
** '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each colour<br />
* '''[delay]''': pauses the game<br />
** '''time''': the time to pause in milliseconds<br />
* '''[redraw]''': redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).<br />
** '''side''': if used, recalculates fog and shroud for that side. Useful if you for example spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).<br />
* '''[unit_overlay]''': sets an image that will be drawn over a particular unit, and follow it around<br />
** '''x''', '''y''': the location of the unit to overlay on<br />
** '''image''': the image to place on the unit<br />
* '''[remove_unit_overlay]''': removes a particular overlayed image from a unit<br />
** '''x''', '''y''': the location of the unit to remove an overlay from<br />
** '''image''': the image to remove from the unit<br />
* '''[animate_unit]''': uses the custom animation of a unit to animate it on screen (if the unit has the corresponding animation)<br />
** '''flag''': the key to find the good custom animation in the unit description see the '''[extra_anim]''' description in [[AnimationWML]] Standar anims can be triggered with the following keywors ''leading recruited standing idling levelin levelout healing healed poisoned movement defend attack death victory pre_teleport post_teleport''<br />
** '''[filter]''': a [[StandardUnitFilter]] 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<br />
** '''[secondary_attack]''': same for the second attack<br />
** '''hits''': the hit type to filter unit on<br />
** '''text''': a text to hover during the animation<br />
** '''red''': red value for the text color<br />
** '''green''': green value for the text color<br />
** '''blue''': blue value for the text color<br />
** '''with_bars''': whether to display the status bars or not.<br />
** '''[animate]''': a sub block with the same syntax as the '''[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 />
* '''[label]''' places a label on the map.<br />
** '''x''', '''y''': the location of the label<br />
** '''text''': what the label should say<br />
** '''team_name''': if specified, the label will only be visible to the given team.<br />
** '''visible_in_fog''' {{DevFeature}}: whether the label should be visible through fog or not. Default yes.<br />
* '''[deprecated_message]''' shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.<br />
** '''message''': the message to show.<br />
* '''[debug_message]''': outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. Information is actually output depending on the minimum severity (''log level'') for the '''notifs''' log domain. {{DevFeature}} This tag is deprecated since 1.5.8, and the '''notifs''' log domain has been removed.<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 />
* '''[wml_message]''' {{DevFeature}}: in 1.5.7+svn/1.5.8 and later, this replaces [debug_message] and works identically, except that 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 />
* '''[open_help]''' {{DevFeature}} opens the in-game help. This tag was added in 1.5.9+svn/1.5.10.<br />
** '''topic''': the id of the topic to open<br />
* '''[show_objectives]''' {{DevFeature}} shows the objectives screen. Has the same effect as if [objectives] were used to replace them with an exact duplicate.<br />
** '''side''': the side to show the objectives. If not set, all sides are used.<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 />
* '''{FLOATING_TEXT}''' Float some text over a unit similar to the damage numbers.<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 />
* '''{TREMOR}''' Creates a tremor like screenshake<br />
** {{DevFeature}} This macro has been deprecated in favor of '''{QUAKE <soundfile>}'''. Thus, it is equivalent to '''{QUAKE (rumble.ogg)}''', although '''cave-in.ogg''' has been added as a much better alternative for most situations.<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>Vorishttps://wiki.wesnoth.org/index.php?title=DirectActionsWML&diff=28943DirectActionsWML2009-03-22T00:42:28Z<p>Voris: Added page to the ActionsWML category.</p>
<hr />
<div>{{WML Tags}}<br />
== Direct actions ==<br />
<br />
Direct actions are actions that have a direct effect on gameplay.<br />
<br />
The following tags are actions:<br />
* '''[endlevel]''': ends the scenario.<br />
** '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless ''result=defeat'', the following keys can also be used:<br />
** '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.<br />
** '''carryover_report''' {{DevFeature}}: whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.<br />
** '''save''' {{DevFeature}}: whether a start-of-scenario save should be created for the next scenario, the default is save=yes.<br />
** '''linger_mode''' {{DevFeature}}: whether the game should switch to linger_mode before advancing to the next scenario, the default is linger_mode=yes.<br />
** '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.<br />
** When the result is "victory" the following keys can be used:<br />
*** '''carryover_percentage''' {{DevFeature}}: by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.<br />
*** '''carryover_add''' {{DevFeature}}: if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.<br />
** '''music''' {{DevFeature}}: (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.<br />
** '''end_text''' {{DevFeature}}: Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].<br />
** '''end_text_duration''' {{DevFeature}}: Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].<br />
* '''[unit]''': places a unit on the map. For syntax see [[SingleUnitWML]].<br />
** {{Short Note:Predefined Macro|GENERIC_UNIT}}<br />
** {{DevFeature}} '''to_variable''': spawn directly into a variable instead of on the map.<br />
* '''[recall]''': recalls a unit. The unit is recalled free of charge, and is placed near the leader.<br />
** [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored.<br />
** '''x,y''': the unit is placed here instead of next to the leader.<br />
** '''show''': if not "no", display the unit being recalled.<br />
* '''[teleport]''': teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}<br />
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be teleported.<br />
** '''x,y''': the position to teleport to.<br />
** '''clear_shroud''': should shroud be cleared on arrival<br />
** '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)<br />
* '''[terrain_mask]''': changes the terrain on the map. See [[TerrainMaskWML]].<br />
* '''[terrain]''': changes the terrain on the map.<br />
** '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.<br />
** '''x,y''': the position (or range of positions) to change.<br />
** {{DevFeature}} '''layer''': (overlay|base|both, default=both) only change the specified layer.<br />
** {{DevFeature}} '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.<br />
* '''[gold]''': give one side gold.<br />
** '''amount''': the amount of gold to give.<br />
** '''side''': (default=1) the number of the side to give the gold to.<br />
* '''[unstore_unit]''': creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also '''[store_unit]''', '''[while]''' and [clear_variable] in [[InternalActionsWML]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.<br />
** '''variable''': the name of the variable.<br />
** '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.<br />
** '''text''': (translatable) floating text to display above the unit, such as a damage amount<br />
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)<br />
** '''advance''': if the XP has been modified then there will be tried to advance the unit, default true. <br />
** {{DevFeature}} '''x''' ,'''y''': override unit location<br />
* '''[allow_recruit]''': allows a side to recruit units it couldn't previously recruit.<br />
** '''type''': the types of units that the side can now recruit.<br />
** '''side''': (default=1) the number of the side that is being allowed to recruit the units.<br />
* '''[disallow_recruit]''': prevents a side from recruiting units it could previously recruit.<br />
** '''type''': the types of units that the side can no longer recruit.<br />
** '''side''': (default=1) the number of the side that may no longer recruit the units.<br />
* '''[set_recruit]''': sets the units a side can recruit.<br />
** '''recruit''': the types of units that the side can now recruit.<br />
** '''side''': (default=1) the number of the side that is having its recruitment set.<br />
* '''[modify_side]''': modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'<br />
** '''side''': (default=1) the number of the side that is to be changed.<br />
** '''income''': the income given at the begining of each turn.<br />
** '''team_name''': the team in which the side plays the scenario.<br />
** '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.<br />
** '''gold''': the amount of gold the side owns.<br />
** '''village_gold''': the income setting per village for the side.<br />
** '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.<br />
** '''fog''': a boolean string (yes/no) describing the status of Fog for the side.<br />
** '''shroud''': a boolean string describing the status of Shroud for the side.<br />
** {{DevFeature}} '''hidden''': a boolean string specifying whether side is shown in status table.<br />
** {{DevFeature}} '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].<br />
* '''[modify_turns]''': modifies the turn limit in the middle of a scenario.<br />
** '''value''': the new turn limit.<br />
** '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).<br />
** {{DevFeature}} '''current''': changes the current turn number after applying turn limit modifications, if any. It is possible to change the current turn number to a greater one than the current only; also, it is not possible to change the turn number to exceed the turn limit.<br />
* '''[capture_village]''': changes the ownership of a village.<br />
** '''side''': the side that takes control of the village. If not given, the village will become neutral.<br />
** '''x, y''': the location of the village.<br />
* '''[kill]''': Removes all units (including units in a recall list) that match the filter from the game.<br />
** [[StandardUnitFilter]]: selection criterion<br />
** '''animate''': if 'yes', displays the unit dying (fading away).<br />
** '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event. {{DevFeature}} 'last breath' events are also fired.<br />
* '''[unstone]''': Unstones all units that match the filter.<br />
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be unstoned. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unstoned.<br />
* '''[object]''': gives some unit an object and removes all items on the tile the unit is on.<br />
** '''id''': when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.<br />
** '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].<br />
** '''duration''': if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).<br />
** '''[filter]''': [[StandardUnitFilter]] the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.<br />
** '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.<br />
** '''silent''': whether or not messages should be suppressed. Default is "no".<br />
** '''image''': the displayed image of the object.<br />
** '''name''': (translatable) displayed as a caption of the image.<br />
<br />
** '''user_description''': {{DevFeature}} (translatable) displayed as a message of the image. In 1.4 and older versions this is just '''description'''; that will still be expected for compatibility.<br />
** '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.<br />
** If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.<br />
** The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.<br />
* '''[remove_shroud]''': removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).<br />
** '''side''': (default=1) the side for which to remove shroud.<br />
** [[StandardLocationFilter]]: the range of tiles for which shroud should be removed.<br />
** Note: '''[remove_shroud]''' doesnt't accept all of the standard location filters. In particular '''[filter]''' to remove shroud around units doesn't work, and radius may not either. To remove shroud around a group of units, you can temporarily switch the sides of the units using '''[store_unit]''', '''[set_variable]''', and then '''[unstore_unit]''' (do the '''[set_variable]''' and '''[unstore_unit]''' twice each, once to switch sides, and once to switch back). Just make sure you call '''[redraw]''' while the unit's side is switched to update shroud. Also make sure to use ''kill=no'' for the store and then ''find_vacant=no'' for the unstores.<br />
** {{DevFeature}}: '''[remove_shroud]''' accepts a full standard location filter.<br />
* '''[place_shroud]''': places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).<br />
** '''side''': (default=1) the side for which to place shroud.<br />
** [[StandardLocationFilter]]: the range of tiles on which shroud should be placed.<br />
* '''[allow_undo]''': allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.<br />
** Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.<br />
* '''[heal_unit]''' {{DevFeature}}: heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed).<br />
** '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed. <br />
** '''[secondary_unit_filter]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true).<br />
** '''amount''': the maximum points the unit will be healed.<br />
** '''animate''': a boolean which indicate if the healing animations must be played.<br />
* '''[time_area]''' {{DevFeature}}: how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] and [illuminated_time] tags in the [scenario] tag<br />
** [[StandardLocationFilter]]: the locations to affect.<br />
** [[TimeWML]]: the new schedule.<br />
** '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. See below.<br />
** '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.<br />
** {{DevFeature}}: in Wesnoth 1.5.9 and later, '''id''' may be a comma-separated list for removing time areas. It is not allowed, however, for inserting time areas; only the first id is taken into account in that case.<br />
<br />
* '''[end_turn]''' {{DevFeature}}: end the current side's turn.<br />
<br />
== Useful Macros ==<br />
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].<br />
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])<br />
* '''{FULL_HEAL}''': Brings a unit to full HP<br />
* '''{LOYAL_UNIT}''': Create a loyal unit<br />
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain<br />
<br />
== See Also ==<br />
<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWML&diff=28942InternalActionsWML2009-03-22T00:42:05Z<p>Voris: Added page to the ActionsWML category.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Internal actions are actions that WML uses internally that do not directly affect game play. For example, storing a variable is an internal action.<br />
<br />
== [event] ==<br />
<br />
This adds a new event to the scenario.<br />
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).<br />
This is useful if you want an event that can only be triggered when a prior event is fulfilled<br />
<br />
== Variable Actions ==<br />
<br />
These tags describe actions that affect the values of WML variables<br />
(see [[VariablesWML]] for information on WML variables,<br />
and [[UtilWML]] for convenient macro shortcuts for some of these):<br />
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}} {{DevFeature}} Floating-point arithmetic is now fully supported.<br />
** '''name''': the name of the variable to manipulate<br />
** '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])<br />
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.<br />
** '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.<br />
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.<br />
** '''add''': add the given amount to the variable. To subtract, add a negative number.<br />
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. {{DevFeature}} Floating point values are no longer rounded.<br />
** '''divide''': divide the variable by the given number. The result is an integer. {{DevFeature}} Floating point results are no longer rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.<br />
** '''modulo''': returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1. {{DevFeature}} Floating point variables also work.<br />
** '''random''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.<br />
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''<br />
** '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.<br />
** {{DevFeature}} '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).<br />
** {{DevFeature}} '''[join]''' joins an array of strings to create a textual list<br />
***variable: name of the array<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to connect the elements<br />
***remove_empty: whether to ignore empty elements<br />
** {{DevFeature}} '''ipart''': Assigns the integer part (the part to the left of the comma) of the referenced variable.<br />
** {{DevFeature}} '''fpart''': Assigns the decimal part (the part to the right of the comma) of the referenced variable.<br />
** {{DevFeature}} '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:<br />
***'''ceil''': Rounds upward to the nearest integer.<br />
***'''floor''': Rounds down to the nearest integer.<br />
<br />
* {{DevFeature}} '''[set_variables]''': manipulates a WML array<br />
** '''name''': the name of the container to manipulate<br />
** '''mode''': one of the following values:<br />
***replace: will clean the array '''name''' and replace it with given data<br />
***append: will append given data to the current array<br />
***merge: will merge in the given data into '''name'''<br />
***insert: will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.<br />
** '''to_variable''': data will be set to the given array<br />
** '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags, example:<br />
[set_variables]<br />
name=arr<br />
mode=replace<br />
[value]<br />
foo=bar<br />
[/value]<br />
[value]<br />
foo=more<br />
[/value]<br />
[/set_variables]<br />
{DEBUG_MSG $arr[0].foo}<br />
{DEBUG_MSG $arr[1].foo}<br />
=>bar; more<br />
** '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags<br />
**'''[split]''' splits a textual list into an array which will then be set to data<br />
***list: textual list to split<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to separate the elements<br />
***remove_empty: wether to ignore empty elements<br />
<br />
* {{DevFeature}} '''[fire_event]''': trigger a WML event<br />
** '''name''': the name of event to trigger<br />
** '''[primary_unit]''': primary unit for the event (usually the attacker) (optional)<br />
** '''[secondary_unit]''': secondary unit for the event (usually the defender) (optional)<br />
** both tags have some keys which are optional :<br />
*** '''x,y''': location of this unit<br />
*** In Wesnoth 1.5.9 and onwards, [primary_unit] and [secondary_unit] can take a [[FilterWML|Standard Unit Filter]], but it will never match on a recall list unit. If it matches multiple units, the first unit that would be obtained with [store_unit] will be used in the relevant event parameter ($unit or $secondary_unit) and event filter.<br />
** '''[primary_attack]''': information passed to the primary attack filter and $weapon variable on the new event.<br />
** '''[secondary_attack]''': information passed to the second attack filter and $second_weapon variable on the new event.<br />
<br />
* '''[store_unit]''': stores details about units into game variables.<br>Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.<br>Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]<br />
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.<br />
** '''variable''': the name of the variable into which to store the unit(s)<br />
** '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.<br />
** '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.<br />
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''<br />
:* description<br />
:* experience<br />
:* facing<br />
:* gender<br />
:* canrecruit<br />
:* overlays<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* moves<br />
:* resting<br />
:* side<br />
:* type<br />
:* unrenamable<br />
:* upkeep<br />
:* user_description<br />
:* x<br />
:* y<br />
:* [variables]<br />
:* [status]<br />
:* [modifications]<br />
Variables, status, and modifications are children of the stored unit variable. Example:<br />
[set_variable]<br />
name=unit_store.status.poisoned<br />
value=yes<br />
[/set_variable]<br />
<br />
:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.<br />
:* advances_to<br />
:* alignment<br />
:* alpha<br />
:* attacks_left<br />
:* canrecruit<br />
:* controller<br />
:* cost<br />
:* description<br />
:* experience<br />
:* facing<br />
:* flying<br />
:* fog<br />
:* gender<br />
:* get_hit_sound<br />
:* gold<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* id<br />
:* image<br />
:* image_defensive<br />
:* income<br />
:* language_name (same as the name key in the unit config)<br />
:* level<br />
:* max_attacks<br />
:* max_experience<br />
:* max_hitpoints<br />
:* max_moves<br />
:* movement<br />
:* movement_type<br />
:* moves<br />
:* race<br />
:* resting<br />
:* shroud<br />
:* side<br />
:* type<br />
:* unit_description<br />
:* unrenamable<br />
:* usage<br />
:* value<br />
:* x<br />
:* y<br />
:* zoc<br />
:* [advancement]<br />
:* [/advancement]<br />
:* [movement_costs]<br />
:* [/movement_costs]<br />
:* [defense]<br />
:* [/defense]<br />
:* [resistance]<br />
:* [/resistance]<br />
:* [variables]<br />
:* [/variables]<br />
:* [status]<br />
:* [/status]<br />
:* [attack]<br />
:* [/attack]<br />
:* [modifications_description]<br />
:* [/modifications_description]<br />
:* [modifications]<br />
:* [/modifications]<br />
<br />
* '''[store_starting_location]''': Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and {{DevFeature}} 'owner_side' (villages only)<br />
** '''side''': the side whose starting location is to be stored<br />
** '''variable''': (default='location'): the name of the variable to store the location in<br />
* '''[store_locations]''': Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and {{DevFeature}} 'owner_side' (villages only).<br />
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.<br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.<br />
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored<br />
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.<br />
* '''[store_villages]''': Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and {{DevFeature}} 'owner_side'.<br />
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages. <br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.<br />
* '''[store_gold]''': Stores a side's gold into a variable.<br />
** '''side''': (default=1) the side for which the gold should be stored<br />
** '''variable''': (default='gold') the name of the variable to store the gold in<br />
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden' {{DevFeature}}, 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)<br />
** '''side''': the side whose information should be stored<br />
** '''variable''': the name of the variable to store the information in<br />
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.<br />
** '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.<br />
* '''[role]''': tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.<br />
** '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.<br />
** '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.<br />
* {{DevFeature}} '''[store_map_dimensions]''': Stores the map dimensions in a variable.<br />
** '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.<br />
* {{DevFeature}} '''[insert_tag]''': inserts a variable as WML<br />
**'''name''': the ["name"] to be given to the tag<br />
**'''variable''': name of the variable to be inserted<br />
* {{DevFeature}} '''[store_time_of_day]''': stores time of day information from the current scenario into a WML variable container.<br />
** '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].<br />
** '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[ConditionalWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=ConditionalActionsWML&diff=28941ConditionalActionsWML2009-03-22T00:39:45Z<p>Voris: Initial creation. Split off from InternalActionsWML since it seemed to deserve standalone documentation.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
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 />
== Condition Tags ==<br />
<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 />
; [have_unit]<br />
: A unit with greater than zero hit points matching this filter exists.<br />
:* [[StandardUnitFilter]] '''*''': Selection criteria. <br />'''* Note:''' ''Does '''not''' check for matching units in the recall list!''<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 />
<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 variable (see [[VariablesWML]]) 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 greater than this value.<br />
:** '''greater_than_equal_to''': ''$name'' is greater than or equal to this value.<br />
:** '''less_than''': ''$name'' is less than this value.<br />
:** '''less_than_equal_to''': ''$name'' is 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 />'''*''' When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.<br />These values are evaluated as ''false'': '''no''', '''false''', '''off''', '''0''', and '''0.0'''<br />These values are evaluated as ''true'': '''yes''', '''true''', '''on''', '''1''', and '''0.1''' (and any other non-zero number)<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 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 others. 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, if it evaluates to true, is all that is necessary for the conditions to be met. In other words, if all other conditions are false, but one '''[or]''' condition is true, the conditions have been met for an action to take place. (See [[AdvancedConditionalWML|Example]])<br />
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true. <br />
<br />
; [not]<br />
: A condition which reverses the evaluation of the contained condition(s).<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 />
== Conditional Actions ==<br />
<br />
These internal actions describe actions that should be executed only if certain conditions (in almost all cases described using [[#Condition Tags|Condition Tags]]) are met.<br />
<br />
=== [if] ===<br />
<br />
Executes actions only if conditions described in 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 a set of action tags which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.<br />
<br />
* '''[else]''': Contains a set of action tags which should be executed if any condition evaluates as false ''and'' '''all''' of the '''[or]''' tags evaluate as false.<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.<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.<br />
** <Action WML>: Action WML ([[InternalActionsWML]], [[DirectActionsWML]], [[InterfaceActionsWML]], etc.) 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 action WML ([[InternalActionsWML]], [[DirectActionsWML]], [[InterfaceActionsWML]], etc.) 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 1024 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 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 '''FOREACH''' and '''NEXT''' macros documented [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg here].<br />
<br />
==== 'REPEAT' Macro ====<br />
This macro simplifies the use of a '''[while]''' tag to execute the same action(s) repeatedly for a specified number of times. To use it, use the '''REPEAT''' macro documented [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg here].<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[InternalActionsWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=ReferenceWML&diff=28939ReferenceWML2009-03-22T00:26:07Z<p>Voris: /* Other WML tags */ renamed ConditionalWML link to ConditionalActionsWML and cleaned up description a bit</p>
<hr />
<div>{{WML Tags}}<br />
== The Wesnoth Markup Language ==<br />
<br />
The Wesnoth Markup Language (WML) is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout.<br />
<br />
This page is a collection of pointers to different common WML structures. See [[AlphabeticalWML]] for a quick listing of all WML tags. The more comprehensive [[BuildingScenariosIndex]] lists tags and keys.<br />
<br />
See [[BuildingScenarios]], [[BuildingCampaigns]] and [[BuildingUnits]]<br />
for a tutorial style overview.<br />
<br />
<br />
<br />
''Note: this reference may contain slight inaccuracies, might not list all existing keys and tags or might contain some deprecated syntax. If you find that this reference doesn't give you the answer to how to implement some feature in WML, the most reliable way is to look at the WML code of existing units and campaigns that have done so.''<br />
<br />
== How WML works ==<br />
<br />
* [[PreprocessorRef]] the WML preprocessor syntax<br />
** [[UtilWML]] utility macros defined in utils.cfg<br />
* [[SyntaxWML]] the language syntax.<br />
** [[VariablesWML]] how to use WML variables<br />
<br />
== WML toplevel tags ==<br />
<br />
* [[GameConfigWML]] the top level '''[game_config]''' tag<br />
* [[UnitsWML]] the top level '''[units]''' tag<br />
** [[UnitWML]] how to describe a unit type<br />
** [[AnimationWML]] how to animate units<br />
* [[CampaignWML]] the top level '''[campaign]''' tag<br />
* [[ScenarioWML]] the top level tags '''[scenario]''', '''[multiplayer]''', '''[test]''', and '''[tutorial]'''<br />
** [[EventWML]] how to describe an event<br />
** [[SideWML]] how to describe a side<br />
** [[MapGeneratorWML]] the random map generator<br />
** [[TimeWML]] how to describe a day<br />
** [[IntroWML]] how to describe the intro screen<br />
* [[SavefileWML]] a description of the format of savegames<br />
** [[ReplayWML]] a description of the format of player actions such as moving a unit<br />
** [[StatisticalScenarioWML]] used to generate statistics of a savegame<br />
* [[PblWML]] a description of the format of server-uploadable campaigns<br />
* [[EraWML]] the top level '''[era]''' tag<br />
* [[TerrainWML]] the top level '''[terrain]''' tag<br />
* [[TerrainGraphicsWML]], the top level '''[terrain_graphics]''' tag<br />
* [[ThemeWML]] the top level '''[theme]''' tag<br />
* [[LanguageWML]] the top level '''[language]''' tag<br />
* [[HelpWML]] the top level '''[help]''' tag<br />
* [[BinaryPathWML]] the top level '''[binary_path]''' tag<br />
* [[FontsWML]] the top level '''[fonts]''' tag<br />
<br />
== Other WML tags ==<br />
<br />
* [[EventWML]] how to describe an event<br />
** [[FilterWML]] the construct to filter on units, locations, and weapons<br />
** [[ConditionalActionsWML]] actions that encapsulate conditional filters and the actions to execute if the conditions are met<br />
** [[DirectActionsWML]] actions that directly affect gameplay: for example creating a unit<br />
** [[InternalActionsWML]] actions that WML uses internally: for example storing a variable<br />
** [[InterfaceActionsWML]] actions that do not affect gameplay: for example displaying a message<br />
* [[SingleUnitWML]] how to describe a unit<br />
* [[AiWML]] how to describe parameters for AI<br />
* [[EffectWML]] the construct to modify a unit<br />
* [[AbilitiesWML]] a list of the different abilities a unit or weapon can have<br />
* [[DescriptionWML]] the structure of WML coded menus like the difficulty chooser of campaigns<br />
* [[EditorWML]] tags controllin the post-1.4 editor's behavior<br />
<br />
== Predefined macros == <br />
<br />
Wesnoth ships with a library of predefined macros you should find useful in writing your own WML. You can find a description of all such macros [http://www.wesnoth.org/macro-reference.xhtml here].<br />
<br />
== Other ==<br />
<br />
* [[ReferenceWMLSyntax]] how this wiki and the pages it links to should be formatted<br />
* [[ConventionsWML]] how to make your WML more readable<br />
* [[UsefulWMLFragments]] Various pieces of WML for various purposes. If you have some WML you're proud of that you think others can use, add it here.<br />
* [[CommandMode]] commands are not strictly speaking part of WML, these could be a little hard to find so there's a link here.<br />
* [[MultiplayerServerWML]] is used when communicating with the multiplayer server.<br />
* [[CampaignServerWML]] is used when managing contributed campaigns on the campaign server.<br />
* [[ImagePathFunctionWML]] is used when applying the team-color function to images.<br />
* [[BinaryWML]] how WML is sent over the network<br />
<br />
== See Also ==<br />
<br />
* [[BuildingMaps]] the text-based format for Wesnoth maps<br />
* [[TerrainCodesWML]] a list of all terrains<br />
* [[MultiHexTutorial]] a description of the multi-hex tiling system<br />
* [[IGNFileFormat]] a description of the ignore file format<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=ConditionalWML&diff=28938ConditionalWML2009-03-22T00:19:38Z<p>Voris: Redirecting to renamed ConditionalActionsWML page.</p>
<hr />
<div>#REDIRECT [[ConditionalActionsWML]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWML&diff=28936InternalActionsWML2009-03-21T23:38:17Z<p>Voris: Removed conditional stuff and moved to its own ConditionalWML page.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Internal actions are actions that WML uses internally that do not directly affect game play. For example, storing a variable is an internal action.<br />
<br />
== [event] ==<br />
<br />
This adds a new event to the scenario.<br />
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).<br />
This is useful if you want an event that can only be triggered when a prior event is fulfilled<br />
<br />
== Variable Actions ==<br />
<br />
These tags describe actions that affect the values of WML variables<br />
(see [[VariablesWML]] for information on WML variables,<br />
and [[UtilWML]] for convenient macro shortcuts for some of these):<br />
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}} {{DevFeature}} Floating-point arithmetic is now fully supported.<br />
** '''name''': the name of the variable to manipulate<br />
** '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])<br />
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.<br />
** '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.<br />
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.<br />
** '''add''': add the given amount to the variable. To subtract, add a negative number.<br />
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. {{DevFeature}} Floating point values are no longer rounded.<br />
** '''divide''': divide the variable by the given number. The result is an integer. {{DevFeature}} Floating point results are no longer rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.<br />
** '''modulo''': returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1. {{DevFeature}} Floating point variables also work.<br />
** '''random''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.<br />
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''<br />
** '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.<br />
** {{DevFeature}} '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).<br />
** {{DevFeature}} '''[join]''' joins an array of strings to create a textual list<br />
***variable: name of the array<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to connect the elements<br />
***remove_empty: whether to ignore empty elements<br />
** {{DevFeature}} '''ipart''': Assigns the integer part (the part to the left of the comma) of the referenced variable.<br />
** {{DevFeature}} '''fpart''': Assigns the decimal part (the part to the right of the comma) of the referenced variable.<br />
** {{DevFeature}} '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:<br />
***'''ceil''': Rounds upward to the nearest integer.<br />
***'''floor''': Rounds down to the nearest integer.<br />
<br />
* {{DevFeature}} '''[set_variables]''': manipulates a WML array<br />
** '''name''': the name of the container to manipulate<br />
** '''mode''': one of the following values:<br />
***replace: will clean the array '''name''' and replace it with given data<br />
***append: will append given data to the current array<br />
***merge: will merge in the given data into '''name'''<br />
***insert: will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.<br />
** '''to_variable''': data will be set to the given array<br />
** '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags, example:<br />
[set_variables]<br />
name=arr<br />
mode=replace<br />
[value]<br />
foo=bar<br />
[/value]<br />
[value]<br />
foo=more<br />
[/value]<br />
[/set_variables]<br />
{DEBUG_MSG $arr[0].foo}<br />
{DEBUG_MSG $arr[1].foo}<br />
=>bar; more<br />
** '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags<br />
**'''[split]''' splits a textual list into an array which will then be set to data<br />
***list: textual list to split<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to separate the elements<br />
***remove_empty: wether to ignore empty elements<br />
<br />
* {{DevFeature}} '''[fire_event]''': trigger a WML event<br />
** '''name''': the name of event to trigger<br />
** '''[primary_unit]''': primary unit for the event (usually the attacker) (optional)<br />
** '''[secondary_unit]''': secondary unit for the event (usually the defender) (optional)<br />
** both tags have some keys which are optional :<br />
*** '''x,y''': location of this unit<br />
*** In Wesnoth 1.5.9 and onwards, [primary_unit] and [secondary_unit] can take a [[FilterWML|Standard Unit Filter]], but it will never match on a recall list unit. If it matches multiple units, the first unit that would be obtained with [store_unit] will be used in the relevant event parameter ($unit or $secondary_unit) and event filter.<br />
** '''[primary_attack]''': information passed to the primary attack filter and $weapon variable on the new event.<br />
** '''[secondary_attack]''': information passed to the second attack filter and $second_weapon variable on the new event.<br />
<br />
* '''[store_unit]''': stores details about units into game variables.<br>Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.<br>Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]<br />
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.<br />
** '''variable''': the name of the variable into which to store the unit(s)<br />
** '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.<br />
** '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.<br />
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''<br />
:* description<br />
:* experience<br />
:* facing<br />
:* gender<br />
:* canrecruit<br />
:* overlays<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* moves<br />
:* resting<br />
:* side<br />
:* type<br />
:* unrenamable<br />
:* upkeep<br />
:* user_description<br />
:* x<br />
:* y<br />
:* [variables]<br />
:* [status]<br />
:* [modifications]<br />
Variables, status, and modifications are children of the stored unit variable. Example:<br />
[set_variable]<br />
name=unit_store.status.poisoned<br />
value=yes<br />
[/set_variable]<br />
<br />
:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.<br />
:* advances_to<br />
:* alignment<br />
:* alpha<br />
:* attacks_left<br />
:* canrecruit<br />
:* controller<br />
:* cost<br />
:* description<br />
:* experience<br />
:* facing<br />
:* flying<br />
:* fog<br />
:* gender<br />
:* get_hit_sound<br />
:* gold<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* id<br />
:* image<br />
:* image_defensive<br />
:* income<br />
:* language_name (same as the name key in the unit config)<br />
:* level<br />
:* max_attacks<br />
:* max_experience<br />
:* max_hitpoints<br />
:* max_moves<br />
:* movement<br />
:* movement_type<br />
:* moves<br />
:* race<br />
:* resting<br />
:* shroud<br />
:* side<br />
:* type<br />
:* unit_description<br />
:* unrenamable<br />
:* usage<br />
:* value<br />
:* x<br />
:* y<br />
:* zoc<br />
:* [advancement]<br />
:* [/advancement]<br />
:* [movement_costs]<br />
:* [/movement_costs]<br />
:* [defense]<br />
:* [/defense]<br />
:* [resistance]<br />
:* [/resistance]<br />
:* [variables]<br />
:* [/variables]<br />
:* [status]<br />
:* [/status]<br />
:* [attack]<br />
:* [/attack]<br />
:* [modifications_description]<br />
:* [/modifications_description]<br />
:* [modifications]<br />
:* [/modifications]<br />
<br />
* '''[store_starting_location]''': Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and {{DevFeature}} 'owner_side' (villages only)<br />
** '''side''': the side whose starting location is to be stored<br />
** '''variable''': (default='location'): the name of the variable to store the location in<br />
* '''[store_locations]''': Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and {{DevFeature}} 'owner_side' (villages only).<br />
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.<br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.<br />
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored<br />
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.<br />
* '''[store_villages]''': Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and {{DevFeature}} 'owner_side'.<br />
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages. <br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.<br />
* '''[store_gold]''': Stores a side's gold into a variable.<br />
** '''side''': (default=1) the side for which the gold should be stored<br />
** '''variable''': (default='gold') the name of the variable to store the gold in<br />
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden' {{DevFeature}}, 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)<br />
** '''side''': the side whose information should be stored<br />
** '''variable''': the name of the variable to store the information in<br />
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.<br />
** '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.<br />
* '''[role]''': tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.<br />
** '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.<br />
** '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.<br />
* {{DevFeature}} '''[store_map_dimensions]''': Stores the map dimensions in a variable.<br />
** '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.<br />
* {{DevFeature}} '''[insert_tag]''': inserts a variable as WML<br />
**'''name''': the ["name"] to be given to the tag<br />
**'''variable''': name of the variable to be inserted<br />
* {{DevFeature}} '''[store_time_of_day]''': stores time of day information from the current scenario into a WML variable container.<br />
** '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].<br />
** '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[ConditionalWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=ConditionalWML&diff=28935ConditionalWML2009-03-21T23:32:22Z<p>Voris: Initial creation. Split off from InternalActionsWML since it seemed to deserve standalone documentation.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Conditional WML is used to describe conditions must be met before an action can take place and to encapsulate the actions which will take place if the conditions are met and, in some cases, what actions will take place if they are not met.<br />
<br />
== Condition Tags ==<br />
<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 />
; [have_unit]<br />
: A unit with greater than zero hit points matching this filter exists.<br />
:* [[StandardUnitFilter]] '''*''': Selection criteria. <br />'''* Note:''' ''Does '''not''' check for matching units in the recall list!''<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 />
<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 variable (see [[VariablesWML]]) 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 greater than this value.<br />
:** '''greater_than_equal_to''': ''$name'' is greater than or equal to this value.<br />
:** '''less_than''': ''$name'' is less than this value.<br />
:** '''less_than_equal_to''': ''$name'' is 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 />'''*''' When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.<br />These values are evaluated as ''false'': '''no''', '''false''', '''off''', '''0''', and '''0.0'''<br />These values are evaluated as ''true'': '''yes''', '''true''', '''on''', '''1''', and '''0.1''' (and any other non-zero number)<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 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 others. 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, if it evaluates to true, is all that is necessary for the conditions to be met. In other words, if all other conditions are false, but one '''[or]''' condition is true, the conditions have been met for an action to take place. (See [[AdvancedConditionalWML|Example]])<br />
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true. <br />
<br />
; [not]<br />
: A condition which reverses the evaluation of the contained condition(s).<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 />
== Conditional Actions ==<br />
<br />
These internal actions describe actions that should be executed only if certain conditions (in almost all cases described using [[#Condition Tags|Condition Tags]]) are met.<br />
<br />
=== [if] ===<br />
<br />
Executes actions only if conditions described in 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 a set of action tags which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.<br />
<br />
* '''[else]''': Contains a set of action tags which should be executed if any condition evaluates as false ''and'' '''all''' of the '''[or]''' tags evaluate as false.<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.<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.<br />
** <Action WML>: Action WML ([[InternalActionsWML]], [[DirectActionsWML]], [[InterfaceActionsWML]], etc.) 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 action WML ([[InternalActionsWML]], [[DirectActionsWML]], [[InterfaceActionsWML]], etc.) 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 1024 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 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 '''FOREACH''' and '''NEXT''' macros documented [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg here].<br />
<br />
==== 'REPEAT' Macro ====<br />
This macro simplifies the use of a '''[while]''' tag to execute the same action(s) repeatedly for a specified number of times. To use it, use the '''REPEAT''' macro documented [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg here].<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[InternalActionsWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=ReferenceWML&diff=28933ReferenceWML2009-03-21T23:19:20Z<p>Voris: Added ConditionalWML link</p>
<hr />
<div>{{WML Tags}}<br />
== The Wesnoth Markup Language ==<br />
<br />
The Wesnoth Markup Language (WML) is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout.<br />
<br />
This page is a collection of pointers to different common WML structures. See [[AlphabeticalWML]] for a quick listing of all WML tags. The more comprehensive [[BuildingScenariosIndex]] lists tags and keys.<br />
<br />
See [[BuildingScenarios]], [[BuildingCampaigns]] and [[BuildingUnits]]<br />
for a tutorial style overview.<br />
<br />
<br />
<br />
''Note: this reference may contain slight inaccuracies, might not list all existing keys and tags or might contain some deprecated syntax. If you find that this reference doesn't give you the answer to how to implement some feature in WML, the most reliable way is to look at the WML code of existing units and campaigns that have done so.''<br />
<br />
== How WML works ==<br />
<br />
* [[PreprocessorRef]] the WML preprocessor syntax<br />
** [[UtilWML]] utility macros defined in utils.cfg<br />
* [[SyntaxWML]] the language syntax.<br />
** [[VariablesWML]] how to use WML variables<br />
<br />
== WML toplevel tags ==<br />
<br />
* [[GameConfigWML]] the top level '''[game_config]''' tag<br />
* [[UnitsWML]] the top level '''[units]''' tag<br />
** [[UnitWML]] how to describe a unit type<br />
** [[AnimationWML]] how to animate units<br />
* [[CampaignWML]] the top level '''[campaign]''' tag<br />
* [[ScenarioWML]] the top level tags '''[scenario]''', '''[multiplayer]''', '''[test]''', and '''[tutorial]'''<br />
** [[EventWML]] how to describe an event<br />
** [[SideWML]] how to describe a side<br />
** [[MapGeneratorWML]] the random map generator<br />
** [[TimeWML]] how to describe a day<br />
** [[IntroWML]] how to describe the intro screen<br />
* [[SavefileWML]] a description of the format of savegames<br />
** [[ReplayWML]] a description of the format of player actions such as moving a unit<br />
** [[StatisticalScenarioWML]] used to generate statistics of a savegame<br />
* [[PblWML]] a description of the format of server-uploadable campaigns<br />
* [[EraWML]] the top level '''[era]''' tag<br />
* [[TerrainWML]] the top level '''[terrain]''' tag<br />
* [[TerrainGraphicsWML]], the top level '''[terrain_graphics]''' tag<br />
* [[ThemeWML]] the top level '''[theme]''' tag<br />
* [[LanguageWML]] the top level '''[language]''' tag<br />
* [[HelpWML]] the top level '''[help]''' tag<br />
* [[BinaryPathWML]] the top level '''[binary_path]''' tag<br />
* [[FontsWML]] the top level '''[fonts]''' tag<br />
<br />
== Other WML tags ==<br />
<br />
* [[EventWML]] how to describe an event<br />
** [[FilterWML]] the construct to filter on units, locations, and weapons<br />
** [[ConditionalWML]] the construct to describe conditions which must be met before an action can take place<br />
** [[DirectActionsWML]] actions that directly affect gameplay: for example creating a unit<br />
** [[InternalActionsWML]] actions that WML uses internally: for example storing a variable<br />
** [[InterfaceActionsWML]] actions that do not affect gameplay: for example displaying a message<br />
* [[SingleUnitWML]] how to describe a unit<br />
* [[AiWML]] how to describe parameters for AI<br />
* [[EffectWML]] the construct to modify a unit<br />
* [[AbilitiesWML]] a list of the different abilities a unit or weapon can have<br />
* [[DescriptionWML]] the structure of WML coded menus like the difficulty chooser of campaigns<br />
* [[EditorWML]] tags controllin the post-1.4 editor's behavior<br />
<br />
== Predefined macros == <br />
<br />
Wesnoth ships with a library of predefined macros you should find useful in writing your own WML. You can find a description of all such macros [http://www.wesnoth.org/macro-reference.xhtml here].<br />
<br />
== Other ==<br />
<br />
* [[ReferenceWMLSyntax]] how this wiki and the pages it links to should be formatted<br />
* [[ConventionsWML]] how to make your WML more readable<br />
* [[UsefulWMLFragments]] Various pieces of WML for various purposes. If you have some WML you're proud of that you think others can use, add it here.<br />
* [[CommandMode]] commands are not strictly speaking part of WML, these could be a little hard to find so there's a link here.<br />
* [[MultiplayerServerWML]] is used when communicating with the multiplayer server.<br />
* [[CampaignServerWML]] is used when managing contributed campaigns on the campaign server.<br />
* [[ImagePathFunctionWML]] is used when applying the team-color function to images.<br />
* [[BinaryWML]] how WML is sent over the network<br />
<br />
== See Also ==<br />
<br />
* [[BuildingMaps]] the text-based format for Wesnoth maps<br />
* [[TerrainCodesWML]] a list of all terrains<br />
* [[MultiHexTutorial]] a description of the multi-hex tiling system<br />
* [[IGNFileFormat]] a description of the ignore file format<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=InternalActionsWML&diff=28920InternalActionsWML2009-03-21T15:24:33Z<p>Voris: Stage one of page cleanup. First half (conditionals) is cleaned up and has 'development' tags removed.</p>
<hr />
<div>{{WML Tags}}<br />
<br />
Internal actions are actions that WML uses internally that do not directly affect game play. For example, storing a variable is an internal action.<br />
<br />
== Condition Tags ==<br />
<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 />
; [have_unit]<br />
: A unit with greater than zero hit points matching this filter exists.<br />
:* [[StandardUnitFilter]] '''*''': Selection criteria. <br />'''* Note:''' ''Does '''not''' check for matching units in the recall list!''<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 />
<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 variable (see [[VariablesWML]]) 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 greater than this value.<br />
:** '''greater_than_equal_to''': ''$name'' is greater than or equal to this value.<br />
:** '''less_than''': ''$name'' is less than this value.<br />
:** '''less_than_equal_to''': ''$name'' is 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 />'''*''' When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.<br />These values are evaluated as ''false'': '''no''', '''false''', '''off''', '''0''', and '''0.0'''<br />These values are evaluated as ''true'': '''yes''', '''true''', '''on''', '''1''', and '''0.1''' (and any other non-zero number)<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 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 others. 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, if it evaluates to true, is all that is necessary for the conditions to be met. In other words, if all other conditions are false, but one '''[or]''' condition is true, the conditions have been met for an action to take place. (See [[AdvancedConditionalWML|Example]])<br />
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true. <br />
<br />
; [not]<br />
: A condition which reverses the evaluation of the contained condition(s).<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 />
== Conditional Actions ==<br />
<br />
These internal actions describe actions that should be executed only if certain conditions (in almost all cases described using [[#Condition Tags|Condition Tags]]) are met.<br />
<br />
=== [if] ===<br />
<br />
Executes actions only if conditions described in 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 a set of action tags which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.<br />
<br />
* '''[else]''': Contains a set of action tags which should be executed if any condition evaluates as false ''and'' '''all''' of the '''[or]''' tags evaluate as false.<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.<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.<br />
** <Action WML>: Action WML ([[#Variable Actions|Variable Actions]], [[DirectActionsWML]], [[InterfaceActionsWML]], [[#.5Bevent.5D|[event]]], etc.) 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 action WML ([[#Variable Actions|Variable Actions]], [[DirectActionsWML]], [[InterfaceActionsWML]], [[#.5Bevent.5D|[event]]], etc.) 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 1024 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 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 '''FOREACH''' and '''NEXT''' macros documented [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg here].<br />
<br />
==== 'REPEAT' Macro ====<br />
This macro simplifies the use of a '''[while]''' tag to execute the same action(s) repeatedly for a specified number of times. To use it, use the '''REPEAT''' macro documented [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg here].<br />
<br />
== [event] ==<br />
<br />
This adds a new event to the scenario.<br />
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).<br />
This is useful if you want an event that can only be triggered when a prior event is fulfilled<br />
<br />
== Variable Actions ==<br />
<br />
These tags describe actions that affect the values of WML variables<br />
(see [[VariablesWML]] for information on WML variables,<br />
and [[UtilWML]] for convenient macro shortcuts for some of these):<br />
* '''[set_variable]''': manipulates a WML variable. {{Note:Predefined Macro|VARIABLE}} {{DevFeature}} Floating-point arithmetic is now fully supported.<br />
** '''name''': the name of the variable to manipulate<br />
** '''value''': set the variable to the given value (can be numeric or string).Use literal for no substitution. (see [[VariablesWML]])<br />
** '''literal''': set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.<br />
** '''format''': This attribute will be deprecated from 1.7 on. Same behaviour as value.<br />
** '''to_variable''': Fully processes its value as in ''format'', and then gets the variable with that name.<br />
** '''add''': add the given amount to the variable. To subtract, add a negative number.<br />
** '''multiply''': multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. {{DevFeature}} Floating point values are no longer rounded.<br />
** '''divide''': divide the variable by the given number. The result is an integer. {{DevFeature}} Floating point results are no longer rounded. If both variables are integers, [http://en.wikipedia.org/wiki/Division_(mathematics)#Division_of_integers Integer division] is used.<br />
** '''modulo''': returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1. {{DevFeature}} Floating point variables also work.<br />
** '''random''': the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.<br />
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''<br />
** '''time=stamp''': Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.<br />
** {{DevFeature}} '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).<br />
** {{DevFeature}} '''[join]''' joins an array of strings to create a textual list<br />
***variable: name of the array<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to connect the elements<br />
***remove_empty: whether to ignore empty elements<br />
** {{DevFeature}} '''ipart''': Assigns the integer part (the part to the left of the comma) of the referenced variable.<br />
** {{DevFeature}} '''fpart''': Assigns the decimal part (the part to the right of the comma) of the referenced variable.<br />
** {{DevFeature}} '''round''': Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:<br />
***'''ceil''': Rounds upward to the nearest integer.<br />
***'''floor''': Rounds down to the nearest integer.<br />
<br />
* {{DevFeature}} '''[set_variables]''': manipulates a WML array<br />
** '''name''': the name of the container to manipulate<br />
** '''mode''': one of the following values:<br />
***replace: will clean the array '''name''' and replace it with given data<br />
***append: will append given data to the current array<br />
***merge: will merge in the given data into '''name'''<br />
***insert: will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.<br />
** '''to_variable''': data will be set to the given array<br />
** '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags, example:<br />
[set_variables]<br />
name=arr<br />
mode=replace<br />
[value]<br />
foo=bar<br />
[/value]<br />
[value]<br />
foo=more<br />
[/value]<br />
[/set_variables]<br />
{DEBUG_MSG $arr[0].foo}<br />
{DEBUG_MSG $arr[1].foo}<br />
=>bar; more<br />
** '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags<br />
**'''[split]''' splits a textual list into an array which will then be set to data<br />
***list: textual list to split<br />
***key: the key of each array element(array[$i].foo) in which the strings are stored<br />
***separator: separator to separate the elements<br />
***remove_empty: wether to ignore empty elements<br />
<br />
* {{DevFeature}} '''[fire_event]''': trigger a WML event<br />
** '''name''': the name of event to trigger<br />
** '''[primary_unit]''': primary unit for the event (usually the attacker) (optional)<br />
** '''[secondary_unit]''': secondary unit for the event (usually the defender) (optional)<br />
** both tags have some keys which are optional :<br />
*** '''x,y''': location of this unit<br />
*** In Wesnoth 1.5.9 and onwards, [primary_unit] and [secondary_unit] can take a [[FilterWML|Standard Unit Filter]], but it will never match on a recall list unit. If it matches multiple units, the first unit that would be obtained with [store_unit] will be used in the relevant event parameter ($unit or $secondary_unit) and event filter.<br />
** '''[primary_attack]''': information passed to the primary attack filter and $weapon variable on the new event.<br />
** '''[secondary_attack]''': information passed to the second attack filter and $second_weapon variable on the new event.<br />
<br />
* '''[store_unit]''': stores details about units into game variables.<br>Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.<br>Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]<br />
** '''[filter]''': [[StandardUnitFilter]] all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.<br />
** '''variable''': the name of the variable into which to store the unit(s)<br />
** '''mode''': defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.<br />
** '''kill''': if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.<br />
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''<br />
:* description<br />
:* experience<br />
:* facing<br />
:* gender<br />
:* canrecruit<br />
:* overlays<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* moves<br />
:* resting<br />
:* side<br />
:* type<br />
:* unrenamable<br />
:* upkeep<br />
:* user_description<br />
:* x<br />
:* y<br />
:* [variables]<br />
:* [status]<br />
:* [modifications]<br />
Variables, status, and modifications are children of the stored unit variable. Example:<br />
[set_variable]<br />
name=unit_store.status.poisoned<br />
value=yes<br />
[/set_variable]<br />
<br />
:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.<br />
:* advances_to<br />
:* alignment<br />
:* alpha<br />
:* attacks_left<br />
:* canrecruit<br />
:* controller<br />
:* cost<br />
:* description<br />
:* experience<br />
:* facing<br />
:* flying<br />
:* fog<br />
:* gender<br />
:* get_hit_sound<br />
:* gold<br />
:* goto_x<br />
:* goto_y<br />
:* hitpoints<br />
:* id<br />
:* image<br />
:* image_defensive<br />
:* income<br />
:* language_name (same as the name key in the unit config)<br />
:* level<br />
:* max_attacks<br />
:* max_experience<br />
:* max_hitpoints<br />
:* max_moves<br />
:* movement<br />
:* movement_type<br />
:* moves<br />
:* race<br />
:* resting<br />
:* shroud<br />
:* side<br />
:* type<br />
:* unit_description<br />
:* unrenamable<br />
:* usage<br />
:* value<br />
:* x<br />
:* y<br />
:* zoc<br />
:* [advancement]<br />
:* [/advancement]<br />
:* [movement_costs]<br />
:* [/movement_costs]<br />
:* [defense]<br />
:* [/defense]<br />
:* [resistance]<br />
:* [/resistance]<br />
:* [variables]<br />
:* [/variables]<br />
:* [status]<br />
:* [/status]<br />
:* [attack]<br />
:* [/attack]<br />
:* [modifications_description]<br />
:* [/modifications_description]<br />
:* [modifications]<br />
:* [/modifications]<br />
<br />
* '''[store_starting_location]''': Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and {{DevFeature}} 'owner_side' (villages only)<br />
** '''side''': the side whose starting location is to be stored<br />
** '''variable''': (default='location'): the name of the variable to store the location in<br />
* '''[store_locations]''': Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and {{DevFeature}} 'owner_side' (villages only).<br />
** [[StandardLocationFilter]]: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.<br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.<br />
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored<br />
** '''[filter]''': [[StandardUnitFilter]] only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.<br />
* '''[store_villages]''': Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and {{DevFeature}} 'owner_side'.<br />
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages. <br />
** '''variable''': the name of the variable (array) into which to store the locations<br />
** '''terrain''': a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.<br />
* '''[store_gold]''': Stores a side's gold into a variable.<br />
** '''side''': (default=1) the side for which the gold should be stored<br />
** '''variable''': (default='gold') the name of the variable to store the gold in<br />
* '''[store_side]''': stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden' {{DevFeature}}, 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)<br />
** '''side''': the side whose information should be stored<br />
** '''variable''': the name of the variable to store the information in<br />
* '''[clear_variable]''': This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.<br />
** '''name''': the name of the variable to clear, multiple comma-separated variable names can be given.<br />
* '''[role]''': tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. This tag uses a [[StandardUnitFilter]] with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.<br />
** '''role''': the value to store as the unit's role. This role is not used in the [[StandardUnitFilter]] when doing the search for the unit to assign this role to.<br />
** '''type''': a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.<br />
* {{DevFeature}} '''[store_map_dimensions]''': Stores the map dimensions in a variable.<br />
** '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.<br />
* {{DevFeature}} '''[insert_tag]''': inserts a variable as WML<br />
**'''name''': the ["name"] to be given to the tag<br />
**'''variable''': name of the variable to be inserted<br />
* {{DevFeature}} '''[store_time_of_day]''': stores time of day information from the current scenario into a WML variable container.<br />
** '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].<br />
** '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.<br />
<br />
== See Also ==<br />
* [[VariablesWML]]<br />
* [[DirectActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=EventWML&diff=28891EventWML2009-03-20T22:43:08Z<p>Voris: Missed a reference to a tag name that changed in last edit. [filter_second_attack] now references [filter_attack] instead of [special_filter].</p>
<hr />
<div>{{WML Tags}}<br />
== The [event] Tag ==<br />
<br />
This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.<br />
<br />
This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.<br />
<br />
=== The 'name' Key (Mandatory) ===<br />
<br />
Usage:<br />
name=<value><br />
<br />
This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.<br />
<br />
'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''<br />
<br />
The '''name''' key can accept a list of comma separated values describing when the event will be triggered.*<br />
<br />
For example:<br />
<br />
name=attacker_misses,defender_misses<br />
<br />
''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''<br />
<br />
==== Valid 'name' Key Values ====<br />
<br />
All valid values are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here will '''not''' work ''no matter how logical or awesome you think it sounds.''<br />
<br />
; prestart<br />
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.<br />
<br />
; start<br />
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.<br />
<br />
; new turn<br />
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.<br />
<br />
; side turn<br />
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.<br />
<br />
; ai turn<br />
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.<br />
<br />
; turn refresh<br />
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.<br />
<br />
; turn ''X''<br />
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.<br />
<br />
; time over<br />
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])<br />
<br />
; enemies defeated<br />
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.<br />
<br />
; victory<br />
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])<br />
<br />
; defeat<br />
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])<br />
<br />
<br />
Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true. <br />
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]<br />
<br />
; moveto<br />
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.<br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.''<br />
<br />
; sighted<br />
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)<br />
<br />
; attack<br />
: Triggers when the primary unit attacks the secondary unit.<br />
<br />
; attack_end<br />
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.<br />
<br />
; attacker_hits<br />
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.<br />
<br />
; attacker_misses<br />
: Same as ''attacker_hits'', but is triggered when the attacker misses.<br />
<br />
; defender_hits<br />
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.<br />
<br />
; defender_misses<br />
: Same as ''defender_hits'', but is triggered when the defender misses.<br />
<br />
; stone<br />
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).<br />
<br />
; last breath<br />
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.<br />
<br />
; die<br />
: Triggers when the primary unit is killed by the secondary unit.<br />
<br />
; capture<br />
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.<br />
<br />
; recruit<br />
: Triggers when the primary unit is recruited. (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).<br />
<br />
; prerecruit<br />
: Triggers when the primary unit is recruited but before it is displayed.<br />
<br />
; recall<br />
: Triggers after a unit is recalled.<br />
<br />
; prerecall<br />
: Triggers when a unit is recalled but before it is displayed.<br />
<br />
; advance<br />
: Triggers just before the primary unit is going to advance to another unit.<br />
<br />
; post_advance<br />
: Triggers just after the primary unit has advanced to another unit.<br />
<br />
; select<br />
: Triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''<br />
<br />
; menu item X<br />
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''<br />
<br />
; Other events with a custom name may be invoked from [fire_event]<br />
<br />
=== Optional Keys and Tags ===<br />
<br />
These keys and tags are more complex ways to filter when an event should trigger:<br />
<br />
==== first_time_only ====<br />
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:<br />
: ''first_time_only=yes''<br />
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.<br />
: ''first_time_only=no''<br />
:: The event will every time the criteria are met instead of only the first time.<br />
<br />
==== [filter] ====<br />
: The event will only trigger if the primary unit matches this filter.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_second] ====<br />
: Like [filter], but for the secondary unit.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_attack] ====<br />
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''.<br />
:* '''name''': the name of the weapon used.<br />
:* '''range''': the range of the weapon used. <br />
<br />
==== [filter_second_attack] ====<br />
: Like [filter_attack], but for the secondary unit.<br />
:* '''name''': the name of the weapon used.<br />
:* '''range''': the range of the weapon used.<br />
<br />
==== [event] ====<br />
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].<br />
<br />
==== delayed_variable_substitution ====<br />
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.<br />
<br />
=== Actions triggered by [event] ===<br />
<br />
After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.<br />
<br />
There are 3 main types of actions:<br />
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay<br />
* display actions ([[InterfaceActionsWML]]) which show something to the user<br />
* internal actions ([[InternalActionsWML]]) which are used by WML internally<br />
<br />
Several actions use standard filters to find out which units<br />
to execute the command on. These are denoted by the phrases<br />
"standard unit filter" and "standard location filter".<br />
<br />
=== Nested Events ===<br />
<br />
There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).<br />
<br />
([[#Nested Event Example|See Examples]])<br />
<br />
==== Delayed Variable Substitution ====<br />
<br />
Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.<br />
<br />
If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.<br />
<br />
This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.<br />
<br />
([[#Delayed Variable Substitution Example|See Examples]])<br />
<br />
== Miscellaneous Notes and Examples ==<br />
<br />
=== Primary/Secondary Unit Speaker Example ===<br />
<br />
In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:<br />
<br />
[event]<br />
name=die<br />
[message]<br />
speaker='''second_unit'''<br />
message= _ "Hahaha! I finally killed you!"<br />
[/message]<br />
<br />
[message]<br />
speaker='''unit'''<br />
message= _ "It's not over yet! I'll come back to haunt you!"<br />
[/message]<br />
[/event]<br />
<br />
=== Nested Event Example ===<br />
<br />
An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
# moving to 5,8 will trigger this event only on turn 10 and after<br />
[/event]<br />
[/event]<br />
<br />
An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.<br />
<br />
=== Delayed Variable Substitution Example ===<br />
<br />
This code will display the turn on which the nested ''moveto'' event happens.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=yes<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
This code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Finally, this example is identical to the first two, in that it will display the turn on which the nested ''moveto'' event happens despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $|turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
== See Also ==<br />
<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[FilterWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=EventWML&diff=28890EventWML2009-03-20T22:37:35Z<p>Voris: Got rid of all {{DevFeature}} tags and applied all edits to names and functionality called out by those tags.</p>
<hr />
<div>{{WML Tags}}<br />
== The [event] Tag ==<br />
<br />
This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.<br />
<br />
This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.<br />
<br />
=== The 'name' Key (Mandatory) ===<br />
<br />
Usage:<br />
name=<value><br />
<br />
This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.<br />
<br />
'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''<br />
<br />
The '''name''' key can accept a list of comma separated values describing when the event will be triggered.*<br />
<br />
For example:<br />
<br />
name=attacker_misses,defender_misses<br />
<br />
''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''<br />
<br />
==== Valid 'name' Key Values ====<br />
<br />
All valid values are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here will '''not''' work ''no matter how logical or awesome you think it sounds.''<br />
<br />
; prestart<br />
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.<br />
<br />
; start<br />
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.<br />
<br />
; new turn<br />
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.<br />
<br />
; side turn<br />
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.<br />
<br />
; ai turn<br />
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.<br />
<br />
; turn refresh<br />
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.<br />
<br />
; turn ''X''<br />
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.<br />
<br />
; time over<br />
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])<br />
<br />
; enemies defeated<br />
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.<br />
<br />
; victory<br />
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])<br />
<br />
; defeat<br />
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])<br />
<br />
<br />
Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true. <br />
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]<br />
<br />
; moveto<br />
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.<br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.''<br />
<br />
; sighted<br />
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)<br />
<br />
; attack<br />
: Triggers when the primary unit attacks the secondary unit.<br />
<br />
; attack_end<br />
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.<br />
<br />
; attacker_hits<br />
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.<br />
<br />
; attacker_misses<br />
: Same as ''attacker_hits'', but is triggered when the attacker misses.<br />
<br />
; defender_hits<br />
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.<br />
<br />
; defender_misses<br />
: Same as ''defender_hits'', but is triggered when the defender misses.<br />
<br />
; stone<br />
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).<br />
<br />
; last breath<br />
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.<br />
<br />
; die<br />
: Triggers when the primary unit is killed by the secondary unit.<br />
<br />
; capture<br />
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.<br />
<br />
; recruit<br />
: Triggers when the primary unit is recruited. (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).<br />
<br />
; prerecruit<br />
: Triggers when the primary unit is recruited but before it is displayed.<br />
<br />
; recall<br />
: Triggers after a unit is recalled.<br />
<br />
; prerecall<br />
: Triggers when a unit is recalled but before it is displayed.<br />
<br />
; advance<br />
: Triggers just before the primary unit is going to advance to another unit.<br />
<br />
; post_advance<br />
: Triggers just after the primary unit has advanced to another unit.<br />
<br />
; select<br />
: Triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''<br />
<br />
; menu item X<br />
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''<br />
<br />
; Other events with a custom name may be invoked from [fire_event]<br />
<br />
=== Optional Keys and Tags ===<br />
<br />
These keys and tags are more complex ways to filter when an event should trigger:<br />
<br />
==== first_time_only ====<br />
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:<br />
: ''first_time_only=yes''<br />
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.<br />
: ''first_time_only=no''<br />
:: The event will every time the criteria are met instead of only the first time.<br />
<br />
==== [filter] ====<br />
: The event will only trigger if the primary unit matches this filter.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_second] ====<br />
: Like [filter], but for the secondary unit.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_attack] ====<br />
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''.<br />
:* '''name''': the name of the weapon used.<br />
:* '''range''': the range of the weapon used. <br />
<br />
==== [filter_second_attack] ====<br />
: Like [special_filter], but for the secondary unit.<br />
:* '''name''': the name of the weapon used.<br />
:* '''range''': the range of the weapon used.<br />
<br />
==== [event] ====<br />
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].<br />
<br />
==== delayed_variable_substitution ====<br />
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.<br />
<br />
=== Actions triggered by [event] ===<br />
<br />
After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.<br />
<br />
There are 3 main types of actions:<br />
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay<br />
* display actions ([[InterfaceActionsWML]]) which show something to the user<br />
* internal actions ([[InternalActionsWML]]) which are used by WML internally<br />
<br />
Several actions use standard filters to find out which units<br />
to execute the command on. These are denoted by the phrases<br />
"standard unit filter" and "standard location filter".<br />
<br />
=== Nested Events ===<br />
<br />
There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).<br />
<br />
([[#Nested Event Example|See Examples]])<br />
<br />
==== Delayed Variable Substitution ====<br />
<br />
Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.<br />
<br />
If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.<br />
<br />
This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.<br />
<br />
([[#Delayed Variable Substitution Example|See Examples]])<br />
<br />
== Miscellaneous Notes and Examples ==<br />
<br />
=== Primary/Secondary Unit Speaker Example ===<br />
<br />
In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:<br />
<br />
[event]<br />
name=die<br />
[message]<br />
speaker='''second_unit'''<br />
message= _ "Hahaha! I finally killed you!"<br />
[/message]<br />
<br />
[message]<br />
speaker='''unit'''<br />
message= _ "It's not over yet! I'll come back to haunt you!"<br />
[/message]<br />
[/event]<br />
<br />
=== Nested Event Example ===<br />
<br />
An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
# moving to 5,8 will trigger this event only on turn 10 and after<br />
[/event]<br />
[/event]<br />
<br />
An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.<br />
<br />
=== Delayed Variable Substitution Example ===<br />
<br />
This code will display the turn on which the nested ''moveto'' event happens.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=yes<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
This code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Finally, this example is identical to the first two, in that it will display the turn on which the nested ''moveto'' event happens despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $|turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
== See Also ==<br />
<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[FilterWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=EventWML&diff=28383EventWML2009-02-27T18:01:52Z<p>Voris: /* Valid 'name' Key Values */ Removed consider attack and unconsider attack since they were reverted: https://gna.org/bugs/?func=detailitem&item_id=12375#comment7</p>
<hr />
<div>{{WML Tags}}<br />
== The [event] Tag ==<br />
<br />
This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.<br />
<br />
This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.<br />
<br />
=== The 'name' Key (Mandatory) ===<br />
<br />
Usage:<br />
name=<value><br />
<br />
This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.<br />
<br />
'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''<br />
<br />
{{DevFeature}} The '''name''' key can accept a list of comma separated values describing when the event will be triggered.*<br />
<br />
For example:<br />
<br />
name=attacker_misses,defender_misses<br />
<br />
''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''<br />
<br />
==== Valid 'name' Key Values ====<br />
<br />
All valid values are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here will '''not''' work ''no matter how logical or awesome you think it sounds.''<br />
<br />
; prestart<br />
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.<br />
<br />
; start<br />
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.<br />
<br />
; new turn<br />
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.<br />
<br />
; side turn<br />
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.<br />
<br />
; ai turn<br />
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.<br />
<br />
; turn refresh<br />
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.<br />
<br />
; turn ''X''<br />
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.<br />
<br />
; time over<br />
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])<br />
<br />
; enemies defeated<br />
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.<br />
<br />
; victory<br />
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])<br />
<br />
; defeat<br />
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])<br />
<br />
<br />
Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true. <br />
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]<br />
<br />
; moveto<br />
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.<br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.''<br />
<br />
; sighted<br />
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)<br />
<br />
; attack<br />
: Triggers when the primary unit attacks the secondary unit.<br />
<br />
; attack_end<br />
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.<br />
<br />
; attacker_hits<br />
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender).<br />{{DevFeature}} The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.<br />
<br />
; attacker_misses<br />
: Same as ''attacker_hits'', but is triggered when the attacker misses.<br />
<br />
; defender_hits<br />
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender).<br />{{DevFeature}} The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.<br />
<br />
; defender_misses<br />
: Same as ''defender_hits'', but is triggered when the defender misses.<br />
<br />
; stone<br />
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).<br />
<br />
; last breath<br />
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.<br />
<br />
; die<br />
: Triggers when the primary unit is killed by the secondary unit.<br />
<br />
; capture<br />
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.<br />
<br />
; recruit<br />
: Triggers when the primary unit is recruited or recalled. (That is, when a unit is recruited or recalled, it will trigger this event and this event's filter will filter that unit.). {{DevFeature}} The '''recruit''' will no longer triggers on recalls.<br />
<br />
; prerecruit<br />
: Triggers when the primary unit is recruited, but before it is displayed. {{DevFeature}} The '''prerecruit''' will no longer triggers on recalls.<br />
<br />
; advance<br />
: Triggers just before the primary unit is going to advance to another unit.<br />
<br />
; post_advance<br />
: Triggers just after the primary unit has advanced to another unit.<br />
<br />
; select<br />
: Triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''<br />
<br />
; menu item X<br />
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''<br />
<br />
; {{DevFeature}} prerecall<br />
: Triggers when a unit is recalled, but before it is displayed. This event is not trigger when a unit is recruit.<br />
<br />
; {{DevFeature}} recall<br />
: Triggers after a unit is recalled. This event is not trigger when a unit is recruit.<br />
<br />
; {{DevFeature}} Other events with a custom name may be invoked from [fire_event]<br />
<br />
=== Optional Keys and Tags ===<br />
<br />
These keys and tags are more complex ways to filter when an event should trigger:<br />
<br />
==== first_time_only ====<br />
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:<br />
: ''first_time_only=yes''<br />
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.<br />
: ''first_time_only=no''<br />
:: The event will every time the criteria are met instead of only the first time.<br />
<br />
==== [filter] ====<br />
: The event will only trigger if the primary unit matches this filter.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_second] ====<br />
: Like [filter], but for the secondary unit.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [special_filter] ====<br />
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''. ({{DevFeature}} renamed to [filter_attack])<br />
:* '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')<br />
:* {{DevFeature}} '''range''': the range of the weapon used. <br />
<br />
==== [special_filter_second] ====<br />
: Like [special_filter], but for the secondary unit. ({{DevFeature}} renamed to [filter_second_attack])<br />
:* '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')<br />
:* {{DevFeature}} '''range''': the range of the weapon used.<br />
<br />
==== [event] ====<br />
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].<br />
<br />
==== delayed_variable_substitution ====<br />
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.<br />
<br />
=== Actions triggered by [event] ===<br />
<br />
After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.<br />
<br />
There are 3 main types of actions:<br />
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay<br />
* display actions ([[InterfaceActionsWML]]) which show something to the user<br />
* internal actions ([[InternalActionsWML]]) which are used by WML internally<br />
<br />
Several actions use standard filters to find out which units<br />
to execute the command on. These are denoted by the phrases<br />
"standard unit filter" and "standard location filter".<br />
<br />
=== Nested Events ===<br />
<br />
There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).<br />
<br />
([[#Nested Event Example|See Examples]])<br />
<br />
==== Delayed Variable Substitution ====<br />
<br />
Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.<br />
<br />
If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.<br />
<br />
This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.<br />
<br />
([[#Delayed Variable Substitution Example|See Examples]])<br />
<br />
== Miscellaneous Notes and Examples ==<br />
<br />
=== Primary/Secondary Unit Speaker Example ===<br />
<br />
In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:<br />
<br />
[event]<br />
name=die<br />
[message]<br />
speaker='''second_unit'''<br />
message= _ "Hahaha! I finally killed you!"<br />
[/message]<br />
<br />
[message]<br />
speaker='''unit'''<br />
message= _ "It's not over yet! I'll come back to haunt you!"<br />
[/message]<br />
[/event]<br />
<br />
=== Nested Event Example ===<br />
<br />
An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
# moving to 5,8 will trigger this event only on turn 10 and after<br />
[/event]<br />
[/event]<br />
<br />
An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.<br />
<br />
=== Delayed Variable Substitution Example ===<br />
<br />
This code will display the turn on which the nested ''moveto'' event happens.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=yes<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
This code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Finally, this example is identical to the first two, in that it will display the turn on which the nested ''moveto'' event happens despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $|turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
== See Also ==<br />
<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[FilterWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=EventWML&diff=28381EventWML2009-02-27T17:26:22Z<p>Voris: /* delayed_variable_substitution */ Corrected internal link to Delayed Variable Substitution heading</p>
<hr />
<div>{{WML Tags}}<br />
== The [event] Tag ==<br />
<br />
This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.<br />
<br />
This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.<br />
<br />
=== The 'name' Key (Mandatory) ===<br />
<br />
Usage:<br />
name=<value><br />
<br />
This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.<br />
<br />
'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''<br />
<br />
{{DevFeature}} The '''name''' key can accept a list of comma separated values describing when the event will be triggered.*<br />
<br />
For example:<br />
<br />
name=attacker_misses,defender_misses<br />
<br />
''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''<br />
<br />
==== Valid 'name' Key Values ====<br />
<br />
All valid values are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here will '''not''' work ''no matter how logical or awesome you think it sounds.''<br />
<br />
; prestart<br />
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.<br />
<br />
; start<br />
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.<br />
<br />
; new turn<br />
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.<br />
<br />
; side turn<br />
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.<br />
<br />
; ai turn<br />
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.<br />
<br />
; turn refresh<br />
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.<br />
<br />
; turn ''X''<br />
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.<br />
<br />
; time over<br />
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])<br />
<br />
; enemies defeated<br />
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.<br />
<br />
; victory<br />
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])<br />
<br />
; defeat<br />
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])<br />
<br />
<br />
Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true. <br />
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]<br />
<br />
; moveto<br />
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.<br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.''<br />
<br />
; sighted<br />
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)<br />
<br />
; attack<br />
: Triggers when the primary unit attacks the secondary unit.<br />
<br />
; attack_end<br />
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.<br />
<br />
; attacker_hits<br />
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender).<br />{{DevFeature}} The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.<br />
<br />
; attacker_misses<br />
: Same as ''attacker_hits'', but is triggered when the attacker misses.<br />
<br />
; defender_hits<br />
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender).<br />{{DevFeature}} The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.<br />
<br />
; defender_misses<br />
: Same as ''defender_hits'', but is triggered when the defender misses.<br />
<br />
; stone<br />
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).<br />
<br />
; last breath<br />
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.<br />
<br />
; die<br />
: Triggers when the primary unit is killed by the secondary unit.<br />
<br />
; capture<br />
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.<br />
<br />
; recruit<br />
: Triggers when the primary unit is recruited or recalled. (That is, when a unit is recruited or recalled, it will trigger this event and this event's filter will filter that unit.). {{DevFeature}} The '''recruit''' will no longer triggers on recalls.<br />
<br />
; prerecruit<br />
: Triggers when the primary unit is recruited, but before it is displayed. {{DevFeature}} The '''prerecruit''' will no longer triggers on recalls.<br />
<br />
; advance<br />
: Triggers just before the primary unit is going to advance to another unit.<br />
<br />
; post_advance<br />
: Triggers just after the primary unit has advanced to another unit.<br />
<br />
; select<br />
: Triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''<br />
<br />
; menu item X<br />
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''<br />
<br />
; {{DevFeature}} prerecall<br />
: Triggers when a unit is recalled, but before it is displayed. This event is not trigger when a unit is recruit.<br />
<br />
; {{DevFeature}} recall<br />
: Triggers after a unit is recalled. This event is not trigger when a unit is recruit.<br />
<br />
; {{DevFeature}} consider attack<br />
: Triggers before the attack dialog is displayed.<br />
<br />
; {{DevFeature}} unconsider attack<br />
: Triggers when canceling out of the attack dialog.<br />
<br />
; {{DevFeature}} Other events with a custom name may be invoked from [fire_event]<br />
<br />
=== Optional Keys and Tags ===<br />
<br />
These keys and tags are more complex ways to filter when an event should trigger:<br />
<br />
==== first_time_only ====<br />
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:<br />
: ''first_time_only=yes''<br />
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.<br />
: ''first_time_only=no''<br />
:: The event will every time the criteria are met instead of only the first time.<br />
<br />
==== [filter] ====<br />
: The event will only trigger if the primary unit matches this filter.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_second] ====<br />
: Like [filter], but for the secondary unit.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [special_filter] ====<br />
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''. ({{DevFeature}} renamed to [filter_attack])<br />
:* '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')<br />
:* {{DevFeature}} '''range''': the range of the weapon used. <br />
<br />
==== [special_filter_second] ====<br />
: Like [special_filter], but for the secondary unit. ({{DevFeature}} renamed to [filter_second_attack])<br />
:* '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')<br />
:* {{DevFeature}} '''range''': the range of the weapon used.<br />
<br />
==== [event] ====<br />
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].<br />
<br />
==== delayed_variable_substitution ====<br />
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.<br />
<br />
=== Actions triggered by [event] ===<br />
<br />
After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.<br />
<br />
There are 3 main types of actions:<br />
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay<br />
* display actions ([[InterfaceActionsWML]]) which show something to the user<br />
* internal actions ([[InternalActionsWML]]) which are used by WML internally<br />
<br />
Several actions use standard filters to find out which units<br />
to execute the command on. These are denoted by the phrases<br />
"standard unit filter" and "standard location filter".<br />
<br />
=== Nested Events ===<br />
<br />
There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).<br />
<br />
([[#Nested Event Example|See Examples]])<br />
<br />
==== Delayed Variable Substitution ====<br />
<br />
Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.<br />
<br />
If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.<br />
<br />
This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.<br />
<br />
([[#Delayed Variable Substitution Example|See Examples]])<br />
<br />
== Miscellaneous Notes and Examples ==<br />
<br />
=== Primary/Secondary Unit Speaker Example ===<br />
<br />
In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:<br />
<br />
[event]<br />
name=die<br />
[message]<br />
speaker='''second_unit'''<br />
message= _ "Hahaha! I finally killed you!"<br />
[/message]<br />
<br />
[message]<br />
speaker='''unit'''<br />
message= _ "It's not over yet! I'll come back to haunt you!"<br />
[/message]<br />
[/event]<br />
<br />
=== Nested Event Example ===<br />
<br />
An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
# moving to 5,8 will trigger this event only on turn 10 and after<br />
[/event]<br />
[/event]<br />
<br />
An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.<br />
<br />
=== Delayed Variable Substitution Example ===<br />
<br />
This code will display the turn on which the nested ''moveto'' event happens.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=yes<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
This code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Finally, this example is identical to the first two, in that it will display the turn on which the nested ''moveto'' event happens despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $|turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
== See Also ==<br />
<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[FilterWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=EventWML&diff=28380EventWML2009-02-27T17:25:32Z<p>Voris: /* [event] */ Corrected internal link to Nested Events heading</p>
<hr />
<div>{{WML Tags}}<br />
== The [event] Tag ==<br />
<br />
This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.<br />
<br />
This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.<br />
<br />
=== The 'name' Key (Mandatory) ===<br />
<br />
Usage:<br />
name=<value><br />
<br />
This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.<br />
<br />
'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''<br />
<br />
{{DevFeature}} The '''name''' key can accept a list of comma separated values describing when the event will be triggered.*<br />
<br />
For example:<br />
<br />
name=attacker_misses,defender_misses<br />
<br />
''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''<br />
<br />
==== Valid 'name' Key Values ====<br />
<br />
All valid values are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here will '''not''' work ''no matter how logical or awesome you think it sounds.''<br />
<br />
; prestart<br />
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.<br />
<br />
; start<br />
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.<br />
<br />
; new turn<br />
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.<br />
<br />
; side turn<br />
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.<br />
<br />
; ai turn<br />
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.<br />
<br />
; turn refresh<br />
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.<br />
<br />
; turn ''X''<br />
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.<br />
<br />
; time over<br />
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])<br />
<br />
; enemies defeated<br />
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.<br />
<br />
; victory<br />
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])<br />
<br />
; defeat<br />
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])<br />
<br />
<br />
Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true. <br />
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]<br />
<br />
; moveto<br />
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.<br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.''<br />
<br />
; sighted<br />
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)<br />
<br />
; attack<br />
: Triggers when the primary unit attacks the secondary unit.<br />
<br />
; attack_end<br />
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.<br />
<br />
; attacker_hits<br />
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender).<br />{{DevFeature}} The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.<br />
<br />
; attacker_misses<br />
: Same as ''attacker_hits'', but is triggered when the attacker misses.<br />
<br />
; defender_hits<br />
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender).<br />{{DevFeature}} The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.<br />
<br />
; defender_misses<br />
: Same as ''defender_hits'', but is triggered when the defender misses.<br />
<br />
; stone<br />
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).<br />
<br />
; last breath<br />
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.<br />
<br />
; die<br />
: Triggers when the primary unit is killed by the secondary unit.<br />
<br />
; capture<br />
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.<br />
<br />
; recruit<br />
: Triggers when the primary unit is recruited or recalled. (That is, when a unit is recruited or recalled, it will trigger this event and this event's filter will filter that unit.). {{DevFeature}} The '''recruit''' will no longer triggers on recalls.<br />
<br />
; prerecruit<br />
: Triggers when the primary unit is recruited, but before it is displayed. {{DevFeature}} The '''prerecruit''' will no longer triggers on recalls.<br />
<br />
; advance<br />
: Triggers just before the primary unit is going to advance to another unit.<br />
<br />
; post_advance<br />
: Triggers just after the primary unit has advanced to another unit.<br />
<br />
; select<br />
: Triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''<br />
<br />
; menu item X<br />
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''<br />
<br />
; {{DevFeature}} prerecall<br />
: Triggers when a unit is recalled, but before it is displayed. This event is not trigger when a unit is recruit.<br />
<br />
; {{DevFeature}} recall<br />
: Triggers after a unit is recalled. This event is not trigger when a unit is recruit.<br />
<br />
; {{DevFeature}} consider attack<br />
: Triggers before the attack dialog is displayed.<br />
<br />
; {{DevFeature}} unconsider attack<br />
: Triggers when canceling out of the attack dialog.<br />
<br />
; {{DevFeature}} Other events with a custom name may be invoked from [fire_event]<br />
<br />
=== Optional Keys and Tags ===<br />
<br />
These keys and tags are more complex ways to filter when an event should trigger:<br />
<br />
==== first_time_only ====<br />
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:<br />
: ''first_time_only=yes''<br />
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.<br />
: ''first_time_only=no''<br />
:: The event will every time the criteria are met instead of only the first time.<br />
<br />
==== [filter] ====<br />
: The event will only trigger if the primary unit matches this filter.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_second] ====<br />
: Like [filter], but for the secondary unit.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [special_filter] ====<br />
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''. ({{DevFeature}} renamed to [filter_attack])<br />
:* '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')<br />
:* {{DevFeature}} '''range''': the range of the weapon used. <br />
<br />
==== [special_filter_second] ====<br />
: Like [special_filter], but for the secondary unit. ({{DevFeature}} renamed to [filter_second_attack])<br />
:* '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')<br />
:* {{DevFeature}} '''range''': the range of the weapon used.<br />
<br />
==== [event] ====<br />
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].<br />
<br />
==== delayed_variable_substitution ====<br />
: This key is only relevant inside of a [[#Nested Event|nested event]] and controls when variable substitution will occur in those special case actions.<br />
<br />
=== Actions triggered by [event] ===<br />
<br />
After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.<br />
<br />
There are 3 main types of actions:<br />
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay<br />
* display actions ([[InterfaceActionsWML]]) which show something to the user<br />
* internal actions ([[InternalActionsWML]]) which are used by WML internally<br />
<br />
Several actions use standard filters to find out which units<br />
to execute the command on. These are denoted by the phrases<br />
"standard unit filter" and "standard location filter".<br />
<br />
=== Nested Events ===<br />
<br />
There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).<br />
<br />
([[#Nested Event Example|See Examples]])<br />
<br />
==== Delayed Variable Substitution ====<br />
<br />
Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.<br />
<br />
If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.<br />
<br />
This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.<br />
<br />
([[#Delayed Variable Substitution Example|See Examples]])<br />
<br />
== Miscellaneous Notes and Examples ==<br />
<br />
=== Primary/Secondary Unit Speaker Example ===<br />
<br />
In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:<br />
<br />
[event]<br />
name=die<br />
[message]<br />
speaker='''second_unit'''<br />
message= _ "Hahaha! I finally killed you!"<br />
[/message]<br />
<br />
[message]<br />
speaker='''unit'''<br />
message= _ "It's not over yet! I'll come back to haunt you!"<br />
[/message]<br />
[/event]<br />
<br />
=== Nested Event Example ===<br />
<br />
An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
# moving to 5,8 will trigger this event only on turn 10 and after<br />
[/event]<br />
[/event]<br />
<br />
An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.<br />
<br />
=== Delayed Variable Substitution Example ===<br />
<br />
This code will display the turn on which the nested ''moveto'' event happens.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=yes<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
This code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Finally, this example is identical to the first two, in that it will display the turn on which the nested ''moveto'' event happens despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $|turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
== See Also ==<br />
<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[FilterWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=EventWML&diff=28378EventWML2009-02-27T17:23:03Z<p>Voris: Called out name as mandatory and extensive formatting overhaul.</p>
<hr />
<div>{{WML Tags}}<br />
== The [event] Tag ==<br />
<br />
This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.<br />
<br />
This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.<br />
<br />
=== The 'name' Key (Mandatory) ===<br />
<br />
Usage:<br />
name=<value><br />
<br />
This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.<br />
<br />
'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''<br />
<br />
{{DevFeature}} The '''name''' key can accept a list of comma separated values describing when the event will be triggered.*<br />
<br />
For example:<br />
<br />
name=attacker_misses,defender_misses<br />
<br />
''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''<br />
<br />
==== Valid 'name' Key Values ====<br />
<br />
All valid values are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here will '''not''' work ''no matter how logical or awesome you think it sounds.''<br />
<br />
; prestart<br />
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.<br />
<br />
; start<br />
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.<br />
<br />
; new turn<br />
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.<br />
<br />
; side turn<br />
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.<br />
<br />
; ai turn<br />
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.<br />
<br />
; turn refresh<br />
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.<br />
<br />
; turn ''X''<br />
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.<br />
<br />
; time over<br />
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])<br />
<br />
; enemies defeated<br />
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.<br />
<br />
; victory<br />
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])<br />
<br />
; defeat<br />
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])<br />
<br />
<br />
Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true. <br />
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]<br />
<br />
; moveto<br />
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.<br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.''<br />
<br />
; sighted<br />
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)<br />
<br />
; attack<br />
: Triggers when the primary unit attacks the secondary unit.<br />
<br />
; attack_end<br />
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.<br />
<br />
; attacker_hits<br />
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender).<br />{{DevFeature}} The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.<br />
<br />
; attacker_misses<br />
: Same as ''attacker_hits'', but is triggered when the attacker misses.<br />
<br />
; defender_hits<br />
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender).<br />{{DevFeature}} The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.<br />
<br />
; defender_misses<br />
: Same as ''defender_hits'', but is triggered when the defender misses.<br />
<br />
; stone<br />
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).<br />
<br />
; last breath<br />
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.<br />
<br />
; die<br />
: Triggers when the primary unit is killed by the secondary unit.<br />
<br />
; capture<br />
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.<br />
<br />
; recruit<br />
: Triggers when the primary unit is recruited or recalled. (That is, when a unit is recruited or recalled, it will trigger this event and this event's filter will filter that unit.). {{DevFeature}} The '''recruit''' will no longer triggers on recalls.<br />
<br />
; prerecruit<br />
: Triggers when the primary unit is recruited, but before it is displayed. {{DevFeature}} The '''prerecruit''' will no longer triggers on recalls.<br />
<br />
; advance<br />
: Triggers just before the primary unit is going to advance to another unit.<br />
<br />
; post_advance<br />
: Triggers just after the primary unit has advanced to another unit.<br />
<br />
; select<br />
: Triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''<br />
<br />
; menu item X<br />
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''<br />
<br />
; {{DevFeature}} prerecall<br />
: Triggers when a unit is recalled, but before it is displayed. This event is not trigger when a unit is recruit.<br />
<br />
; {{DevFeature}} recall<br />
: Triggers after a unit is recalled. This event is not trigger when a unit is recruit.<br />
<br />
; {{DevFeature}} consider attack<br />
: Triggers before the attack dialog is displayed.<br />
<br />
; {{DevFeature}} unconsider attack<br />
: Triggers when canceling out of the attack dialog.<br />
<br />
; {{DevFeature}} Other events with a custom name may be invoked from [fire_event]<br />
<br />
=== Optional Keys and Tags ===<br />
<br />
These keys and tags are more complex ways to filter when an event should trigger:<br />
<br />
==== first_time_only ====<br />
: Whether the event should be removed from the scenario after it is triggered. There are two possible values for this key:<br />
: ''first_time_only=yes''<br />
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.<br />
: ''first_time_only=no''<br />
:: The event will every time the criteria are met instead of only the first time.<br />
<br />
==== [filter] ====<br />
: The event will only trigger if the primary unit matches this filter.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [filter_second] ====<br />
: Like [filter], but for the secondary unit.<br />
:* [[StandardUnitFilter]]: selection criteria<br />
<br />
==== [special_filter] ====<br />
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''. ({{DevFeature}} renamed to [filter_attack])<br />
:* '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')<br />
:* {{DevFeature}} '''range''': the range of the weapon used. <br />
<br />
==== [special_filter_second] ====<br />
: Like [special_filter], but for the secondary unit. ({{DevFeature}} renamed to [filter_second_attack])<br />
:* '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')<br />
:* {{DevFeature}} '''range''': the range of the weapon used.<br />
<br />
==== [event] ====<br />
: A special case 'action', the [event] tag may be used to create a [[#Nested Event|nested event]].<br />
<br />
==== delayed_variable_substitution ====<br />
: This key is only relevant inside of a [[#Nested Event|nested event]] and controls when variable substitution will occur in those special case actions.<br />
<br />
=== Actions triggered by [event] ===<br />
<br />
After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.<br />
<br />
There are 3 main types of actions:<br />
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay<br />
* display actions ([[InterfaceActionsWML]]) which show something to the user<br />
* internal actions ([[InternalActionsWML]]) which are used by WML internally<br />
<br />
Several actions use standard filters to find out which units<br />
to execute the command on. These are denoted by the phrases<br />
"standard unit filter" and "standard location filter".<br />
<br />
=== Nested Events ===<br />
<br />
There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).<br />
<br />
([[#Nested Event Example|See Examples]])<br />
<br />
==== Delayed Variable Substitution ====<br />
<br />
Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.<br />
<br />
If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.<br />
<br />
This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.<br />
<br />
([[#Delayed Variable Substitution Example|See Examples]])<br />
<br />
== Miscellaneous Notes and Examples ==<br />
<br />
=== Primary/Secondary Unit Speaker Example ===<br />
<br />
In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:<br />
<br />
[event]<br />
name=die<br />
[message]<br />
speaker='''second_unit'''<br />
message= _ "Hahaha! I finally killed you!"<br />
[/message]<br />
<br />
[message]<br />
speaker='''unit'''<br />
message= _ "It's not over yet! I'll come back to haunt you!"<br />
[/message]<br />
[/event]<br />
<br />
=== Nested Event Example ===<br />
<br />
An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
# moving to 5,8 will trigger this event only on turn 10 and after<br />
[/event]<br />
[/event]<br />
<br />
An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.<br />
<br />
=== Delayed Variable Substitution Example ===<br />
<br />
This code will display the turn on which the nested ''moveto'' event happens.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=yes<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
This code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
Finally, this example is identical to the first two, in that it will display the turn on which the nested ''moveto'' event happens despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
{DEBUG_MSG "Turn $|turn_number"} <br />
[/event]<br />
[/event]<br />
<br />
== See Also ==<br />
<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[FilterWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=EventWML&diff=28367EventWML2009-02-27T06:37:09Z<p>Voris: /* The [event] tag */ indented all the bullet items that are values for 'name' and moved [allow_undo] blurb up to moveto tag it is relevant to</p>
<hr />
<div>{{WML Tags}}<br />
== The [event] tag ==<br />
<br />
This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.<br />
<br />
Keys and tags that describe when the event should trigger:<br />
* '''name''': this is not like a normal 'name' key. It is a basic description of when the event will trigger. {{DevFeature}} '''name''' can accept a list of commas separated descriptions for which the event must be triggered. Example: '''name= attacker_misses, defender_misses'''. Note that unless you use ''first_time_only=no'', the event will fire only once, not once for each listed type.<br />
** '''prestart''': the event is triggered before a scenario 'starts' -- before anything is shown on the screen at all. You can use this event to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start'''.<br />
** '''start''': this event triggers after the map is shown but before the scenario begins<br />
** '''new turn''': this event triggers whenever the last player ends their turn. See also '''first_time_only=no'''. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.<br />
** '''side turn''': this event triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.<br />
** '''turn refresh''': this event triggers just before a side is taking control after healing, calculating income, and restoring unit movement and status.<br />
** '''turn X''': (for X some number) this event triggers at the start of turn ''X''. ''X'' cannot be 1.<br />
** '''time over''': this event triggers on turn ''turns''. (''turns'' is specified in [scenario])<br />
** '''enemies defeated''': this event triggers when all units with '''canrecruit=yes''' (i.e. all leaders) not allied with side 1 are killed.<br />
** '''victory''': in this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also [endlevel], [[DirectActionsWML]])<br />
** '''defeat''': in this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])<br />
** '''ai turn''': is triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.<br />
<br />
: Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true. <br />
: These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]<br />
<br />
:* '''moveto''': triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.<br />
:: ''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.''<br />
<br />
:* '''sighted''': this event triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.)<br />
:* '''attack''': this event triggers when the primary unit attacks the secondary unit.<br />
:* '''attacker_hits''': this event triggers when the the primary unit (the attacker) hits the secondary unit (the defender). {{DevFeature}} A variable '''$damage_inflicted''' allow to check the number of hitpoints inflicted by the attacker.<br />
:* '''attacker_misses''': same as ''attacker_hits'', but is triggered when the attacker misses.<br />
:* '''defender_hits''': this event triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). {{DevFeature}} A variable '''$damage_inflicted''' allow to check the number of hitpoints inflicted by the defender.<br />
:* '''defender_misses''': same as ''defender_hits'', but is triggered when the defender misses.<br />
:* '''attack_end''': is similar to '''attack''', but is instead triggered after the fight, not before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.<br />
:* '''stone''': this event triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).<br />
:* '''last breath''': this event triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.<br />
:* '''die''': this event triggers when the primary unit is killed by the secondary unit.<br />
:* '''capture''': this event triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.<br />
:* '''recruit''': this event triggers when the primary unit is recruited or recalled. (That is, when a unit is recruited or recalled, it will trigger this event and this event's filter will filter that unit.). {{DevFeature}} The '''recruit''' will no longer triggers on recalls.<br />
:* '''prerecruit''': this event triggers when the primary unit is recruited, but before it is displayed. {{DevFeature}} The '''prerecruit''' will no longer triggers on recalls.<br />
:* '''advance''': this event triggers just before the primary unit is going to advance to another unit.<br />
:* '''post_advance''': this event triggers just after the primary unit has advanced to another unit.<br />
:* '''select''': triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''<br />
:* '''menu item X''': triggers when a WML menu item with id=X is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.'' <br />
:* {{DevFeature}} '''prerecall''': triggers when a unit is recalled, but before it is displayed. This event is not trigger when a unit is recruit.<br />
:* {{DevFeature}} '''recall''': triggers after a unit is recalled. This event is not trigger when a unit is recruit.<br />
:* {{DevFeature}} other events with a custom name may be invoked from [fire_event]<br />
:* {{DevFeature}} '''consider attack''': triggers before the attack dialog is displayed.<br />
:* {{DevFeature}} '''unconsider attack''': triggers when canceling out of the attack dialog.<br />
<br />
The primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the speaker= key. For example:<br />
<br />
[event]<br />
name=die<br />
[message]<br />
speaker=second_unit<br />
message="Hahaha, I finally killed you!"<br />
[/message]<br />
<br />
[message]<br />
speaker=unit<br />
message="It's not over yet! I'll come back to haunt you!"<br />
[/message]<br />
[/event]<br />
<br />
These keys and tags are more complex ways to filter when an event should trigger:<br />
* '''first_time_only''': whether the event should be removed from the scenario after it is triggered. Default is '''yes'''.<br />
* '''[filter]''': the event will only trigger if the primary unit matches this filter.<br />
** [[StandardUnitFilter]]: selection criteria<br />
* '''[filter_second]''': is like [filter], but for the secondary unit.<br />
** [[StandardUnitFilter]]: selection criteria<br />
* '''[special_filter]''' and '''[special_filter_second]''': can be used to set some additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker_hits'', ''attacker_misses'', ''defender_hits'', ''defender_misses'' and ''attack_end''. ({{DevFeature}} renamed to [filter_attack] and [filter_second_attack])<br />
** '''weapon''': the name of the weapon used. ({{DevFeature}} renamed to '''name''')<br />
** {{DevFeature}} '''range''': the range of the weapon used. <br />
<br />
=== Actions triggered by [event] ===<br />
<br />
After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.<br />
<br />
There are 3 main types of actions:<br />
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay<br />
* display actions ([[InterfaceActionsWML]]) which show something to the user<br />
* internal actions ([[InternalActionsWML]]) which are used by WML internally<br />
<br />
Several actions use standard filters to find out which units<br />
to execute the command on. These are denoted by the phrases<br />
"standard unit filter" and "standard location filter".<br />
<br />
=== Nested events ===<br />
<br />
There is 1 special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is created when the nested event is encountered (when executing the contents of the event). For example, you could create a portal that opens on turn 10. The outer event executes on turn 10, creating the nested moveto event, which executes when a player steps on a certain spot. An equivalent way of doing this would be to a single moveto event with an '''[if]''' statement to check for turn number, but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.<br />
<br />
Example:<br />
<br />
[event]<br />
name=turn 10<br />
<br />
[event]<br />
name=moveto<br />
<br />
[filter]<br />
x,y=5,8<br />
[/filter]<br />
<br />
# moving to 5,8 will trigger this event only on turn 10 and after<br />
[/event]<br />
[/event]<br />
<br />
Variable substitution for a nested event can happen either when the event is spawned, or when it is triggered. This is controlled with the key ''delayed_variable_substitution'' (default yes). Consider the following two examples:<br />
<br />
# This makes the message display the turn on which the moveto happens,<br />
# because the variable substitution for the moveto event will be done<br />
# when the event triggers.<br />
<br />
[event]<br />
name=turn 2<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=yes<br />
<br />
{DEBUG_MSG "Turn $turn_number"}<br />
[/event]<br />
[/event]<br />
<br />
# This makes the message on moveto always display as "Turn 2", because<br />
# the variable substitution is done when the moveto event is spawned,<br />
# not when it eventually triggers.<br />
<br />
[event]<br />
name=turn 2<br />
<br />
[event]<br />
name=moveto<br />
delayed_variable_substitution=no<br />
<br />
{DEBUG_MSG "Turn $turn_number"}<br />
[/event]<br />
[/event]<br />
<br />
Another way to mark an individual variable to be substituted later (when the event is triggered) is to write it as "$|var" instead of the normal "$var". By combining this with delayed_variable_substitution=no you can have some variables in the nested event be substituted immediately when the event is spawned and some variables substituted when the event triggers.<br />
<br />
== See Also ==<br />
<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[FilterWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=SingleUnitWML&diff=27583SingleUnitWML2008-12-13T20:51:33Z<p>Voris: /* How to describe a single unit */ poision & slow claim positive value is 'on' but that doesn't work in [if] cases...testing proves 'yes' does work so changed to reflect this.</p>
<hr />
<div>{{WML Tags}}<br />
== How to describe a single unit ==<br />
<br />
This tag, '''[unit]''', describes a single unit on the map, for example Konrad.<br />
It is different from the [unit] in [units], which describes a class of units.<br />
<br />
The following keys are recognized:<br />
* '''type''': the ID of the unit's unit type. See [[UnitWML]].<br />
<br />
* '''side''': the side that the unit is on.<br />
<br />
* '''gender''': can be set to male or female to designate the gender of the unit. Default is male, but if the unit has only a female variant it will be female.<br />
<br />
* '''x''', '''y''': the location of the unit. If a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list.<br />
<br />
* '''description''': a unique identifier for the unit. This is not displayed to the player, but is to be used only for identifying and filtering for units. If not specified or when a unit is normally recruited, a random one will be generated for the unit to ensure that each unit has a unique ''description'' attribute. Note: This function has been taken over {{DevFeature}} by '''id'''.<br />
<br />
* '''id''': {{DevFeature}} a unique identifier for the unit. This is not displayed to the player, but is to be used only for identifying and filtering for units. If not specified or when a unit is normally recruited, a random one will be generated for the unit to ensure that each unit has a unique ''id'' attribute. In older versions, the '''description''' attribute specified a unique ID.<br />
<br />
* '''user_description''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this. Note: {{DevFeature}} this attribute is removed in 1.5, and its function is fulfilled by '''name'''.<br />
<br />
* '''name''': {{DevFeature}} the user-visible name of the unit. Note that the player may use the "rename unit" action to change this.<br />
<br />
* '''generate_description''': if set to "yes", will generate a new name (user-level description only, not internal unique ID) for the unit, as if the unit were a freshly-recruited one. Note: this attribute has been renamed {{DevFeature}} to '''generate_name'''.<br />
<br />
* '''generate_name''': {{DevFeature}} if set to "yes", will generate a new name (user-level description only, not internal unique ID) for the unit, as if the unit were a freshly-recruited one<br />
<br />
* '''unrenamable''': if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).<br />
<br />
* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.<br />
<br />
* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give a unit less traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.<br />
<br />
* '''random_gender''': "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.<br />
<br />
* '''canrecruit''': a special key for leaders.<br />
** '''no''': default. Unit cannot recruit.<br />
** '''yes''': unit can recruit.<br />
: Normally when a team controls no units with '''canrecruit=yes''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=yes'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with '''canrecruit=yes''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.<br />
<br />
* '''variation''': the variation of itself the unit should be created as.<br />
<br />
* '''upkeep''': the amount of upkeep the unit costs.<br />
** '''loyal''' no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])<br />
** '''full''': unit costs ''level'' upkeep (see [[UnitWML]]).<br />
** An integer can be used to set the upkeep cost to that number.<br />
** The default is "full".<br />
** Leaders (units with '''canrecruit=yes''') never pay upkeep no matter what upkeep is set to.<br />
** Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.<br />
<br />
* '''overlays''': a list of images that are overlayed on the unit.<br />
<br />
* '''goto_x''':, '''goto_y''': UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.<br />
<br />
* '''hitpoints''': the HP of the unit. Default is the max HP for ''type''.<br />
<br />
* '''experience''': the XP of the unit. Default is 0.<br />
<br />
* '''moves''': number of movement points the unit has left. Default is the movement for its unit type.<br />
<br />
* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.<br />
<br />
* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).<br />
<br />
* '''ai_special''': causes the unit to act differently.<br />
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it).<br />
<br />
* '''facing''': which way the unit is facing (this only affects how the unit is displayed).<br />
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Using '''sw''' is preferred for a "reversed" facing (looking to the left) and '''se''' for a normal (looking to the right) facing.<br />
<br />
* '''profile''': sets a default portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type.<br />
<br />
** "unit_image" if given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).<br />
<br />
* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.<br />
<br />
* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'off', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The status of a unit is displayed on the Status Table; each status modification ''statusmod'' is represented by the image '''misc/statusmod.png'''.<br />
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].<br />
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, ''slowed'' is set to 'off' <br />
** '''stone''': if 'yes', the unit cannot move, attack, or be attacked.<br />
** '''hides''': if 'yes', the unit cannot be seen by opponents.<br />
<br />
* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).<br />
<br />
* '''[modifications]''' changes that have been made to the unit.<br />
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].<br />
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].<br />
<br />
* '''unit_description''': overrides the unit type description for this unit. You will probably want to set up a ''post_advance'' [[EventWML|event]] to override the default description after promotions. Or better, use an object with a profile [[EffectWML|effect(s)]] to filter on unit type and change the unit description and/or portrait.<br />
<br />
== See Also ==<br />
<br />
* [[UnitWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category:WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=AnimationWML&diff=27552AnimationWML2008-12-06T16:40:53Z<p>Voris: /* Field Description */ reference start_time role in making duration work as replacement for begin/end</p>
<hr />
<div>{{WML Tags}}<br />
<br />
<br />
== Introduction ==<br />
<br />
This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.<br />
<br />
This page will deal with the two problems of animations<br />
* How are animations Chosen<br />
* What exactly is drawn<br />
<br />
<br />
<br />
== How animations are drawn ==<br />
=== Animations ===<br />
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as<br />
* unit is attacking<br />
* unit is idling<br />
* unit is attacking (event) and uses a melee weapon (condition)<br />
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)<br />
<br />
events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.<br />
<br />
=== Frames ===<br />
<br />
An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix<br />
<br />
A frame typically describes an image, where an how to render it. It can contain such things as<br />
* the image to display<br />
* how transparent should that image be<br />
* where to draw that image.<br />
<br />
At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time<br />
<br />
<br />
The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned<br />
<br />
=== Timing, Clock, Multiple animations ===<br />
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start<br />
<br />
This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.<br />
<br />
The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine<br />
<br />
In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.<br />
<br />
Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.<br />
<br />
==== Example Syntax ====<br />
[attack_anim]<br />
[attack_filter]<br />
name= _ "bow"<br />
[/attack_filter]<br />
'''start_time'''=-350<br />
'''missile_start_time'''=-150<br />
[missile_frame]<br />
duration=150<br />
image="projectiles/missile-n.png"<br />
image_diagonal="projectiles/missile-ne.png"<br />
[/missile_frame]<br />
[if]<br />
hits=yes<br />
[frame]<br />
duration=350<br />
sound=bow.ogg<br />
[/frame]<br />
[/if]<br />
[else]<br />
hits=no<br />
[frame]<br />
duration=350<br />
sound=bow-miss.ogg<br />
[/frame]<br />
[/else]<br />
[/attack_anim]<br />
<br />
=== The content of a frame ===<br />
==== Syntax summary ====<br />
[frame]<br />
duration=<integer><br />
begin=<deprecated,integer><br />
end=<deprecated,integer><br />
image=<string><br />
image_diagonal=<string><br />
image_mod=<string><br />
sound=<string><br />
halo=<progressive string><br />
halo_x=<progressive int><br />
halo_y=<progressive int><br />
halo_mod=<string><br />
alpha=<progressive float><br />
offset=<progressive float><br />
blend_color=< red, green, blue ><br />
blend_ratio=<progressive float><br />
text=<string><br />
text_color=< red, green, blue ><br />
submerge=<dev:progressige float><br />
x=<dev:progressive int><br />
y=<dev:progressive int><br />
layer=<dev:progressive int><br />
[/frame]<br />
<br />
<br />
dev denotes a {{DevFeature}}<br />
<br />
==== Progressive parameters ====<br />
<br />
Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.<br />
<br />
A typical example would be a unit progressively fading out, becoming transparent<br />
<br />
To do that, you could use:<br />
<br />
alpha=1~0<br />
<br />
To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:<br />
<br />
alpha=1~0:300,0:300,0~1:300<br />
<br />
you could also specify it like that<br />
<br />
alpha=1~0,0,0~1<br />
<br />
when a timing is missing, the engine will do its best to fill in in a fair way. <br />
<br />
a progressive string has a similar syntax<br />
<br />
halo=halo1.png:300,halo2.png:300,halo2.png:300<br />
<br />
==== Field Description ====<br />
<br />
** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''<br />
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.<br />
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.<br />
** '''image''': the image to display during the frame.<br />
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).<br />
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images<br />
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.<br />
** '''halo''': the halo to display at the time.<br />
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.<br />
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.<br />
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes<br />
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.<br />
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.<br />
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.<br />
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.<br />
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).<br />
** '''text_color''': the color of the above floating label.<br />
** '''submerge''': {{DevFeature}} the part of the unit that should drawn with 50% opacity (for units in water)<br />
** '''x''': {{DevFeature}} x offset applied to the frame<br />
** '''y''': {{DevFeature}} y offset applied to the frame<br />
** '''layer''': {{DevFeature}} layer used to draw the frame, see discussion bellow<br />
<br />
=== Drawing related animation content ===<br />
==== Syntax summary ====<br />
[animation]<br />
<animation choice related content><br />
[frame]<br />
<frame content><br />
[/frame]<br />
[frame]<br />
<frame content><br />
[/frame]<br />
start_time=<integer><br />
offset=<progressive float><br />
image_mod=<string><br />
blend_with=<r,g,b><br />
blend_ratio=<progressive float><br />
halo=<progressive_string><br />
halo_x=<progressive int><br />
halo_y=<progressive int><br />
halo_mod=<string><br />
submerge=<dev:progressive float><br />
x=<dev:progressive int><br />
y=<dev:progressive int><br />
layer=<dev:progressive int><br />
<br />
[xxx_frame]<br />
<frame content><br />
[/xxx_frame]<br />
xxx_start_time=<integer><br />
xxx_image_mod=<string><br />
xxx_offset=<progressive float><br />
xxx_blend_with=<r,g,b><br />
xxx_blend_ratio=<progressive float><br />
xxx_halo=<progressive_string><br />
xxx_halo_x=<progressive int><br />
xxx_halo_y=<progressive int><br />
xxx_halo_mod=<string><br />
xxx_submerge=<dev:progressive float><br />
xxx_x=<dev:progressive int><br />
xxx_y=<dev:progressive int><br />
xxx_layer=<dev:progressive int><br />
<br />
[/animation]<br />
<br />
dev denotes a {{DevFeature}}<br />
<br />
==== Parameter handling ====<br />
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame. <br />
<br />
The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.<br />
<br />
== How animations are chosen ==<br />
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played. <br />
<br />
Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :<br />
* a normal walking animation<br />
* a swimming animation when the unit is in water<br />
* a tiptioeing animation when moving next to an ennemy unit<br />
<br />
Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.<br />
<br />
To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation<br />
* Start with all animations<br />
* Drop all animations with a criteria that fails on the current situation<br />
* Take the animations that have the most maching criterias<br />
* If there are more than one animation remaining, take an animation randomly<br />
* If all animations have been droped, the engine will provide a smart default.<br />
<br />
here is a pseudo-code explaination of this algorithm<br />
<br />
foreach animation<br />
animation_score = 0<br />
foreach filter-criteria<br />
if <criteria-fails> <br />
animation_score = -1;<br />
break;<br />
elsif <criteria-matches> <br />
animation_score++<br />
endfor<br />
if animation_score > max_score<br />
<empty animation list><br />
max_score = animation_score;<br />
push(animation,animation_list);<br />
elsif animation_score = max_score<br />
push(animation,animation_list);<br />
endfor<br />
<choose an animation randomly from animation_list><br />
<br />
<br />
Note that all animations don't have all the filters...<br />
<br />
so, if we have a unit with<br />
# an animation for water terrain<br />
# an animation for SE on grassland<br />
# an animation with no criteria<br />
# an animation for N,NE,NW,S,SW,SE<br />
# an animation for NW<br />
<br />
* 3. will never be taken, because 4. will always trump it<br />
* on water going NW, it can be 1. 4. 5.<br />
* on water, any direction but NW, it will be 1. or 4.<br />
* on SE grassland it will be 2.<br />
* on other grasslands, it will be 4. (4. or 5. if NW)<br />
<br />
=== Generic animation filters available for all animations ===<br />
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below<br />
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event<br />
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].<br />
* '''[unit_filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[unit_filter]''' blocks in an animation. ({{DevFeature}} renamed to [filter])<br />
* '''[secondary_unit_filter]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[secondary_unit_filter]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail. ({{DevFeature}} renamed to [filter_second])<br />
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).<br />
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.<br />
* '''[attack_filter]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]]. ({{DevFeature}} renamed to [filter_attack])<br />
* '''[secondary_attack_filter]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail. ({{DevFeature}} renamed to [filter_second_attack])<br />
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:<br />
** '''hit''': the attack hits, defender survives.<br />
** '''no''' or '''miss''': the attack misses.<br />
** '''kill''': the attack hits, defender dies.<br />
** '''yes''': is an alias of '''hit,kill'''.<br />
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1).<br />
<br />
=== Events trigerring animations and default animations ===<br />
==== standing ====<br />
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered<br />
<br />
this is the default "standing image" for the unit<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used<br />
==== selected ====<br />
This animation is triggered whenever the unit is selected<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''<br />
==== recruited ====<br />
This animation is triggered whenever the unit is recruited or recalled<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''<br />
==== levelin ====<br />
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''<br />
==== levelout ====<br />
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''<br />
==== movement ====<br />
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation<br />
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar<br />
* when a unit enters a hex, the current anim is tested again.<br />
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is<br />
** if it fails, a new movement anim is searched<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''<br />
==== pre_teleport ====<br />
This animation is triggered whenever the unit teleports, but before it has moved to the target hex<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''<br />
==== post_teleport ====<br />
This animation is triggered whenever the unit teleports, but after it has moved to the target hex<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''<br />
==== healing ====<br />
This animation is triggered when the unit has healing powers and uses them<br />
<br />
''value='' is the number of points healed<br />
<br />
No default is provided by the engine<br />
==== healed ====<br />
This animation is triggered whenever the unit is healed for any reason<br />
<br />
''value='' is the number of points healed<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''<br />
and plays the sound ''heal.wav''<br />
==== poisoned ====<br />
This animation is triggered whenever the unit suffers poison dammage<br />
<br />
''value='' is the number of points lost<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''<br />
and plays the sound 'poison.ogg''<br />
==== defend ====<br />
This animation is triggered during a strike, of the unit receiving the blow<br />
<br />
''value='' is the number of point lost, if any<br />
<br />
No default is provided by the engine<br />
==== attack ====<br />
This animation is triggered during a strike, of the unit giving the blow<br />
<br />
''value='' is the number of damage dealt, if any<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks<br />
No default is provided for range attacks<br />
==== leading ====<br />
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
No default is provided by the engine<br />
==== death ====<br />
This animation is triggered when a unit die.<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit<br />
==== victory ====<br />
This animation is triggered when a unit finishes a fight by killing the other unit<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
No default is provided by the engine<br />
==== idling ====<br />
This animation is called when the unit has been using its standing animation for a random duration.<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
No default is provided by the engine<br />
<br />
==== default {{DevFeature}} ====<br />
<br />
This animation is never triggered, but is used as a base to create new animations<br />
<br />
''value='' is used depending of the type of animation it replaces<br />
<br />
A single animation made of the base frame is provided by the engine if no default animation is available<br />
<br />
==== extra animations ====<br />
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.<br />
<br />
Note that WML events can also trigger standard animations.<br />
''value='' is set from the WML event<br />
<br />
== Shortcuts, tricks and quirks ==<br />
<br />
=== ''[if]'' and ''[else]'' ===<br />
<br />
Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that. <br />
<br />
Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):<br />
<br />
[if]<br />
hits=no<br />
[frame]<br />
begin=-100<br />
end=100<br />
image="units/dwarves/lord-attack.png"<br />
sound={SOUND_LIST:MISS}<br />
[/frame]<br />
[/if]<br />
[else]<br />
hits=yes<br />
[frame]<br />
begin=-100<br />
end=100<br />
image="units/dwarves/lord-attack.png"<br />
sound=axe.ogg<br />
[/frame]<br />
[/else]<br />
<br />
note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection<br />
<br />
=== Simplified animation blocks ===<br />
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported<br />
<br />
some of these use extra tags which are translated in the normal ''value='' tag<br />
<br />
some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose<br />
<br />
* '''[leading_anim]''' is an animation with the following parameters automatically set<br />
apply_to=leading<br />
* '''[recruit_anim]''' is an animation with the following parameters automatically set<br />
apply_to=recruited<br />
* '''[standing_anim]''' is an animation with the following parameters automatically set<br />
apply_to=standing,default<br />
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.<br />
<br />
i.e: the animation will be used to build default animations<br />
* '''[idle_anim]''' is an animation with the following parameters automatically set<br />
apply_to=idling<br />
* '''[levelin_anim]''' is an animation with the following parameters automatically set<br />
apply_to=levelin<br />
* '''[levelout_anim]''' is an animation with the following parameters automatically set<br />
apply_to=levelout<br />
* '''[healing_anim]''' is an animation with the following parameters automatically set<br />
apply_to=healing<br />
value=<damage= value><br />
* '''[healed_anim]''' is an animation with the following parameters automatically set<br />
apply_to=healed<br />
value=<healing= value><br />
[_healed_sound_frame]<br />
sound=heal.wav<br />
[/_healed_sound_frame]<br />
* '''[poison_anim]''' is an animation with the following parameters automatically set<br />
apply_to=poisoned<br />
value=<damage= value><br />
[_poison_sound_frame]<br />
sound=poison.ogg<br />
[/_poison_sound_frame]<br />
* '''[movement_anim]''' is an animation with the following parameters automatically set<br />
apply_to=movement<br />
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"<br />
* '''[defend]''' is an animation with the following parameters automatically set<br />
apply_to=defend<br />
value=<damage= value><br />
<WML content><br />
[frame]<br />
blend_with=255,0,0<br />
blend_ratio="0.5:50,0.0:50"<br />
[/frame]<br />
<br />
there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned<br />
<br />
* '''[attack_anim]''' is an animation with the following parameters automatically set<br />
if the animation contains a missile frame<br />
<br />
apply_to=attack<br />
missile_offset="0~0.8"<br />
<br />
else<br />
<br />
apply_to=attack<br />
offset="0~0.6,0.6~0"<br />
<br />
* '''[death]''' is an animation with the following parameters automatically set<br />
apply_to=death<br />
[_death_sound_frame]<br />
sound=<die_sound= of the enclosing [unit] tag><br />
[/_death_sound_frame]<br />
* '''[victory_anim]''' is an animation with the following parameters automatically set<br />
apply_to=victory<br />
* '''[extra_anim]''' is an animation with the following parameters automatically set<br />
apply_to=<flag= value of the anim><br />
* '''[teleport_anim]''' will be cut into two at the clock-time 0<br />
everything before zero becomes an animation with the following parameters automatically set<br />
apply_to=pre_teleport<br />
everything after zero becomes an animation with the following parameters automatically set<br />
apply_to=post_teleport<br />
<br />
== Layering ==<br />
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.<br />
<br />
this value must be between 0 and 100<br />
<br />
* the back of haloes is drawn with a value of 10<br />
* when unspecified, a animation is drawn with a value of 40<br />
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50<br />
* orbs and status bars are drawn on layer 80<br />
* when unspecified missile frames are drawn on layer 90<br />
<br />
by changing these values, it is easy to have the unit display the way you want<br />
<br />
== See Also ==<br />
<br />
* [[UnitWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=AnimationWML&diff=27550AnimationWML2008-12-06T16:24:31Z<p>Voris: /* Timing, Clock, Multiple animations */ (added start_time key info</p>
<hr />
<div>{{WML Tags}}<br />
<br />
<br />
== Introduction ==<br />
<br />
This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.<br />
<br />
This page will deal with the two problems of animations<br />
* How are animations Chosen<br />
* What exactly is drawn<br />
<br />
<br />
<br />
== How animations are drawn ==<br />
=== Animations ===<br />
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as<br />
* unit is attacking<br />
* unit is idling<br />
* unit is attacking (event) and uses a melee weapon (condition)<br />
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)<br />
<br />
events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.<br />
<br />
=== Frames ===<br />
<br />
An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix<br />
<br />
A frame typically describes an image, where an how to render it. It can contain such things as<br />
* the image to display<br />
* how transparent should that image be<br />
* where to draw that image.<br />
<br />
At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time<br />
<br />
<br />
The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned<br />
<br />
=== Timing, Clock, Multiple animations ===<br />
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start<br />
<br />
This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.<br />
<br />
The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine<br />
<br />
In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.<br />
<br />
Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.<br />
<br />
==== Example Syntax ====<br />
[attack_anim]<br />
[attack_filter]<br />
name= _ "bow"<br />
[/attack_filter]<br />
'''start_time'''=-350<br />
'''missile_start_time'''=-150<br />
[missile_frame]<br />
duration=150<br />
image="projectiles/missile-n.png"<br />
image_diagonal="projectiles/missile-ne.png"<br />
[/missile_frame]<br />
[if]<br />
hits=yes<br />
[frame]<br />
duration=350<br />
sound=bow.ogg<br />
[/frame]<br />
[/if]<br />
[else]<br />
hits=no<br />
[frame]<br />
duration=350<br />
sound=bow-miss.ogg<br />
[/frame]<br />
[/else]<br />
[/attack_anim]<br />
<br />
=== The content of a frame ===<br />
==== Syntax summary ====<br />
[frame]<br />
duration=<integer><br />
begin=<deprecated,integer><br />
end=<deprecated,integer><br />
image=<string><br />
image_diagonal=<string><br />
image_mod=<string><br />
sound=<string><br />
halo=<progressive string><br />
halo_x=<progressive int><br />
halo_y=<progressive int><br />
halo_mod=<string><br />
alpha=<progressive float><br />
offset=<progressive float><br />
blend_color=< red, green, blue ><br />
blend_ratio=<progressive float><br />
text=<string><br />
text_color=< red, green, blue ><br />
submerge=<dev:progressige float><br />
x=<dev:progressive int><br />
y=<dev:progressive int><br />
layer=<dev:progressive int><br />
[/frame]<br />
<br />
<br />
dev denotes a {{DevFeature}}<br />
<br />
==== Progressive parameters ====<br />
<br />
Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.<br />
<br />
A typical example would be a unit progressively fading out, becoming transparent<br />
<br />
To do that, you could use:<br />
<br />
alpha=1~0<br />
<br />
To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:<br />
<br />
alpha=1~0:300,0:300,0~1:300<br />
<br />
you could also specify it like that<br />
<br />
alpha=1~0,0,0~1<br />
<br />
when a timing is missing, the engine will do its best to fill in in a fair way. <br />
<br />
a progressive string has a similar syntax<br />
<br />
halo=halo1.png:300,halo2.png:300,halo2.png:300<br />
<br />
==== Field Description ====<br />
<br />
** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''<br />
** '''end''': (deprecated) see '''begin'''<br />
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.<br />
** '''image''': the image to display during the frame.<br />
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).<br />
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images<br />
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.<br />
** '''halo''': the halo to display at the time.<br />
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.<br />
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.<br />
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes<br />
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.<br />
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.<br />
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.<br />
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.<br />
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).<br />
** '''text_color''': the color of the above floating label.<br />
** '''submerge''': {{DevFeature}} the part of the unit that should drawn with 50% opacity (for units in water)<br />
** '''x''': {{DevFeature}} x offset applied to the frame<br />
** '''y''': {{DevFeature}} y offset applied to the frame<br />
** '''layer''': {{DevFeature}} layer used to draw the frame, see discussion bellow<br />
<br />
=== Drawing related animation content ===<br />
==== Syntax summary ====<br />
[animation]<br />
<animation choice related content><br />
[frame]<br />
<frame content><br />
[/frame]<br />
[frame]<br />
<frame content><br />
[/frame]<br />
start_time=<integer><br />
offset=<progressive float><br />
image_mod=<string><br />
blend_with=<r,g,b><br />
blend_ratio=<progressive float><br />
halo=<progressive_string><br />
halo_x=<progressive int><br />
halo_y=<progressive int><br />
halo_mod=<string><br />
submerge=<dev:progressive float><br />
x=<dev:progressive int><br />
y=<dev:progressive int><br />
layer=<dev:progressive int><br />
<br />
[xxx_frame]<br />
<frame content><br />
[/xxx_frame]<br />
xxx_start_time=<integer><br />
xxx_image_mod=<string><br />
xxx_offset=<progressive float><br />
xxx_blend_with=<r,g,b><br />
xxx_blend_ratio=<progressive float><br />
xxx_halo=<progressive_string><br />
xxx_halo_x=<progressive int><br />
xxx_halo_y=<progressive int><br />
xxx_halo_mod=<string><br />
xxx_submerge=<dev:progressive float><br />
xxx_x=<dev:progressive int><br />
xxx_y=<dev:progressive int><br />
xxx_layer=<dev:progressive int><br />
<br />
[/animation]<br />
<br />
dev denotes a {{DevFeature}}<br />
<br />
==== Parameter handling ====<br />
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame. <br />
<br />
The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.<br />
<br />
== How animations are chosen ==<br />
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played. <br />
<br />
Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :<br />
* a normal walking animation<br />
* a swimming animation when the unit is in water<br />
* a tiptioeing animation when moving next to an ennemy unit<br />
<br />
Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.<br />
<br />
To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation<br />
* Start with all animations<br />
* Drop all animations with a criteria that fails on the current situation<br />
* Take the animations that have the most maching criterias<br />
* If there are more than one animation remaining, take an animation randomly<br />
* If all animations have been droped, the engine will provide a smart default.<br />
<br />
here is a pseudo-code explaination of this algorithm<br />
<br />
foreach animation<br />
animation_score = 0<br />
foreach filter-criteria<br />
if <criteria-fails> <br />
animation_score = -1;<br />
break;<br />
elsif <criteria-matches> <br />
animation_score++<br />
endfor<br />
if animation_score > max_score<br />
<empty animation list><br />
max_score = animation_score;<br />
push(animation,animation_list);<br />
elsif animation_score = max_score<br />
push(animation,animation_list);<br />
endfor<br />
<choose an animation randomly from animation_list><br />
<br />
<br />
Note that all animations don't have all the filters...<br />
<br />
so, if we have a unit with<br />
# an animation for water terrain<br />
# an animation for SE on grassland<br />
# an animation with no criteria<br />
# an animation for N,NE,NW,S,SW,SE<br />
# an animation for NW<br />
<br />
* 3. will never be taken, because 4. will always trump it<br />
* on water going NW, it can be 1. 4. 5.<br />
* on water, any direction but NW, it will be 1. or 4.<br />
* on SE grassland it will be 2.<br />
* on other grasslands, it will be 4. (4. or 5. if NW)<br />
<br />
=== Generic animation filters available for all animations ===<br />
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below<br />
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event<br />
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].<br />
* '''[unit_filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[unit_filter]''' blocks in an animation. ({{DevFeature}} renamed to [filter])<br />
* '''[secondary_unit_filter]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[secondary_unit_filter]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail. ({{DevFeature}} renamed to [filter_second])<br />
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).<br />
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.<br />
* '''[attack_filter]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]]. ({{DevFeature}} renamed to [filter_attack])<br />
* '''[secondary_attack_filter]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail. ({{DevFeature}} renamed to [filter_second_attack])<br />
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:<br />
** '''hit''': the attack hits, defender survives.<br />
** '''no''' or '''miss''': the attack misses.<br />
** '''kill''': the attack hits, defender dies.<br />
** '''yes''': is an alias of '''hit,kill'''.<br />
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1).<br />
<br />
=== Events trigerring animations and default animations ===<br />
==== standing ====<br />
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered<br />
<br />
this is the default "standing image" for the unit<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used<br />
==== selected ====<br />
This animation is triggered whenever the unit is selected<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''<br />
==== recruited ====<br />
This animation is triggered whenever the unit is recruited or recalled<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''<br />
==== levelin ====<br />
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''<br />
==== levelout ====<br />
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''<br />
==== movement ====<br />
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation<br />
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar<br />
* when a unit enters a hex, the current anim is tested again.<br />
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is<br />
** if it fails, a new movement anim is searched<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''<br />
==== pre_teleport ====<br />
This animation is triggered whenever the unit teleports, but before it has moved to the target hex<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''<br />
==== post_teleport ====<br />
This animation is triggered whenever the unit teleports, but after it has moved to the target hex<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''<br />
==== healing ====<br />
This animation is triggered when the unit has healing powers and uses them<br />
<br />
''value='' is the number of points healed<br />
<br />
No default is provided by the engine<br />
==== healed ====<br />
This animation is triggered whenever the unit is healed for any reason<br />
<br />
''value='' is the number of points healed<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''<br />
and plays the sound ''heal.wav''<br />
==== poisoned ====<br />
This animation is triggered whenever the unit suffers poison dammage<br />
<br />
''value='' is the number of points lost<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''<br />
and plays the sound 'poison.ogg''<br />
==== defend ====<br />
This animation is triggered during a strike, of the unit receiving the blow<br />
<br />
''value='' is the number of point lost, if any<br />
<br />
No default is provided by the engine<br />
==== attack ====<br />
This animation is triggered during a strike, of the unit giving the blow<br />
<br />
''value='' is the number of damage dealt, if any<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks<br />
No default is provided for range attacks<br />
==== leading ====<br />
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
No default is provided by the engine<br />
==== death ====<br />
This animation is triggered when a unit die.<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit<br />
==== victory ====<br />
This animation is triggered when a unit finishes a fight by killing the other unit<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
No default is provided by the engine<br />
==== idling ====<br />
This animation is called when the unit has been using its standing animation for a random duration.<br />
<br />
''value='' is not used, and always contains 0<br />
<br />
No default is provided by the engine<br />
<br />
==== default {{DevFeature}} ====<br />
<br />
This animation is never triggered, but is used as a base to create new animations<br />
<br />
''value='' is used depending of the type of animation it replaces<br />
<br />
A single animation made of the base frame is provided by the engine if no default animation is available<br />
<br />
==== extra animations ====<br />
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.<br />
<br />
Note that WML events can also trigger standard animations.<br />
''value='' is set from the WML event<br />
<br />
== Shortcuts, tricks and quirks ==<br />
<br />
=== ''[if]'' and ''[else]'' ===<br />
<br />
Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that. <br />
<br />
Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):<br />
<br />
[if]<br />
hits=no<br />
[frame]<br />
begin=-100<br />
end=100<br />
image="units/dwarves/lord-attack.png"<br />
sound={SOUND_LIST:MISS}<br />
[/frame]<br />
[/if]<br />
[else]<br />
hits=yes<br />
[frame]<br />
begin=-100<br />
end=100<br />
image="units/dwarves/lord-attack.png"<br />
sound=axe.ogg<br />
[/frame]<br />
[/else]<br />
<br />
note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection<br />
<br />
=== Simplified animation blocks ===<br />
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported<br />
<br />
some of these use extra tags which are translated in the normal ''value='' tag<br />
<br />
some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose<br />
<br />
* '''[leading_anim]''' is an animation with the following parameters automatically set<br />
apply_to=leading<br />
* '''[recruit_anim]''' is an animation with the following parameters automatically set<br />
apply_to=recruited<br />
* '''[standing_anim]''' is an animation with the following parameters automatically set<br />
apply_to=standing,default<br />
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.<br />
<br />
i.e: the animation will be used to build default animations<br />
* '''[idle_anim]''' is an animation with the following parameters automatically set<br />
apply_to=idling<br />
* '''[levelin_anim]''' is an animation with the following parameters automatically set<br />
apply_to=levelin<br />
* '''[levelout_anim]''' is an animation with the following parameters automatically set<br />
apply_to=levelout<br />
* '''[healing_anim]''' is an animation with the following parameters automatically set<br />
apply_to=healing<br />
value=<damage= value><br />
* '''[healed_anim]''' is an animation with the following parameters automatically set<br />
apply_to=healed<br />
value=<healing= value><br />
[_healed_sound_frame]<br />
sound=heal.wav<br />
[/_healed_sound_frame]<br />
* '''[poison_anim]''' is an animation with the following parameters automatically set<br />
apply_to=poisoned<br />
value=<damage= value><br />
[_poison_sound_frame]<br />
sound=poison.ogg<br />
[/_poison_sound_frame]<br />
* '''[movement_anim]''' is an animation with the following parameters automatically set<br />
apply_to=movement<br />
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"<br />
* '''[defend]''' is an animation with the following parameters automatically set<br />
apply_to=defend<br />
value=<damage= value><br />
<WML content><br />
[frame]<br />
blend_with=255,0,0<br />
blend_ratio="0.5:50,0.0:50"<br />
[/frame]<br />
<br />
there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned<br />
<br />
* '''[attack_anim]''' is an animation with the following parameters automatically set<br />
if the animation contains a missile frame<br />
<br />
apply_to=attack<br />
missile_offset="0~0.8"<br />
<br />
else<br />
<br />
apply_to=attack<br />
offset="0~0.6,0.6~0"<br />
<br />
* '''[death]''' is an animation with the following parameters automatically set<br />
apply_to=death<br />
[_death_sound_frame]<br />
sound=<die_sound= of the enclosing [unit] tag><br />
[/_death_sound_frame]<br />
* '''[victory_anim]''' is an animation with the following parameters automatically set<br />
apply_to=victory<br />
* '''[extra_anim]''' is an animation with the following parameters automatically set<br />
apply_to=<flag= value of the anim><br />
* '''[teleport_anim]''' will be cut into two at the clock-time 0<br />
everything before zero becomes an animation with the following parameters automatically set<br />
apply_to=pre_teleport<br />
everything after zero becomes an animation with the following parameters automatically set<br />
apply_to=post_teleport<br />
<br />
== Layering ==<br />
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.<br />
<br />
this value must be between 0 and 100<br />
<br />
* the back of haloes is drawn with a value of 10<br />
* when unspecified, a animation is drawn with a value of 40<br />
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50<br />
* orbs and status bars are drawn on layer 80<br />
* when unspecified missile frames are drawn on layer 90<br />
<br />
by changing these values, it is easy to have the unit display the way you want<br />
<br />
== See Also ==<br />
<br />
* [[UnitWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=How_to_play&diff=26906How to play2008-09-28T10:53:50Z<p>Voris: Redirect so hyperlinks in email that leave off all periods will still work.</p>
<hr />
<div>#REDIRECT [[How_to_play...]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=How_to_play..&diff=26905How to play..2008-09-28T10:53:09Z<p>Voris: Redirect so hyperlinks in email that leave off some periods will still work.</p>
<hr />
<div>#REDIRECT [[How_to_play...]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=How_to_play.&diff=26904How to play.2008-09-28T10:52:23Z<p>Voris: Stupidly used full url in original. Now just has page name.</p>
<hr />
<div>#REDIRECT [[How_to_play...]]</div>Vorishttps://wiki.wesnoth.org/index.php?title=How_to_play.&diff=26903How to play.2008-09-28T10:51:12Z<p>Voris: Redirect so hyperlinks in email that leave off some periods will still work.</p>
<hr />
<div>#REDIRECT [[http://www.wesnoth.org/wiki/How_to_play...]]</div>Voris