Difference between revisions of "DirectActionsWML"
From The Battle for Wesnoth Wiki
m (→result=continue_no_save: try to fix spurious heading) |
(reformat) |
||
| Line 5: | Line 5: | ||
The following tags are actions: | The following tags are actions: | ||
* '''[endlevel]''' ends the scenario. | * '''[endlevel]''' ends the scenario. | ||
| − | ** ''result'' before the scenario is over, all events with | + | ** ''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: |
| − | The message '''' | + | ** ''bonus'' whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). |
| − | are displayed. | + | ** ''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''. |
| − | If | + | * '''[unit]''' places a unit on the map. For syntax see [[SingleUnitWML]]. |
| − | if | + | * '''[recall]''' recalls a unit. The unit is recalled free of charge, and is placed near the leader. |
| − | These last two are rarely used: | + | ** ''standard unit filter'' the first matching unit will be recalled. If no units match this tag is ignored. |
| − | is not reduced to 80%, and it does not | + | ** ''x,y'' the unit is placed here instead of next to the leader. |
| − | bring up a "Victory" message or | ||
| − | the gold changing message (since it doesn't change); | ||
| − | |||
| − | and is taken directly to the next scenario without any messages. | ||
| − | Unless | ||
| − | ** ''bonus'' whether the player should get bonus gold | ||
| − | (maximum possible gold that could have been earned by waiting the level out). | ||
| − | ** ''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''. | ||
| − | * '''[unit]''' places a unit on the map. | ||
| − | For syntax see [[SingleUnitWML]]. | ||
| − | * '''[recall]''' recalls a unit. | ||
| − | The unit is recalled free of charge, and is placed near the leader. | ||
| − | ** standard unit filter | ||
| − | If no units match this tag is ignored. | ||
| − | ** ''x | ||
** ''show'' if not "no", display the unit being recalled. | ** ''show'' if not "no", display the unit being recalled. | ||
* '''[teleport]''' teleports a unit on map. | * '''[teleport]''' teleports a unit on map. | ||
** '''[filter]''' (standard unit filter) all units matching the filter will be teleported. | ** '''[filter]''' (standard unit filter) all units matching the filter will be teleported. | ||
| − | ** ''x | + | ** ''x,y'' the position to teleport to. |
* '''[terrain_mask]''' changes the terrain on the map. See [[TerrainMaskWML]]. | * '''[terrain_mask]''' changes the terrain on the map. See [[TerrainMaskWML]]. | ||
* '''[terrain]''' changes the terrain on the map. | * '''[terrain]''' changes the terrain on the map. | ||
| − | ** ''letter'' the character of the terrain to use. | + | ** ''letter'' the character of the terrain to use. See [[TerrainLettersWML]] to see what letter a type of terrain uses. |
| − | See [[TerrainLettersWML]] to see what letter a type of terrain uses. | ||
** standard location filter- the area to change the terrain of. | ** standard location filter- the area to change the terrain of. | ||
* '''[gold]''' give one side gold. | * '''[gold]''' give one side gold. | ||
** ''amount'' the amount of gold to give. | ** ''amount'' the amount of gold to give. | ||
** ''side'' (default=1) the number of the side to give the gold to. | ** ''side'' (default=1) the number of the side to give the gold to. | ||
| − | * '''[unstore_unit]''' creates a unit from a game variable, activates it on the playing field, then clears the variable. | + | * '''[unstore_unit]''' creates a unit from a game variable, activates it on the playing field, then clears the variable. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. See also [store_unit] and [while], both in [[InternalActionsWML]]. |
| − | This must be a specific variable describing a unit, and may not be an array | ||
| − | -- to unstore an entire array, iterate over it. | ||
| − | See also [store_unit] and [while], both in [[InternalActionsWML]]. | ||
** ''variable'' the name of the variable. | ** ''variable'' the name of the variable. | ||
| − | ** ''find_vacant'' whether the unit should be placed on the nearest vacant tile to its specified location. | + | ** ''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. |
| − | If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed. | ||
* '''[allow_recruit]''' allows a side to recruit units it couldn't previously recruit. | * '''[allow_recruit]''' allows a side to recruit units it couldn't previously recruit. | ||
** ''type'' the types of units that the side can now recruit. | ** ''type'' the types of units that the side can now recruit. | ||
| Line 57: | Line 35: | ||
** ''recruit'' the types of units that the side can now recruit. | ** ''recruit'' the types of units that the side can now recruit. | ||
** ''side'' (default=1) the number of the side that is having its recruitment set. | ** ''side'' (default=1) the number of the side that is having its recruitment set. | ||
| − | * '''[modify_side]''' modifies some details of a given side in the middle of a scenario. | + | * '''[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!''' |
| − | |||
| − | [modify_side] can affect! | ||
** ''side'' (default=1) the number of the side that is to be changed. | ** ''side'' (default=1) the number of the side that is to be changed. | ||
** ''income'' the income given at the begining of each turn. | ** ''income'' the income given at the begining of each turn. | ||
| Line 66: | Line 42: | ||
* '''[capture_village]''' changes the ownership of a village. | * '''[capture_village]''' changes the ownership of a village. | ||
** ''side'' the side that takes control of the village. If not given, the village will become neutral. | ** ''side'' the side that takes control of the village. If not given, the village will become neutral. | ||
| − | ** ''x | + | ** ''x, y'' the location of the village. |
* '''[kill]''' Removes all units that match the filter from the game. | * '''[kill]''' Removes all units that match the filter from the game. | ||
** standard unit filter | ** standard unit filter | ||
| Line 73: | Line 49: | ||
* '''[unstone]''' Unstones all units that match the filter. | * '''[unstone]''' Unstones all units that match the filter. | ||
** standard unit filter | ** standard unit filter | ||
| − | * '''[object]''' gives some unit an object | + | * '''[object]''' gives some unit an object and removes all items on the tile the unit is on. |
| − | and removes all items on the tile the unit is on. | + | ** ''id'' when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an ID can only be used once, even if first_time_only=no is set for the event. |
| − | ** ''id'' when the object is picked up, a flag is set for ''id''. | + | ** '''[effect]''' one or more effect elements may be listed. See [[EffectWML]] for a description of [effect]. |
| − | 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. | ||
| − | ** '''[effect]''' one or more effect elements may be listed. | ||
| − | See [[EffectWML]] for a description of [effect]. | ||
** ''duration'' if 'level', effects only last until the end of the level. | ** ''duration'' if 'level', effects only last until the end of the level. | ||
| − | ** '''[filter]''' (standard unit filter) the first unit found that matches the filter will be given the object. | + | ** '''[filter]''' (standard unit filter) 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. |
| − | If no unit matches the filter, then a message is displayed and the object is not removed. | ||
** ''silent'' whether a message should be displayed. Default is "no". | ** ''silent'' whether a message should be displayed. Default is "no". | ||
** ''image'' the displayed image of the object. | ** ''image'' the displayed image of the object. | ||
| Line 89: | Line 59: | ||
** ''description'' (translatable) displayed as a message of the image. | ** ''description'' (translatable) displayed as a message of the image. | ||
** ''cannot_use_message'' (translatable) displayed instead of '''description''' if no unit passes the filter test. | ** ''cannot_use_message'' (translatable) displayed instead of '''description''' if no unit passes the filter test. | ||
| − | * '''[remove_shroud]''' removes some shroud from the map for a certain side | + | * '''[remove_shroud]''' removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes). |
| − | (only relevant for sides that have shroud=yes). | ||
** ''side'' (default=1) the side for which to remove shroud. | ** ''side'' (default=1) the side for which to remove shroud. | ||
** standard location filter- the range of tiles for which shroud should be removed. | ** standard location filter- the range of tiles for which shroud should be removed. | ||
| − | * '''[place_shroud]''' places some shroud on the map for a certain side | + | * '''[place_shroud]''' places some shroud on the map for a certain side (only relevant for sides that have shroud=yes). |
| − | (only relevant for sides that have shroud=yes). | ||
** ''side'' (default=1) the side for which to place shroud. | ** ''side'' (default=1) the side for which to place shroud. | ||
** standard location filter- the range of tiles on which shroud should be placed. | ** standard location filter- the range of tiles on which shroud should be placed. | ||
| − | * '''[allow_undo]''' allows the player to undo the event that this tag is inside. | + | * '''[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. Therefore, it is advised that you do not use '''[allow_undo]''' before or after usage of other actions from [[DirectActionsWML]]. If you modify a variable(i.e. [[InternalActionsWML]]), set it back before using '''[allow_undo]'''. However, you can check a conditional, and only allow undo if you do not use the actions. |
| − | 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. | ||
| − | Therefore, it is advised that you do not use '''[allow_undo]''' before or after | ||
| − | usage of other actions from [[DirectActionsWML]]. | ||
| − | If you modify a variable(i.e. [[InternalActionsWML]]), set it back before using '''[allow_undo]'''. | ||
| − | However, you can check a conditional, and only allow undo if you do not use the actions. | ||
== See Also == | == See Also == | ||
Revision as of 19:41, 28 August 2005
Direct actions
Direct actions are actions that have a direct effect on gameplay.
The following tags are actions:
- [endlevel] ends the scenario.
- result before the scenario is over, all events with name=result are triggered. The message result_message with the heading result_heading (see LanguageWML) are displayed. If result=victory, the player progresses to the next level; if result=defeat, the game returns to the main menu. These last two are rarely used: result=continue behaves identically to result=victory except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); result=continue_no_save works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless result=defeat, the following keys can also be used:
- bonus whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out).
- 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.
- [unit] places a unit on the map. For syntax see SingleUnitWML.
- [recall] recalls a unit. The unit is recalled free of charge, and is placed near the leader.
- standard unit filter the first matching unit will be recalled. If no units match this tag is ignored.
- x,y the unit is placed here instead of next to the leader.
- show if not "no", display the unit being recalled.
- [teleport] teleports a unit on map.
- [filter] (standard unit filter) all units matching the filter will be teleported.
- x,y the position to teleport to.
- [terrain_mask] changes the terrain on the map. See TerrainMaskWML.
- [terrain] changes the terrain on the map.
- letter the character of the terrain to use. See TerrainLettersWML to see what letter a type of terrain uses.
- standard location filter- the area to change the terrain of.
- [gold] give one side gold.
- amount the amount of gold to give.
- side (default=1) the number of the side to give the gold to.
- [unstore_unit] creates a unit from a game variable, activates it on the playing field, then clears the variable. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. See also [store_unit] and [while], both in InternalActionsWML.
- variable the name of the variable.
- find_vacant whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
- [allow_recruit] allows a side to recruit units it couldn't previously recruit.
- type the types of units that the side can now recruit.
- side (default=1) the number of the side that is being allowed to recruit the units.
- [disallow_recruit] prevents a side from recruiting units it could previously recruit.
- type the types of units that the side can no longer recruit.
- side (default=1) the number of the side that may no longer recruit the units.
- [set_recruit] sets the units a side can recruit.
- recruit the types of units that the side can now recruit.
- side (default=1) the number of the side that is having its recruitment set.
- [modify_side] modifies some details of a given side in the middle of a scenario. The following listed properties are the only properties that [modify_side] can affect!
- side (default=1) the number of the side that is to be changed.
- income the income given at the begining of each turn.
- team_name the team in which the side plays the scenario.
- gold the amount of gold the side owns.
- [capture_village] changes the ownership of a village.
- side the side that takes control of the village. If not given, the village will become neutral.
- x, y the location of the village.
- [kill] Removes all units that match the filter from the game.
- standard unit filter
- animate if 'yes', displays the unit dying (fading away).
- fire_event if 'yes', triggers any appropriate 'die' events (See EventWML).
- [unstone] Unstones all units that match the filter.
- standard unit filter
- [object] gives some unit an object and removes all items on the tile the unit is on.
- id when the object is picked up, a flag is set for id. The object cannot be picked up if a flag for id has been set. This means that any object with an ID can only be used once, even if first_time_only=no is set for the event.
- [effect] one or more effect elements may be listed. See EffectWML for a description of [effect].
- duration if 'level', effects only last until the end of the level.
- [filter] (standard unit filter) 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.
- silent whether a message should be displayed. Default is "no".
- image the displayed image of the object.
- name (translatable) displayed as a caption of the image.
- description (translatable) displayed as a message of the image.
- cannot_use_message (translatable) displayed instead of description if no unit passes the filter test.
- [remove_shroud] removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
- side (default=1) the side for which to remove shroud.
- standard location filter- the range of tiles for which shroud should be removed.
- [place_shroud] places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
- side (default=1) the side for which to place shroud.
- standard location filter- the range of tiles on which shroud should be placed.
- [allow_undo] allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. Therefore, it is advised that you do not use [allow_undo] before or after usage of other actions from DirectActionsWML. If you modify a variable(i.e. InternalActionsWML), set it back before using [allow_undo]. However, you can check a conditional, and only allow undo if you do not use the actions.