Differences

This shows you the differences between two versions of the page.

--- 4rpl:commands:getunits [2021/01/21 23:18] – created virgilw
+++ 4rpl:commands:getunits [2025/02/14 14:57] (current) – external edit 127.0.0.1
@@ Line 7: / Line 7: @@
 ===== 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.\\
-  * **unitType:** a string indicating the unit type to return. If empty string (""), then all units are searched.\\
-  * **startPos:** a V3 (vector3) indicating the point to search outwards from.\\
+  ? unitType:
-  * **range:** a floating point number that is the maximum distance from startPos.\\
+  : a string indicating the [[unit types|unit type]]((Unit Type can also be the GUID of a CMOD)) to return. If empty string (""), then all units are searched.
-  * **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). \\
+  ? startPos:
-  * **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.\\
+  : a V3 (vector3) indicating the point to search outwards from.
-  * **requireLOS:** a boolean indicating if terrain line of sight is required.\\
+  ? range:
-  * **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.\\
+  : a floating point number that is the maximum distance from startPos.
-  * **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.\\
+  ? isSquare:
-  * **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.\\
+  : 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). :!: __Bug__: if isSquare is true, then the startPos vector will ignore the Z-value.
+  ? 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.
+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.
 ===== Examples =====
@@ Line 32: / Line 44: @@
 GetTerrain(<-cellX <-cellZ) 1 + ->terrain
-GetUnitsInRange(<-unitType V3(<-cellX <-terrain <-cellZ) <-range <-isSquare <-is3D <-requireLOS <-enemyState <-builtState <-imperviousState) ->units
+GetUnits(<-unitType V3(<-cellX <-terrain <-cellZ) <-range <-isSquare <-is3D <-requireLOS <-enemyState <-builtState <-imperviousState) ->units
 </code>
+=== Notes ===
+  ** The difference between this API and [[GetUnitsInRange]] is this API takes a 'unitType' parameter.  By specifying a unitType, fewer 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.
+  * 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.
+  * 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.
+=== See Also ===
+  * [[GetUnitsInRange]]
 <=[[4rpl:start| Index]]

Knuckle Cracker Wiki

User Tools

Site Tools

Differences

Page Tools