{"name":"BIS_fnc_findSafePos","operator":null,"title":"BIS fnc findSafePos","type":"function","url":"https://community.bistudio.com/wiki/BIS_fnc_findSafePos","revid":349938,"updated":"2023-11-20T22:11:20Z","groups":["Positions"],"status":"ok","replaced_by":[],"games":[{"game":"arma2","name":"Arma 2","version":"1.00"},{"game":"arma2oa","name":"Arma 2: Operation Arrowhead","version":"1.50"},{"game":"tkoh","name":"Take On Helicopters","version":"1.00"},{"game":"arma3","name":"Arma 3","version":"0.50"}],"since":{"game":"arma2","name":"Arma 2","version":"1.00"},"arma3_since":"0.50","branch":null,"locality":{"argument":null,"effect":null,"server_exec":false},"exec":null,"description":"This function generates position on a map according to several given parameters (see diagram).\n\nThe 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.\n\nAdditionally, 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].","syntaxes":[{"syntax":"[center, minDist, maxDist, objDist, waterMode, maxGrad, shoreMode, blacklistPos, defaultPos] call BIS_fnc_findSafePos","since":null,"effect":null,"exec":null,"params":[{"name":"center","type":null,"optional":true,"default":"`[]`","description":"center position. Can be one of:\n- Array - position in format Position2D or Position3D\n- Object - object which position will be used\n- Nothing - when passing empty array [] or nothing, the world's \"safePositionAnchor\" entry will be used","types":[],"since":null,"text":"center: (Optional, default `[]`) center position. Can be one of:\n- Array - position in format Position2D or Position3D\n- Object - object which position will be used\n- Nothing - when passing empty array [] or nothing, the world's \"safePositionAnchor\" entry will be used"},{"name":"minDist","type":"Number","optional":true,"default":"0","description":"minimum distance from the center position","types":["Number"],"since":null,"text":"minDist: Number - (Optional, default 0) minimum distance from the center position"},{"name":"maxDist","type":"Number","optional":true,"default":"-1","description":"maximum distance from the center position. If -1, the world's \"safePositionRadius\" entry will be used","types":["Number"],"since":null,"text":"maxDist: Number - (Optional, default -1) maximum distance from the center position. If -1, the world's \"safePositionRadius\" entry will be used"},{"name":"objDist","type":"Number","optional":true,"default":"0","description":"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","types":["Number"],"since":null,"text":"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"},{"name":"waterMode","type":"Number","optional":true,"default":"0","description":"water mode. Can be one of:\n- 0 - cannot be in water\n- 1 - can either be in water or not\n- 2 - must be in water","types":["Number"],"since":null,"text":"waterMode: Number - (Optional, default 0) water mode. Can be one of:\n- 0 - cannot be in water\n- 1 - can either be in water or not\n- 2 - must be in water"},{"name":"maxGrad","type":"Number","optional":true,"default":"0","description":"maximum terrain gradient (hill steepness). A quite small non-zero value could result in failure to find suitable position. Recommended: 0.1+","types":["Number"],"since":null,"text":"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+"},{"name":"shoreMode","type":"Number","optional":true,"default":"0","description":"shore mode. Can be one of:\n- 0 - does not have to be at a shore\n- 1 - must be at a shore","types":["Number"],"since":null,"text":"shoreMode: Number - (Optional, default 0) shore mode. Can be one of:\n- 0 - does not have to be at a shore\n- 1 - must be at a shore"},{"name":"blacklistPos","type":"Array","optional":true,"default":"`[]`","description":"list of blacklisted areas in format [area1, area2, area3... areaN]. Can be one of:\n- Array - in format [topLeftCorner, bottomRightCorner] - top and bottom coordinates of blacklisted area\n- Object - trigger area\n- String - marker area\n- Location - location\n- Array - array in format [center, distance] or [center, a, b, angle, rect] or [center, a, b, angle, rect, height]","types":["Array"],"since":null,"text":"blacklistPos: Array - (Optional, default `[]`) list of blacklisted areas in format [area1, area2, area3... areaN]. Can be one of:\n- Array - in format [topLeftCorner, bottomRightCorner] - top and bottom coordinates of blacklisted area\n- Object - trigger area\n- String - marker area\n- Location - location\n- Array - array in format [center, distance] or [center, a, b, angle, rect] or [center, a, b, angle, rect, height]"},{"name":"defaultPos","type":"Array","optional":true,"default":"`[]`","description":"default position when no position is found. Array format is [landPosition, seaPosition], where:\n- landPosition: Array - in format [x,y] or [x,y,z] - default position on land\n- seaPosition: Array - in format [x,y] or [x,y,z] - default position on water","types":["Array"],"since":null,"text":"defaultPos: Array - (Optional, default `[]`) default position when no position is found. Array format is [landPosition, seaPosition], where:\n- landPosition: Array - in format [x,y] or [x,y,z] - default position on land\n- seaPosition: Array - in format [x,y] or [x,y,z] - default position on water"}],"returns":{"type":"Array","types":["Array"],"description":"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]","text":"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":[{"text":"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:\n\n```sqf\nprivate _pos = [player, 1, 150, 3, 0, 20, 0] call BIS_fnc_findSafePos;\n```","code":["private _pos = [player, 1, 150, 3, 0, 20, 0] call BIS_fnc_findSafePos;"]},{"text":"```sqf\nprivate _pos = [getPos player, 2000, 5000, 1, 0, 0.7, 0, [], [getPos player, getPos player]] call BIS_fnc_findSafePos;\n```","code":["private _pos = [getPos player, 2000, 5000, 1, 0, 0.7, 0, [], [getPos player, getPos player]] call BIS_fnc_findSafePos;"]},{"text":"```sqf\nprivate _pos = [[], 0, 1000] call BIS_fnc_findSafePos;\n```","code":["private _pos = [[], 0, 1000] call BIS_fnc_findSafePos;"]}],"multiplayer":null,"problems":null,"aliases":[],"see_also":["BIS_fnc_randomPosTrigger","BIS_fnc_randomPos"],"notes":[{"user":"Killzone_Kid","date":"2017-03-15T19:30:00Z","text":"To make sure position is not inside a building, increase distance to nearest object param."},{"user":"AgentRev","date":"2021-09-24T22:23:05Z","text":"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."}],"categories":["Arma 2: Functions","Arma 2: New Functions","Arma 2: Operation Arrowhead: Functions","Arma 3: Functions","Function Group: Positions","Functions","Introduced with Arma 2 version 1.00","Take On Helicopters: Functions"],"docblock":null,"filled_from_docblock":[]}