⇐ 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 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). 1)
- 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
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