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

<WRAP tabs>
  * [[4rpl:commands:GetUnitSpecifiedTarget|Get]]
  * [[4rpl:commands:SetUnitSpecifiedTarget|Set]]
  * [[4rpl:commands:ClearUnitSpecifiedTarget|Clear]]
</WRAP>

====== SetUnitSpecifiedTarget ======
SetUnitSpecifiedTarget(<-Unit <-pos)

===== Description =====
Sets a unit's specified target location. The specified target is a map cell location that is set either by player interaction or by script.

''<-pos'' must be a V3, despite the Y location being completely unused. It expects the vector to be this: ''V3(<-X 0 <-Z)'', so if your input is this; ''V2(<-X <-Z)'' the Z value will be read incorrectly. You may easily "convert" vectors as such: ''V3(swap(EV2(<-vector) 0))'' or ''EV2 0 swap V3'' or ''<-vector.y ->vector.z'' If you are converting two ints into a V3, (like what [[GetUnitCell]] returns,) simply push a 0 and [[swap]].

----

The "SpecifiedTarget" only exists when the unit has "Can Specify Target" enabled in their cpack settings, found in the "Basic" tab of Settings. When a unit allows "Can Specify Target", an opaque line or arch (specified by [[SetUnitSpecifiedTargetPathHeight]]((A height of 0 means it will be a line, any other number will produce an arch with an apex of that height value.))) can be seen even when inside or behind terrain along with a visable gray target icon at the SpecifiedTarget location. The gray line can become invisible by using the API [[SetUnitSpecifiedTargetShowPath]] to set it to <color #8BDFFF>false</color>, making __only the gray line invisible__ (except at 0,0,0).\\
Both the gray line (if visible) and gray target marker will follow the mouse when selected. SpecifiedTarget is good for units that like to allow a player to specify where they should fire or, for especially flying and controllable units, move to without involving the unit ghost created by the game's built-in movement system which implies the unit is meant for the ground and not the air. The Thor is a perfect example of using SpecifiedTarget as a way for a player to control air units neatly. Just beware of how visually noisy the opaque lines can be.

Note: If you're potentially assigning fractional values to it, it's better to make them integers first.   If you assign it to say, 80.8 x, 30 z it will actually round up and target tile 81, but drops the visual marker on tile 80.

===== Examples =====
<code 4rpl>
SetUnitSpecifiedTarget(self V3(10 0 20))
</code>
<=[[4rpl:start| Index]]