Differences

This shows you the differences between two versions of the page.

--- 4rpl:commands:getunitposition [2021/01/08 16:01] – external edit 127.0.0.1
+++ 4rpl:commands:getunitposition [2025/02/14 14:57] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
 ~~NOTOC~~
 <=[[4rpl:start| Index]]
+<WRAP tabs>
+  * [[4rpl:commands:GetUnitPosition|Get]]
+  * [[4rpl:commands:SetUnitPosition|Set]]
+</WRAP>
 ====== GetUnitPosition ======
@@ Line 8: / Line 13: @@
 Get the 3D position of a unit.  A vector is returned.  The X and Z positions are where on the map the unit is, and the Y coordinate
 is the height, or elevation, of the unit.
+Note: If this call is attempted on an non-existing unit, nothing will be put on the stack.
+In V 2.4, this behavior changes and this API will now return V3(0 0 0), similar to other APIs.
 ===== Examples =====
 <code 4rpl>
 GetUnitPosition(<-UID) ->pos
+# to extract the individual values from the above vector:
+<-pos.x ->positionX
+<-pos.y ->positionY
+<-pos.z ->positonZ
+# or use the .dot syntax above to directly access the values in the vector, or
+EV3(<-pos) ->z ->y ->x
 </code>
+A "safe" method to use this function and to handle the lack of a return value on non-existent units are as follows:
+<code 4rpl>
+	Trace (@UnitPos(7) )
+:unitPos
+    StackSize ->size
+    GetUnitPosition
+    If (Stacksize <-size NEQ)
+        V3(-1 -1 -1)
+    endif
+</code>
 <=[[4rpl:start| Index]]

Knuckle Cracker Wiki