Position And Proximity Function Reference

Position And Proximity Function Reference

Source-verified 2026-06-21 against then-current master cf2a6d6a4; current origin/master is 0139a346, so recheck cited paths before current-head claims. Paths relative to Missions/[55-2hc]warfarev2_073v48co.chernarus/. Arma 2 OA 1.64.

This page catalogs the shared helper family that picks random positions, finds nearby objects or towns, checks build/service ranges and counts nearby enemy presence. It complements Spawn Primitive Function Reference and Waypoint Helper Function Reference: those pages cover how units/vehicles/waypoints are created, while this page covers the position and proximity helpers they often depend on.

Function Registry

Helper	Compile name(s)	Source	Contract
Common_GetRandomPosition.sqf	GetRandomPosition; WFBE_CO_FNC_GetRandomPosition	Common/Init/Init_Common.sqf:36, Common/Init/Init_Common.sqf:125; behavior Common/Functions/Common_GetRandomPosition.sqf:16-23	Returns a random non-water position around an object or position.
Common_GetPositionFrom.sqf	GetPositionFrom	Common/Init/Init_Common.sqf:35; behavior Common/Functions/Common_GetPositionFrom.sqf:3-11	Returns a polar offset from a position/object, using either a numeric direction or a direction toward another object/position.
Common_PlaceNear.sqf	PlaceNear	Common/Init/Init_Common.sqf:71; behavior Common/Functions/Common_PlaceNear.sqf:3-34	Moves an object to a random radius around a point, optionally delegating the final placement to PlaceSafe.
Common_PlaceSafe.sqf	PlaceSafe	Common/Init/Init_Common.sqf:72; behavior Common/Functions/Common_PlaceSafe.sqf:4-28	Moves an object to the first nearby candidate that is not water and not close to building/vehicle obstacles.
Common_GetEmptyPosition.sqf	WFBE_CO_FNC_GetEmptyPosition	Common/Init/Init_Common.sqf:123; behavior Common/Functions/Common_GetEmptyPosition.sqf:10-24	Returns a random isFlatEmpty position inside a square around the input.
Common_GetSafePlace.sqf	GetSafePlace	Common/Init/Init_Common.sqf:39; behavior Common/Functions/Common_GetSafePlace.sqf:4-27	Returns a nearby safe position, or [] when its 30-probe search finds none.
Common_SortByDistance.sqf	SortByDistance; WFBE_CO_FNC_SortByDistance	Common/Init/Init_Common.sqf:82, Common/Init/Init_Common.sqf:152; behavior Common/Functions/Common_SortByDistance.sqf:10-30	Returns a copied list sorted nearest-to-farthest from the reference object/position.
Common_GetClosestEntity*.sqf	WFBE_CO_FNC_GetClosestEntity through WFBE_CO_FNC_GetClosestEntity4	Common/Init/Init_Common.sqf:117-120; behavior Common/Functions/Common_GetClosestEntity.sqf:10-17, Common/Functions/Common_GetClosestEntity2.sqf:13-17, Common/Functions/Common_GetClosestEntity3.sqf:13-17, Common/Functions/Common_GetClosestEntity4.sqf:13-17	Returns the nearest object in a list, with variants that cap the accepted distance by base-area constants.
Town closest helpers	GetClosestLocation; GetClosestLocationBySide; GetClosestFriendlyLocation	Common/Init/Init_Common.sqf:25-27; behavior Common/Functions/Common_GetClosestLocation.sqf:3-5, Common/Functions/Common_GetClosestLocationBySide.sqf:3-21, Common/Functions/Common_GetClosestFriendlyTown.sqf:3-12	Find nearest town objects from the global towns array, with side-owned or non-side-owned filters. Note: WFBE_CO_FNC_GetClosestEnemyLocation was removed from master (zero call sites; compile line replaced with comment at Init_Common.sqf:125; source file deleted).
Area/range helpers	BuildingInRange; GetHostilesInArea; WFBE_CO_FNC_GetAreaEnemiesCount; GetUnitsBelowHeight	Common/Init/Init_Common.sqf:18, Common/Init/Init_Common.sqf:33, Common/Init/Init_Common.sqf:64, Common/Init/Init_Common.sqf:114; behavior Common/Functions/Common_BuildingInRange.sqf:2-16, Common/Functions/Common_GetHostilesInArea.sqf:2-18, Common/Functions/Common_GetAreaEnemiesCount.sqf:11-20, Common/Functions/Common_GetUnitsBelowHeight.sqf:3-11	Build/service range checks, nearby hostile counts and height-filtered unit lists.

Placement Helpers

Helper	Signature	Behavior	Edge to preserve
GetRandomPosition	[_positionOrObject, _minRadius, _maxRadius] Call GetRandomPosition or Call WFBE_CO_FNC_GetRandomPosition	Converts objects to getPos, pads 2D positions with z = 0, chooses a random direction, chooses radius random (_maxRadius - _minRadius) + _minRadius, and returns the offset position.	The water-retry loop has no iteration cap; it keeps resampling while surfaceIsWater _position is true (Common/Functions/Common_GetRandomPosition.sqf:16-21).
GetPositionFrom	[_positionOrObject, _distance, _directionOrTarget] Call GetPositionFrom	Converts non-array origins with Position, accepts scalar directions directly, otherwise computes direction through GetDirTo, then returns a same-Z offset using sin/cos.	Non-scalar direction values must be valid for GetDirTo; the helper does no null/type validation beyond the scalar check (Common/Functions/Common_GetPositionFrom.sqf:3-11).
PlaceNear	[_object, _position, _minRadius, _maxRadius, _faceAway, _randomDirection, _placeSafe] Call PlaceNear	Defaults _faceAway = true, _randomDirection = true, _placeSafe = false; picks random direction/radius; either setPoses the object at z + 0.5 or calls PlaceSafe with a safe radius equal to half the spread and minimum 5.	_randomDirection is applied before _faceAway, but _faceAway then overwrites direction based on the final object position away from the center (Common/Functions/Common_PlaceNear.sqf:8-15, Common/Functions/Common_PlaceNear.sqf:20-33).
PlaceSafe	[_object, _position, _radius?] Call PlaceSafe	Defaults _radius = 35, tries up to 30 candidate positions, rejects water, nearestObjects buildings within 15 m and nearEntities building/car/tank/air objects within 7 m, then sets position and downward velocity.	The search rotates by 36 degrees per failed probe, expands radius by 25 after probe 15, and falls back to the original position if no safe candidate is found (Common/Functions/Common_PlaceSafe.sqf:4-28).
GetEmptyPosition	[_positionOrObject, _radius] Call WFBE_CO_FNC_GetEmptyPosition	Converts object inputs to getPos, starts with fallback [x+5,y+5,0], then makes up to 1000 random square samples and accepts the first isFlatEmpty [15,0,2,10,0,false,objNull] result.	This returns the fallback offset if all 1000 samples fail; it does not return objNull or [] (Common/Functions/Common_GetEmptyPosition.sqf:10-24).
GetSafePlace	[_position, _radius?] Call GetSafePlace	Uses the same 30-probe obstacle/water search pattern as PlaceSafe, but returns a position instead of moving an object.	Unlike PlaceSafe, failure returns []; there is no original-position fallback (Common/Functions/Common_GetSafePlace.sqf:4-27).
SortByDistance	[_reference, _objects] Call SortByDistance or Call WFBE_CO_FNC_SortByDistance	Copies the input array, repeatedly finds the nearest remaining entry by distance, appends it to _sorted, removes it with a sentinel marker, and returns the sorted copy.	The nested loop is O(n^2); keep it away from large hot-loop lists unless the caller's cadence is bounded (Common/Functions/Common_SortByDistance.sqf:10-30).

Closest-Entity Helpers

Helper	Distance seed / filter	Return	Primary use
WFBE_CO_FNC_GetClosestEntity	Starts with _distance = 100000; any nearer object wins.	objNull if the list is empty, otherwise the nearest object.	General UI, respawn, service, construction, ZetaCargo and town/patrol targeting use this broad helper (Common/Functions/Common_GetClosestEntity.sqf:10-17; examples at Client/GUI/GUI_RespawnMenu.sqf:52, Client/GUI/GUI_Menu_Service.sqf:225, Server/FSM/server_patrols.sqf:49).
WFBE_CO_FNC_GetClosestEntity2	Starts with WFBE_C_BASE_AREA_RANGE + WFBE_C_BASE_HQ_BUILD_RANGE.	Only returns an object inside that base-area plus HQ-build radius; otherwise objNull.	Build preview/base-area checks in client init and CoIn (Common/Functions/Common_GetClosestEntity2.sqf:13-17; Client/Init/Init_Client.sqf:625, Client/Module/CoIn/coin_interface.sqf:257).
WFBE_CO_FNC_GetClosestEntity3	Starts with WFBE_C_BASE_PROTECTION_RANGE.	Only returns an object inside base-protection range; otherwise objNull.	Enemy-base protection preview check (Common/Functions/Common_GetClosestEntity3.sqf:13-17; Client/Init/Init_Client.sqf:712).
WFBE_CO_FNC_GetClosestEntity4	Starts with WFBE_C_BASE_DEFENSE_MANNING_RANGE.	Only returns an object inside defense-manning range; otherwise objNull.	Stationary defense construction area selection (Common/Functions/Common_GetClosestEntity4.sqf:13-17; Server/Construction/Construction_StationaryDefense.sqf:14).

Town And Area Helpers

Helper	Signature	Behavior	Caller notes
GetClosestLocation	[_object] Call GetClosestLocation	Calls WFBE_CO_FNC_GetClosestEntity over the global towns array.	Used for building/sale chat text and respawn-camp lookup (Common/Functions/Common_GetClosestLocation.sqf:3-5; Client/PVFunctions/LocalizeMessage.sqf:51-52; Common/Functions/Common_GetRespawnCamps.sqf:14).
GetClosestLocationBySide	[_object, _side, _cvar?] Call GetClosestLocationBySide	Builds towns - (_side Call GetSideTowns), sorts by distance, and either returns the nearest non-owned town or the nearest sorted town whose _cvar variable is true.	The helper finds towns not held by _side; do not describe it as enemy-only without checking neutral/resistance ownership in the caller (Common/Functions/Common_GetClosestLocationBySide.sqf:3-18; Client/Functions/Client_TaskSystem.sqf:36).
GetClosestFriendlyLocation	[] Call GetClosestFriendlyLocation	Ignores parameters, gets (side player) Call GetSideTowns, sorts them from player, and returns the first one.	The compile name says "location", but the file is Common_GetClosestFriendlyTown.sqf and the origin is hardcoded to player (Common/Functions/Common_GetClosestFriendlyTown.sqf:3-12; Common/Init/Init_Common.sqf:27).
WFBE_CO_FNC_GetClosestEnemyLocation	Removed from master (zero call sites). Compile deleted from Common/Init/Init_Common.sqf; source file absent from Chernarus Common/Functions. Still present in Modded_Missions (lingor/eden/Napf).	—	—
BuildingInRange	[_buildingType, _buildings, _range, _side, _unit] Call BuildingInRange	Resolves structures through GetFactories, picks the closest result with WFBE_CO_FNC_GetClosestEntity, and returns objNull if the closest structure is farther than _range.	Used by the action FSM for barracks, gear, light, heavy, aircraft, service and command-center range flags, and by stationary-defense manning near barracks (Common/Functions/Common_BuildingInRange.sqf:2-16; Client/FSM/updateavailableactions.fsm:157-180; Server/Construction/Construction_StationaryDefense.sqf:106).
GetHostilesInArea	[_object, _sideOrSides, _within?] Call GetHostilesInArea	Defaults radius to 50, scans nearEntities [["Man","Car","Motorcycle","Tank","Air"], _within], then counts either every side in an array or a single side.	Respawn-camp eligibility passes enemy side(s) and minimum range through this helper (Common/Functions/Common_GetHostilesInArea.sqf:2-18; Common/Functions/Common_GetRespawnCamps.sqf:27, Common/Functions/Common_GetRespawnCamps.sqf:50, Common/Functions/Common_GetRespawnCamps.sqf:79).
WFBE_CO_FNC_GetAreaEnemiesCount	[_unitsOrObjects, _friendlySide, _ignoredSides?] Call WFBE_CO_FNC_GetAreaEnemiesCount	Counts sides from [west, east, resistance, sideEnemy] - [_friendlySide] - _ignoredSides using countSide.	Town AI uses it after its own detection/filtering stage, so the helper counts sides in a provided list rather than scanning the world itself (Common/Functions/Common_GetAreaEnemiesCount.sqf:11-20; Server/FSM/server_town_ai.sqf:77).
GetUnitsBelowHeight	[_units, _height, _min?] Call GetUnitsBelowHeight	Returns units whose getPos Z value is below _height and at or above _min; default _min = -10.	It is compiled as a short global; treat it as a height filter until a caller gives it more specific runtime semantics (Common/Functions/Common_GetUnitsBelowHeight.sqf:3-11; Common/Init/Init_Common.sqf:64).

Live Caller Map

Flow	Helpers	Source
Town AI and side patrol spawn placement	WFBE_CO_FNC_GetRandomPosition followed by WFBE_CO_FNC_GetEmptyPosition.	Server/FSM/server_town_ai.sqf:136-140; Server/FSM/server_patrols.sqf:20-21; Common/Functions/Common_RunSidePatrol.sqf:18-19
AI attack path waypoint scattering	WFBE_CO_FNC_SortByDistance chooses nodes/camps, then WFBE_CO_FNC_GetRandomPosition scatters MOVE/SAD waypoints around them.	Server/Functions/Server_AI_SetTownAttackPath.sqf:35-39, Server/Functions/Server_AI_SetTownAttackPath.sqf:58-95
Factory and defense spawn offsets	GetPositionFrom computes offsets from factory/defense headings before spawn.	Server/Functions/Server_BuyUnit.sqf:32; Client/Functions/Client_BuildUnit.sqf:164; Server/Functions/Server_HandleDefense.sqf:27
Start vehicles around HQ	PlaceNear places startup vehicles around the side HQ with safe placement enabled.	Server/Init/Init_Server.sqf:418, Server/Init/Init_Server.sqf:432, Server/Init/Init_Server.sqf:449
Respawn and disconnect fallback positions	GetRandomPosition scatters respawn positions; disconnect fallback first chooses closest respawn structure with WFBE_CO_FNC_GetClosestEntity.	Client/Functions/Client_OnRespawnHandler.sqf:32; Server/Functions/Server_OnPlayerDisconnected.sqf:120-122; Server/AI/AI_SquadRespawn.sqf:88-98; Server/AI/AI_AdvancedRespawn.sqf:102-113
Build/action UI range flags	BuildingInRange is the action-FSM gate for barracks, gear, factories, service points and command centers.	Client/FSM/updateavailableactions.fsm:157-180, Client/FSM/updateavailableactions.fsm:197
Fast travel and unstuck-style relocation	PlaceSafe moves grouped units or vehicles near chosen destinations.	Client/GUI/GUI_Menu.sqf:123-134; Client/GUI/GUI_Menu_Tactical.sqf:448; Server/AI/AI_TLWPHandler.sqs:27

Safe Change Rules

Rule	Why
Keep the short-global and WFBE_CO_FNC_* aliases in sync when changing shared helpers.	GetRandomPosition, SortByDistance and several closest/range helpers are compiled under mixed legacy and namespaced names (Common/Init/Init_Common.sqf:35-39, Common/Init/Init_Common.sqf:82, Common/Init/Init_Common.sqf:117-125, Common/Init/Init_Common.sqf:152).
Do not put GetRandomPosition, WaypointPatrol water-avoidance or SortByDistance over large unbounded lists in hot loops without a cap.	GetRandomPosition retries water forever, WaypointPatrol pages document the same uncapped water-resample pattern, and SortByDistance uses a nested nearest-search loop (Common/Functions/Common_GetRandomPosition.sqf:21; Common/Functions/Common_SortByDistance.sqf:14-28; Waypoint Helper Function Reference).
Use the right closest-entity variant for base checks.	Entity variants 2, 3 and 4 are not generic aliases: they hard-code base-area/HQ-build, base-protection and defense-manning ranges respectively (Common/Functions/Common_GetClosestEntity2.sqf:14; Common/Functions/Common_GetClosestEntity3.sqf:14; Common/Functions/Common_GetClosestEntity4.sqf:14).
Treat GetClosestLocationBySide as "not owned by this side" unless the caller separately filters hostility.	Its candidate set is towns - ((_side) Call GetSideTowns), which can include neutral or resistance-held towns depending on current map state (Common/Functions/Common_GetClosestLocationBySide.sqf:7).
Smoke placement changes in both Chernarus source and maintained Vanilla after propagation.	Town AI, patrol, respawn, build, fast-travel and start-vehicle callers are spread across server, client and common paths, and Chernarus remains the source mission propagated through LoadoutManager (Server/FSM/server_town_ai.sqf:136-140; Client/Functions/Client_OnRespawnHandler.sqf:32; Server/Init/Init_Server.sqf:418; Tools And Build Workflow).

Continue Reading

Previous: Function and module index | Next: Spawn primitive function reference

Related: Waypoint helper function reference | Construction and CoIn systems atlas | Server gameplay runtime atlas