isFlatEmpty – Arma 3 command

Description

Checks given position against given filter params. Filter includes checks for:

If there are any objects closer than given distance from given position (in 2D)
If the area around position is flat enough to match given gradient
If the given position is over water or land
If the given position is over shore line The gradient seems to correlate with general hill steepness: 0.1 (10%) ~6°, 0.5 (50%) ~27°, 1.0 (100%) ~45°, etc.

Note
See also BIS_fnc_findSafePos.

Syntax

position isFlatEmpty [minDistance, mode, maxGradient, maxGradientRadius, overLandOrWater, shoreLine, ignoreObject]

Parameters:

position: PositionAGL
minDistance: Number - (Optional, default -1) minimum (2D) distance from other objects (range 0..50). -1 to ignore proximity check
mode: Number - (Optional, default -1) position check mode (ALWAYS USE DEFAULT VALUE)
maxGradient: Number - (Optional, default -1) maximum terrain steepness allowed. -1 to ignore
maxGradientRadius: Number - (Optional, default 1) how far to extend gradient check
overLandOrWater: Number - (Optional, default 0)
- 0: position cannot be over water
- 2: position cannot be over land
- -1 to ignore
shoreLine: Boolean - (Optional, default false)
- true: position is over shoreline (< ~25 m from water)
- false to ignore
ignoreObject: Object - (Optional, default objNull) object to ignore in proximity checks. objNull to ignore

Returns: Array - empty array [] if check failed or PositionASL if succeded. Resulting position will be original PositionAGL + getTerrainHeightASL

Examples

Example 1

Check if player position is over land:

_overLand = !(position player isFlatEmpty [-1, -1, -1, -1, 0, false] isEqualTo []);

Example 2

Check if player position is over shore line:

_overShore = !(position player isFlatEmpty  [-1, -1, -1, -1, 0, true] isEqualTo []);

Example 3

Check if player position is over water:

_overWater = !(position player isFlatEmpty  [-1, -1, -1, -1, 2, false] isEqualTo []);

Example 4

Check if no object is closer than 5m to player position:

_isEmpty = !(position player isFlatEmpty  [5, -1, -1, -1, -1, false, player] isEqualTo []);

Example 5

Check if area 10m around player position is relatively flat:

_isFlat = !(position player isFlatEmpty  [-1, -1, 0.3, 10, -1] isEqualTo []);

Example 6

Check if area 15m around player position is very flat and empty:

_isFlatEmpty = !(position player isFlatEmpty  [15, -1, 0.1, 15, -1, false, player] isEqualTo []);

Problems

Objects accounted for proximity check seem to be static objects. Nearby vehicles and units do not seem to affect the output
Given position will be magically transferred into given position + getTerrainHeightASL value
The second element must be -1 (≤ 0 really) at all times, otherwise command becomes unusable
The command might be a bit heavy on computations so avoid frequent and large area checks

Community notes

Killzone_Kid2016-04-24

When this command is instructed to check if area at given position is empty it takes into account the radius of the bounding sphere of surrounding objects. Because of this, the high voltage columns such as "Land_HighVoltageColumnWire_F" and such objects may appear extremely large to the calculations and the position will be rejected even if visually it doesn't look too bad. To avoid this, use findEmptyPosition command first to find guaranteed empty position, then pass the result to isFlatEmpty making sure you switched off proximity check by setting 1st param to -1. For example:

// Check if given position is flat and empty within 1m radius
[4274.66,12113,0.00139618] isFlatEmpty [1, -1, 0.1, 1, -1, false, objNull]; // []

The result suggests it is not flat and empty.

// Check if given position is flat within 1m radius
[4274.66,12113,0.00139618] isFlatEmpty [-1, -1, 0.1, 1, -1, false, objNull]; // [4274.66,12113,48.3209]

The result suggests it is.

// Check if given position is empty within 1m radius
[4274.66,12113,0.00139618] isFlatEmpty [1, -1, -1, -1, -1, false, objNull]; // []

The result suggests it is not empty. But the position is in the middle of a road and there is nothing within 1m but there is "Land_HighVoltageColumnWire_F" not far.

// Check if given position is empty within 1m radius ignoring nearest "Land_HighVoltageColumnWire_F"
[4274.66,12113,0.00139618] isFlatEmpty [1, -1, -1, 1, -1, false, nearestObject [[4274.66,12113,0.00139618], "Land_HighVoltageColumnWire_F"]]; // [4274.66,12113,48.3209]

The result now suggests it is empty. So instead of relying on internal proximity check we can combine both commands:

fnc_isFlatEmpty =
{
    params ["_pos", "_params"];
    _pos = _pos findEmptyPosition [0, _params select 0];
    if (_pos isEqualTo []) exitWith {[]};
    _params = +_params;
    _params set [0, -1];
    _pos = _pos isFlatEmpty _params;
    if (_pos isEqualTo []) exitWith {[]};
    _pos
};

// Test
[[4274.66,12113,0.00139618], [1, -1, 0.1, 1, -1, false, objNull]] call fnc_isFlatEmpty; // [4274.53,12113,48.3175]