DirectActionsWML - Revision history

Soliton: /* [move_unit] */

2025-05-05T09:54:11Z

‎[move_unit]

Laela: /* [gold] */ side is not used anymore

2025-04-02T17:55:47Z

‎[gold]: side is not used anymore

Laela: /* [modify_unit] */ type and experience

2025-01-13T19:57:56Z

‎[modify_unit]: type and experience

Celtic Minstrel: /* [modify_unit] */ Replace Markdown markup with wiki markup

2024-12-07T16:38:44Z

‎[modify_unit]: Replace Markdown markup with wiki markup

White haired uncle: /* [modify_unit] */ - correct description of hitpoints example

2024-11-13T20:44:16Z

‎[modify_unit]: - correct description of hitpoints example

Jarom: Add information about $teleport_unit in [tunnel]

2024-09-04T18:47:40Z

Add information about $teleport_unit in [tunnel]

Laela: /* [cancel_action] */

2024-07-28T18:06:01Z

‎[cancel_action]

Soliton: /* [remove_trait] */

2024-07-01T17:55:35Z

‎[remove_trait]

Celtic Minstrel: Link to the redirect instead of the section (so it still works if we ever make it not a redirect anymore)

2024-02-22T03:40:20Z

Link to the redirect instead of the section (so it still works if we ever make it not a redirect anymore)

Celtic Minstrel: /* [unstore_unit] */ Use M dashes instead of N dashes – the N dashes look too much like hyphens and are confusing

2024-01-24T14:14:50Z

‎[unstore_unit]: Use M dashes instead of N dashes – the N dashes look too much like hyphens and are confusing

@@ Line 221: / Line 221: @@
 === [move_unit] ===
-Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.
+Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through. If the target location is occupied, the nearest free location is chosen.
-* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.
+* [[StandardUnitFilter]] inline; do not use a [filter] tag. All units matching the filter are moved.
 * '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.
 * '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.

@@ Line 93: / Line 93: @@
 Gives sides gold.
 * '''amount''': the amount of gold to give.
-* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.
+* [[StandardSideFilter]] sides to give the gold to. Default is all sides.
 === [unstore_unit] ===

@@ Line 263: / Line 263: @@
 The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their current value. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).
-Modifying a unit ''may'' trigger an advancement event if the experience is set higher than the max_experience. However, this behaviour should not be relied upon to happen under all circumstances; if it's desired, the event should be triggered separately, for example with '''[transform_unit]'''.
+Modifying a unit ''may'' trigger an advancement event if the experience is set higher than the max_experience. However, this behaviour should not be relied upon to happen under all circumstances; if it's desired, the event should be triggered separately, for example with '''[transform_unit]'''. Setting value, including empty string, of ''type'' acts as shortcut of ''experience="$this_unit.max_experience"''.
 '''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are ''not'' reset in [remove_object] and are thus safe to use directly in [modify_unit]:

@@ Line 265: / Line 265: @@
 Modifying a unit ''may'' trigger an advancement event if the experience is set higher than the max_experience. However, this behaviour should not be relied upon to happen under all circumstances; if it's desired, the event should be triggered separately, for example with '''[transform_unit]'''.
-'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:
+'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are ''not'' reset in [remove_object] and are thus safe to use directly in [modify_unit]:
 * '''side'''
 * '''gender'''

@@ Line 261: / Line 261: @@
 </syntaxhighlight>
-The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).
+The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their current value. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).
 Modifying a unit ''may'' trigger an advancement event if the experience is set higher than the max_experience. However, this behaviour should not be relied upon to happen under all circumstances; if it's desired, the event should be triggered separately, for example with '''[transform_unit]'''.

@@ Line 560: / Line 560: @@
 * '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".
-* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).
+* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es). Use $teleport_unit to filter on unit being teleported.
-* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).
+* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es). Use $teleport_unit to filter on unit being teleported.
 * '''id''': (optional) identifier for the tunnel, to allow removing.
 * '''remove''': (boolean, default: no)  If yes, removes all defined tunnels with the same ID (then only id= is necessary).

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

@@ Line 339: / Line 339: @@
 * [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.
-* '''trait_id''': The id of the object to be removed.
+* '''trait_id''': The id of the trait to be removed. See [[UnitsWML#.5Btrait.5D|[trait]]].
 === [remove_shroud] ===

@@ Line 104: / Line 104: @@
 * To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.
-The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[SyntaxWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
+The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[VariablesWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].
 The tag takes the following keys:
@@ Line 408: / Line 408: @@
 {{DevFeature1.13|2}}
 Contains commands to execute when the player undoes the action which triggered the parent event.
-*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)
+*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[VariablesWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)
 Note:

@@ Line 122: / Line 122: @@
 ** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.
-Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit&ndash;and killed&ndash;in combat.) The details of the unusual behavior are subject to change between stable releases without warning.
+Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit&mdash;and killed&mdash;in combat.) The details of the unusual behavior are subject to change between stable releases without warning.
 === [allow_recruit] ===