This is an old revision of the document!
⇐ Index
Available in version 1.3 and later.
GetUnits(<-unitType <-startPos <-range <-isSquare <-is3D <-requireLOS <-enemyState <-builtState <-imperviousState) ->units
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 GetUnitsInRange is this API takes a 'unitType' parameter. By specifying a unitType, less units are searched over resulting in potentially higher performance. Furthermore, GetUnits can search for any units regardless of whether they occupy space, so units that are in flight can be found this way as well.
GetUnits takes a unit type and from that it will internally find all units of that type. It then enumerates those units and checks if they are in range and if they match the state filters. So GetUnits can be used to find any unit (air, map, or neither). This method can be more performant than GetUnitsInRange if the unit being searched is not found in large quantities on the map.
Note: 2D square search is currently broken and will find all units as long as they are close enough on X-axis, disregarding the Z-axis. Do not use this combination of parameters.
Note: The units “ern” and “pterosaur” will be picked up by a search looking for non-enemy built non-impervious units. If you need to avoid picking up those see if GetUnitsInRange is a more appropriate method (it doesn't pick up units in the air). If not, you may have to manually clean those from the list.
For short range searches refer to the unit search analysis to see how the different parameters interact with finding units in a short range.
"" ->unitType 10 ->cellX 15 ->cellZ 20 ->range false ->isSquare true ->is3D true ->requireLOS 2 ->enemyState 1 ->builtState 1 ->imperviousState GetTerrain(<-cellX <-cellZ) 1 + ->terrain GetUnits(<-unitType V3(<-cellX <-terrain <-cellZ) <-range <-isSquare <-is3D <-requireLOS <-enemyState <-builtState <-imperviousState) ->units