Added a few useful macros.

data/utils.cfg

@@ -137,6 +137,191 @@ message={MSG}
 [/message]
 #enddef
 
+
+
+# MODIFY_UNIT alters a unit variable (such as unit.x, unit.type,
+# unit.side), handling all the storing and unstoring.
+#
+# Example that flips all spearmen to side 2:
+# {MODIFY_UNIT type=Spearman side 2}
+
+#define MODIFY_UNIT FILTER VAR VALUE
+    [store_unit]
+        [filter]
+            {FILTER}
+        [/filter]
+
+        variable=MODIFY_UNIT_store
+        kill=yes
+    [/store_unit]
+
+    {FOREACH MODIFY_UNIT_store MODIFY_UNIT_i}
+        [set_variable]
+            name=MODIFY_UNIT_store[$MODIFY_UNIT_i].{VAR}
+            value={VALUE}
+        [/set_variable]
+
+        [unstore_unit]
+            variable=MODIFY_UNIT_store[$MODIFY_UNIT_i]
+            find_vacant=no
+        [/unstore_unit]
+    {NEXT MODIFY_UNIT_i}
+
+    {CLEAR_VARIABLE MODIFY_UNIT_store}
+#enddef
+
+
+# Stores an attribute of a unit to the given variable.
+#
+# Example where this is used to flip all orcs to whatever side James is on:
+#
+# {STORE_UNIT_VAR description=James side side_of_James}
+# {MODIFY_UNIT race=orc side $side_of_James}
+
+#define STORE_UNIT_VAR FILTER VAR TO_VAR
+    [store_unit]
+        [filter]
+            {FILTER}
+        [/filter]
+
+        kill=no
+        variable=STORE_UNIT_VAR_store
+    [/store_unit]
+
+    {VARIABLE_OP {TO_VAR} format $STORE_UNIT_VAR_store.{VAR}}
+
+    {CLEAR_VARIABLE STORE_UNIT_VAR_store}
+#enddef 
+
+
+# This is a way to check whether or not the terrain in the given coordinates
+# is of the given type or types. Might be useful, since filtering by terrain
+# isn't possible directly.
+#
+# You can use it for example like this:
+#
+# [event]
+#     name=moveto
+#     first_time_only=no
+#
+#     {IF_TERRAIN $x1 $y1 gfm (
+#         [then]
+#             {DEBUG_MSG "Stepped on grassland, forest or mountains!"}
+#         [/then]
+#     )}
+# [/event]
+
+#define IF_TERRAIN X Y TYPES CONTENTS
+    [store_locations]
+        x={X}
+        y={Y}
+        terrain={TYPES}
+        variable=IF_TERRAIN_temp
+    [/store_locations]
+ 
+    [if]
+        [variable]
+            name=IF_TERRAIN_temp.length
+            not_equals=0
+        [/variable]
+ 
+        {CONTENTS}
+    [/if]
+ 
+    {CLEAR_VARIABLE IF_TERRAIN_temp}
+#enddef
+
+
+# Moves a unit from its current location to the given location along a
+# relatively straight line displaying the movement just like [move_unit_fake]
+# does.
+#
+# Note that setting the destination on an existing unit does not kill either
+# one, but causes the unit to move to the nearest vacant hex instead.
+
+#define MOVE_UNIT FILTER TO_X TO_Y
+    [store_unit]
+        [filter]
+            {FILTER}
+        [/filter]
+ 
+        variable=MOVE_UNIT_temp
+        kill=no
+    [/store_unit]
+
+    [scroll_to]
+        x=$MOVE_UNIT_temp.x
+        y=$MOVE_UNIT_temp.y
+    [/scroll_to]
+
+    [hide_unit]
+        x=$MOVE_UNIT_temp.x
+        y=$MOVE_UNIT_temp.y
+    [/hide_unit]
+
+    {VARIABLE_OP x_coords format ("$MOVE_UNIT_temp.x|,{TO_X}")}
+    {VARIABLE_OP y_coords format ("$MOVE_UNIT_temp.y|,{TO_Y}")}
+
+    [move_unit_fake]
+        type=$MOVE_UNIT_temp.type
+        x=$x_coords
+        y=$y_coords
+    [/move_unit_fake]
+
+    [teleport]
+        [filter]
+            {FILTER}
+        [/filter]
+
+        x,y={TO_X},{TO_Y}
+    [/teleport]
+
+    [unhide_unit][/unhide_unit]
+
+    [redraw][/redraw]
+#enddef
+
+
+# This places a given unit back to the recall list of the side it is on.
+# Note however, that the unit is not healed to full health, so when
+# recalled (even if not until the next scenario) the unit may have less
+# than his maximum hp left.
+#
+# An example, that returns all units stepping on (20,38) back to the recall
+# list:
+# 
+# [event]
+#     name=moveto
+#
+#     [filter]
+#         x,y=20,38
+#     [/filter]
+#
+#     {PUT_TO_RECALL_LIST x,y=20,38}
+# [/event]
+
+#define PUT_TO_RECALL_LIST FILTER
+    [store_unit]
+        [filter]
+            {FILTER}
+        [/filter]
+
+        variable=PUT_TO_RECALL_LIST_temp
+        kill=yes
+    [/store_unit]
+ 
+    {FOREACH temp i}
+        {VARIABLE PUT_TO_RECALL_LIST_temp[$i].x "recall"}
+        {VARIABLE PUT_TO_RECALL_LIST_temp[$i].y "recall"}
+
+        [unstore_unit]
+            variable=PUT_TO_RECALL_LIST_temp[$i]
+            find_vacant=no
+        [/unstore_unit]
+    {NEXT i}
+#enddef
+
+
 #macro to make a side start a scenario with villages
 
 #define STARTING_VILLAGES SIDE RADIUS