BIS fnc findSafePos: Difference between revisions

Latest revision as of 23:11, 20 November 2023

1.00

1.50

1.00

0.50

Hover & click on the images for description

Description

Description:: This function generates position on a map according to several given parameters (see diagram).

Diagram

The position pos will be generated inside an area which resides between minDist and maxDist from the given center. If objDist is also specified, the position will be selected objDist away from nearest terrain object. If maxGrad > 0 then the position will be also checked for how flat the area around is within objDist radius. The function can additionally be instructed to generate position specifically on water or land (waterMode) or on a shoreline (shoreMode). The shoreLine param will be ignored if position is not requested specifically on land.

Additionally, generated position could be checked against the list of blacklisted positions blacklistPos. If search for suitable position failed, defaultPos position will be used. The format for defaultPos is array with 2 positions: [posOnLand, posOnWater].
Execution:: call
Groups:: Positions

Syntax

Syntax:

[center, minDist, maxDist, objDist, waterMode, maxGrad, shoreMode, blacklistPos, defaultPos] call BIS_fnc_findSafePos

Parameters:

center: (Optional, default []) center position. Can be one of:

Array - position in format Position2D or Position3D
Object - object which position will be used
Nothing - when passing empty array [] or nothing, the world's "safePositionAnchor" entry will be used

minDist: Number - (Optional, default 0) minimum distance from the center position

maxDist: Number - (Optional, default -1) maximum distance from the center position. If -1, the world's "safePositionRadius" entry will be used

objDist: Number - (Optional, default 0) minimum distance from the resulting position to the center of nearest object. Specifying quite large distance here will slow the function and might often fail to find suitable position. Recommended value: 0..10

waterMode: Number - (Optional, default 0) water mode. Can be one of:

0 - cannot be in water
1 - can either be in water or not
2 - must be in water

maxGrad: Number - (Optional, default 0) maximum terrain gradient (hill steepness). A quite small non-zero value could result in failure to find suitable position. Recommended: 0.1+

shoreMode: Number - (Optional, default 0) shore mode. Can be one of:

0 - does not have to be at a shore
1 - must be at a shore

blacklistPos: Array - (Optional, default []) list of blacklisted areas in format [area1, area2, area3... areaN]. Can be one of:

Array - in format [topLeftCorner, bottomRightCorner] - top and bottom coordinates of blacklisted area
Object - trigger area
String - marker area
Location - location
Array - array in format [center, distance] or [center, a, b, angle, rect] or [center, a, b, angle, rect, height]

defaultPos: Array - (Optional, default []) default position when no position is found. Array format is [landPosition, seaPosition], where:

landPosition: Array - in format [x,y] or [x,y,z] - default position on land
seaPosition: Array - in format [x,y] or [x,y,z] - default position on water

Return Value:

Array - in format [x,y] on success. When position cannot be found at all, default map center position is returned, which will be in format [x,y,0]

Examples

Example 1:: Find position minimum 1m from from player but not further than 150m, not closer than 3m to any other object, not in the water, maximum gradient of 20, not on the shoreline:
private _pos = [player, 1, 150, 3, 0, 20, 0] call BIS_fnc_findSafePos;
Example 2:: private _pos = [getPos player, 2000, 5000, 1, 0, 0.7, 0, [], [getPos player, getPos player]] call BIS_fnc_findSafePos;
Example 3:: private _pos = [[], 0, 1000] call BIS_fnc_findSafePos;

Additional Information

See also:: BIS_fnc_randomPosTrigger BIS_fnc_randomPos

Notes

: Report bugs on the Feedback Tracker and/or discuss them on the Arma Discord or on the Forums.
Only post proven facts here! Add Note

Killzone_Kid - c: Posted on Mar 15, 2017 - 19:30 (UTC)
: To make sure position is not inside a building, increase distance to nearest object param.

AgentRev - c: Posted on Sep 24, 2021 - 22:23 (UTC)
: If objDist > 0, this function will unfortunately treat all roads and trails seen on the map as obstacles to avoid, due to its unfiltered usage of nearestTerrainObjects.

@@ Line 1: / Line 1: @@
+{{RV|type=function
-{{Function|= Comments
+|game1= arma2
-____________________________________________________________________________________________
+|version1= 1.00
-| arma2 |= Game name
+|game2= arma2oa
+|version2= 1.50
-|1.00|= Game version
+|game3= tkoh
-____________________________________________________________________________________________
+|version3= 1.00
-| This function generates position on a map according to several given parameters (see diagram):<br><br>
+|game4= arma3
-[[Image:bis_fnc_findsafepos.jpg|800px]]
+|version4= 0.50
-<br>
-The position '''pos''' will be generated inside an area which resides between '''minDist''' and '''maxDist''' from the given '''center'''. If '''objDist''' is also specified, the position will be selected '''objDist''' away from nearest object. If '''maxGrad''' > 0 then the position will be also checked for how flat the area around is within '''objDist''' radius. The function can additionally be instructed to generate position specifically on water or land ('''waterMode''') or on a shoreline ('''shoreMode'''). The '''shoreLine''' param will be ignored if position is requested on water.<br><br>
+|gr1= Positions
+|descr= This function generates position on a map according to several given parameters (see diagram).
+[[File:bis_fnc_findsafepos.jpg|600px|thumb|Diagram]]
+The position '''pos''' will be generated inside an area which resides between '''minDist''' and '''maxDist''' from the given '''center'''. If '''objDist''' is also specified, the position will be selected '''objDist''' away from nearest terrain object. If '''maxGrad''' > 0 then the position will be also checked for how flat the area around is within '''objDist''' radius. The function can additionally be instructed to generate position specifically on water or land ('''waterMode''') or on a shoreline ('''shoreMode'''). The '''shoreLine''' param will be ignored if position is not requested specifically on land.<br><br>
 Additionally, generated position could be checked against the list of blacklisted positions '''blacklistPos'''. If search for suitable position failed, '''defaultPos''' position will be used. The format for '''defaultPos''' is array with 2 positions: [posOnLand, posOnWater].
-<br><br>
-<pre>
-/*
-	File: findSafePos.sqf
-	Description:
+|s1= [center, minDist, maxDist, objDist, waterMode, maxGrad, shoreMode, blacklistPos, defaultPos] call [[BIS_fnc_findSafePos]]
-	Function to retrieve and dynamic position in the world according to several parameters.
+|p1= center: (Optional, default <sqf inline>[]</sqf>) center position. Can be one of:
+* [[Array]] - position in format [[Position#Introduction|Position2D]] or [[Position#Introduction|Position3D]]
+* [[Object]] - object which position will be used
+* [[Nothing]] - when passing empty array [] or nothing, the world's "safePositionAnchor" entry will be used
+|p2= minDist: [[Number]] - (Optional, default 0) minimum distance from the center position
+|p3= maxDist: [[Number]] - (Optional, default -1) maximum distance from the center position. If -1, the world's "safePositionRadius" entry will be used
+|p4= objDist: [[Number]] - (Optional, default 0) minimum distance from the resulting position to the center of nearest object. Specifying quite large distance here will slow the function and might often fail to find suitable position. Recommended value: 0..10
-	Parameter(s):
+|p5= waterMode: [[Number]] - (Optional, default 0) water mode. Can be one of:
-	_this select 0: center position (Array)
+* 0 - cannot be in water
-						Note: passing [] (empty Array), the world's safePositionAnchor entry will be used.
+* 1 - can either be in water or not
-	_this select 1: minimum distance from the center position (Number)
+* 2 - must be in water
-	_this select 2: maximum distance from the center position (Number)
-						Note: passing -1, the world's safePositionRadius entry will be used.
-	_this select 3: minimum distance from the nearest object (Number)
-	_this select 4: water mode (Number)
-: cannot be in water
-: can either be in water or not
-: must be in water
-	_this select 5: maximum terrain gradient (average altitude difference in meters - Number)
-	_this select 6: shore mode (Number):
-: does not have to be at a shore
-: must be at a shore
-	_this select 7: (optional) blacklist (Array of Arrays):
-						(_this select 7) select X: Top-left and bottom-right coordinates of blacklisted area (Array)
-	_this select 8: (optional) default positions (Array of Arrays):
-						(_this select 8) select 0: default position on land (Array)
-						(_this select 8) select 1: default position on water (Array)
-	Returns:
-	Coordinate array with a position solution.
-	TODO:
-	* Maybe allow passing several combinations of position, min and max dist ... so that you can
-	avoid several things?
-	* Interpretation of minDist / maxDist is wrong. It's not true distance that is used. Too bad?
-*/
-</pre><small>''(Placeholder description extracted from the function header by [[BIS_fnc_exportFunctionsToWiki]])''</small> |= Description
+|p6= maxGrad: [[Number]] - (Optional, default 0) maximum terrain gradient (hill steepness). A quite small non-zero value could result in failure to find suitable position. Recommended: 0.1+
-____________________________________________________________________________________________
-| <!-- [] call [[BIS_fnc_findSafePos]]; --> |= Syntax
+|p7= shoreMode: [[Number]] - (Optional, default 0) shore mode. Can be one of:
+* 0 - does not have to be at a shore
+* 1 - must be at a shore
-|p1= |= Parameter 1
+|p8= blacklistPos: [[Array]] - (Optional, default <sqf inline>[]</sqf>) list of blacklisted areas in format [area1, area2, area3... areaN]. Can be one of:
+* [[Array]] - in format [topLeftCorner, bottomRightCorner] - top and bottom coordinates of blacklisted area
+* [[Object]] - trigger area
+* [[String]] - marker area
+* [[Location]] - location
+* [[Array]] - array in format [center, distance] or [center, a, b, angle, rect] or [center, a, b, angle, rect, height]
-| |= Return value
+|p9= defaultPos: [[Array]] - (Optional, default <sqf inline>[]</sqf>) default position when no position is found. Array format is [landPosition, seaPosition], where:
-____________________________________________________________________________________________
+* landPosition: [[Array]] - in format [x,y] or [x,y,z] - default position on land
+* seaPosition: [[Array]] - in format [x,y] or [x,y,z] - default position on water
-|x1= <code>kRandSpawnPos = [kdestPos, 1, 150, 3, 0, 20, 0] call BIS_fnc_findSafePos;</code> |=
+|r1= [[Array]] - in format [x,y] on success. When position cannot be found at all, default map center position is returned, which will be in format [x,y,0]
-____________________________________________________________________________________________
-| |= See also
+|x1= Find position minimum 1m from from player but not further than 150m, not closer than 3m to any other object, not in the water, maximum gradient of 20, not on the shoreline:
+<sqf>private _pos = [player, 1, 150, 3, 0, 20, 0] call BIS_fnc_findSafePos;</sqf>
+|x2= <sqf>private _pos = [getPos player, 2000, 5000, 1, 0, 0.7, 0, [], [getPos player, getPos player]] call BIS_fnc_findSafePos;</sqf>
+|x3= <sqf>private _pos = [[], 0, 1000] call BIS_fnc_findSafePos;</sqf>
+|seealso= [[BIS_fnc_randomPosTrigger]] [[BIS_fnc_randomPos]]
 }}
-<h3 style="display:none">Notes</h3>
+{{Note
-<dl class="command_description">
+|user= Killzone_Kid
-<!-- Note Section BEGIN -->
+|timestamp= 20170315193000
-Example 1 would generate a position as follows:
+|text= To make sure position is not inside a building, increase distance to nearest object param.
-Minimal 1 meter from "kdestPos" but not further than 150, not closer than 3 meters to any other object, not in the water, maximum gradient of 20 meters, not on the shoreline. And safe the generated position in "kRandSpawnPos". --[[User:Kamaradski|Kamaradski]] ([[User talk:Kamaradski|talk]]) 13:56, 10 March 2015 (CET)
+}}
--->
-<!-- Note Section END -->
-</dl>
-<h3 style="display:none">Bottom Section</h3>
+{{Note
-[[Category:Function Group: Misc|{{uc:findSafePos}}]]
+|user= AgentRev
-[[Category:Functions|{{uc:findSafePos}}]]
+|timestamp= 20210924222305
-[[Category:{{Name|arma2}}: Functions|{{uc:findSafePos}}]]
+|text= If ''objDist'' &gt; 0, this function will unfortunately treat all roads and trails seen on the map as obstacles to avoid, due to its unfiltered usage of [[nearestTerrainObjects]].
-[[Category:{{Name|arma2oa}}: Functions|{{uc:findSafePos}}]]
+}}
-[[Category:{{Name|tkoh}}: Functions|{{uc:findSafePos}}]]
-[[Category:{{Name|arma3}}: Functions|{{uc:findSafePos}}]]