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

====== GetUnitsInRange ======
GetUnitsInRange(<-startPos <-range <-isSquare <-is3D <-requireLOS <-enemyState <-builtState <-imperviousState) ->units

===== Description =====
Returns list of units in range of a given position. The returned list is sorted so that the first item in the list is the closest.

:!: **Note:** The difference between this API and [[GetUnits]] is that this method performs a search around the specified coordinates for any units that leave a footprint on the map by occupying space. This can be more performant than GetUnits in situations where a smaller area is being searched, but it comes with a downside that it won't find flying units, **or land units that are currently moving**. Units occupy space as soon as they begin descending at their target location, they do not have to have touched the ground yet. If you need a method to find units regardless of whether or not they are occupying space, use GetUnits. \\
Whether a custom unit occupies space can be controlled through the CMOD Settings: **Settings > Basic > "occupies land"**.

For short range searches refer to the [[cw4:4rpl_unit_search_analysis|unit search analysis]] to see how the different parameters interact with finding units in a short range.


  ? startPos:
  : a [[V3]] (vector3) indicating the point to search outwards from.
  ? range:
  : a floating point number that is the maximum distance from startPos.
  ? isSquare:
  : a boolean. It means to check in a square rather than a circle around startPos. For 3D checks, the vertical displacement is also checked (so the range is effectivly a cube rather than a sphere). (( **Note:** When isSquare is true, the search will also not use the unit's exact position to see if they are in range, but rather their hitbox (footprint & height). If any part of the hitbox crosses into the square, it will be selected.)) 
  ? is3D:
  : a boolean. It determines if a true 3d distance is used for range, or if only the X and Z components (2D) distance calculation is used.
  ? requireLOS:
  : a boolean indicating if terrain line of sight is required. 
  ? enemyState:
  : an int (either 0,1,2). 
    ? 0 = 
    : ignore enemy status. 
    ? 1 = 
    : Only find units that are enemies. 
    ? 2 = 
    : Only find units that are not enemies. 
  ? builtState:
  : an int (either 0,1,2). 
    ? 0 = 
    : ignore built state. 
    ? 1 = 
    : Only find units that are built. 
    ? 2 = 
    : Only find units that are not built. 
  ? imperviousState:
  : an int (either 0,1,2). 
    ? 0 = 
    : ignore impervious state. 
    ? 1 = 
    : Only find units that are not impervious. 
    ? 2 = 
    : Only find units that are impervious. Things like ore deposits are impervious.

===== Examples =====
<code 4rpl>
10 ->cellX
15 ->cellZ
20 ->range
false ->isSquare
true ->is3D
true ->requireLOS
2 ->enemyState
1 ->builtState
1 ->imperviousState
GetTerrain(<-cellX <-cellZ) 1 + ->terrain

GetUnitsInRange( V3(<-cellX <-terrain <-cellZ) <-range <-isSquare <-is3D <-requireLOS <-enemyState <-builtState <-imperviousState) ->units
</code>

=== See Also ===
  * [[GetUnits]]
  
<=[[4rpl:start| Index]]