~~NOTOC~~
<=[[4rpl:start| Index]]

<WRAP tabs>
  * [[4rpl:commands:GetUnitPosition|Get]]
  * [[4rpl:commands:SetUnitPosition|Set]]
</WRAP>

====== GetUnitPosition ======
GetUnitPosition(<-UID) ->pos

===== Description =====
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]]