Differences

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

--- 4rpl:commands:getunitsinrange [2021/01/08 16:01] – external edit 127.0.0.1
+++ 4rpl:commands:getunitsinrange [2025/02/14 14:57] (current) – external edit 127.0.0.1
@@ Line 6: / Line 6: @@
 ===== Description =====
-Returns list of units in range of a startPos. The returned list is sorted so that the first item in the list is the closest.\\
+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.
-startPos is a V3 (vector3) indicating the point to search outwards from.\\
-range is a floating point number that is the maximum distance from startPos.\\
+:!: **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. \\
-isSquare is 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)\\
+Whether a custom unit occupies space can be controlled through the CMOD Settings: **Settings > Basic > "occupies land"**.
-is3D is 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 is a boolean indicating if terrain line of sight is required.\\
+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.
-enemyState is 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 is 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 is 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.\\
+  ? 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>
 ->cellX
-->cellY
+->cellZ
 ->range
-false -> isSquare
+false ->isSquare
 true ->is3D
 true ->requireLOS
@@ Line 27: / Line 60: @@
 ->builtState
 ->imperviousState
-GetTerrain(<-cellX <-cellY) 1 + ->terrain
+GetTerrain(<-cellX <-cellZ) 1 + ->terrain
-GetUnitsInRange( V3(<-cellX <-terrain <-cellY) <-range <-isSquare <-is3D <-requireLOS <-enemyState <-builtState <-imperviousState) ->units
+GetUnitsInRange( V3(<-cellX <-terrain <-cellZ) <-range <-isSquare <-is3D <-requireLOS <-enemyState <-builtState <-imperviousState) ->units
 </code>
+=== See Also ===
+  * [[GetUnits]]
 <=[[4rpl:start| Index]]

Knuckle Cracker Wiki

User Tools

Site Tools

Differences

Page Tools