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

====== FindUnitEnemy ======
FindUnitEnemy(<-unit <-deepest <-firePriority) ->cellZ ->cellX

===== Description =====
Finds creeper and mesh within range of a unit. The range is specified on the unit (along with other line of sight options).
   * Deepest is a boolean. If true, then the deepest creeper will be found. If false the nearest creeper will be found. \\
   * FirePriority is either 0 or 1. If 0, then creeper has priority. If 1 then mesh has priority. \\
The returned cell coordinate is the cell of the found creeper or mesh. A value of -1 is returned for each returned int if no enemy is found in range. \\
Note: When deepest is specified this routine runs the same code as a mortar. When nearest, the same code as a cannon. That means that
firePriority is interpreted differently in each case. For deepest (the mortar) firepriority chooses between targeting creeper or mesh (it picks one and ignores the other).
For nearest (the cannon) firePriority will find either if the other (creeper or mesh) is not present.

If the unit can move, you'll want to use [[4rpl:commands:refreshunitloscache|RefreshUnitLosCache]] after it has finished moving to properly calculate its new line of sight to make sure it can target properly.
===== Performance =====
This API is performance expensive when many custom units call it. There for, it would be utmost wise to not call FindUnitEnemy more than absolutely necessary within a unit's script.\\
As to be expected, the larger the range of the unit, the more expensive this API becomes.\\
A performance efficient example is provided. Units with longer range should have a higher upper and lower bound in [[4rpl:commands:randint|RandInt]].
===== Examples =====
<code 4rpl>
FindUnitEnemy(self true 0) ->cellZ ->cellX

</code>
<code 4rpl>
if(GetTimer0 eq0) #We are aloud to find a target.
	FindUnitEnemy(self true 0) ->tCellZ ->tCellX
	if(<-tCellX eq(-1))
		RandInt(30 60) SetTimer0 
		#The randInt ensures multiple of this unit don't all call FindUnitEnemy at the same time,
		#(which would cause the game to stutter every time they all used FindUnitEnemy).
	else
		@aimAndShoot
	endif
endif
</code>
<=[[4rpl:start| Index]]