VBS1 Functions
From Bohemia Interactive Community
Introduction
A number of scripting functions are preloaded by the VBS1 core. Each function is stored and loaded from a global variable. To use these functions, use the following syntax in your scripts:
_returnvalue = [parameters] call functionName
VBS1 Functions in VBS2
The VBS1 functions are not included in VBS2 by default; the new function library should be used instead.
However, to help backwards-compatibility with VBS1 scripts, it is possible to manually load the VBS1 functions in a mission. To do this, you need to create a file called "init.sqf" in your mission directory, and include this line at the top of the file:
#include "\vbs2\headers\vbs1_compatibility.hpp"
The VBS1 header only needs to be added to init.sqf, not any other script. Note that the new VBS2 function library includes all of the VBS1 functions (and many more). You should only use the above header for missions using scripts made for VBS1.
Functions List
VBS_is_null
Returns true if variable has not been initialised.
Operand types:
is null: Boolean variable: Any Value (but not an Array)
Example: is null? = [variable] call VBS_is_null
VBS_is_scalar
Returns true if array has not been initialised.
Operand types:
is null: Boolean array: Array
Example: is null? = [array] call VBS_is_scalar
VBS_getRandom
Returns a random number between number1 and number2.
Operand types:
number1: Number number2: Number Return Value: Number
Example: myrndnum = [number1,number2] call VBS_getRandom
VBS_randomElement
Randomly returns an element out of array.
Operand types:
element: Any Value (a reference to a single element of array) array: Array
Example: element = array call VBS_randomElement
VBS_randomIndex
Randomly returns an index of array, index is a number representing an element of the Array.
Operand types:
index: Number array: Array
Example: index = array call VBS_randomIndex
VBS_getDirPos
Returns the direction in degrees from position1 to position2.
Operand types:
position1: Array position2: Array Return Value: Number
Example: direction = [position1,position2] call VBS_getDirPos
VBS_getDirRelPos
Returns the relative direction in degrees from unit to position. A position to the right of unit would be at a relative direction of 90 degrees, for example.
Operand types:
unit: Object position: Array Return Value: Number
Example: direction = [unit,position] call VBS_getDirRelPos
VBS_inAng
Returns true if position lies within the sector defined by center position, center angle of sector and sector width. Use this function to determine if a position lies within a certain angle from another position (ie the center position).
Operand types: center position: Array center angle of sector: Number (degrees) sector width: Number (degrees) position: Array Return Value: Boolean
Example:
insector = [center position,center angle of sector,sector width,position] call VBS_inAng
VBS_distancePos
Returns the 2D distance in metres from position1 to position2.
distance = [position1,position2] call VBS_distancePos
Operand types:
position1: Array position2: Array Return Value: Number
VBS_distancePosSqr
Returns the squared 2D distance in metres from position1 to position2. Working in the squared domain is a little faster than using the VBS_distancePos function.
distance = [position1,position2] call VBS_distancePosSqr
Operand types:
position1: Array position2: Array Return Value: Number
VBS_distancePos3D
Returns the 3D distance in metres from position1 to position2. This is a very slow function, made obsolete by the getposasl command (use the two functions below instead of this one).
distance = [position1,position2,logic1,logic2] call VBS_distancePos3D
Operand types:
position1: Array position2: Array logic1: Game Logic logic2: Game Logic Return Value: Number
VBS_distance3D
Returns the 3D distance in metres from position1 to position2. Ensure that both positions are height above sea level (use getposasl).
distance = [position1,position2] call VBS_distance3D
Operand types:
position1: Array position2: Array Return Value: Number
VBS_distance3DSqr
Returns the 3D distance in metres from position1 to position2. Working in the squared domain is a little faster than using the VBS_distance3D function. Ensure that both positions are height above sea level (use getposasl).
Operand types: position1: Array position2: Array Return Value: Number
Example distance = [position1,position2] call VBS_distance3DSqr
VBS_roundn
Returns Number rounded to the nearest whole number.
Operand types: number: Number Return Value: [[Number
Example: myRoundNumber = number call VBS_roundn
VBS_echo
Takes array and converts it to a string seperated by "\n\n". Generally used in debugging (ie hint format["%1",my_array call VBS_echo]).
Operand types: array: Array Return Value: String
Example: message = array call VBS_echo
VBS_getSide
Returns a number for a particular side.
- 0 for units of side WEST
- 1 for units of side EAST
- 2 for units of side RESISTANCE
- 3 for units of side CIVILIAN.
Units of side ENEMY are returned as per their initial side.
Operand types: unit: Object Return Value: Number Example: sideindex = unit call VBS_getSide
VBS_vDiff
Returns a vector that is the difference between vector1 and vector2.
Operand types: vector1: Array vector2: Array Return Value: Array
Example: difference = [vector1,vector2] call VBS_vDiff
VBS_vMag
Returns the magnitude of vector.
Operand types: vector: Array Return Value: Number
Example: magnitude = vector call VBS_vMag
VBS_vUnit
Returns the unitvector of vector.
Operand types: vector: Array Return Value: Array
Example: unitvector = vector call VBS_vUnit
VBS_vVelUnit
Returns a unit vector that 'points' from vector1 to vector2. This is a very useful function, as it can be used with the velocity command to move an object from one position to another (ie vector1 to vector2) - ensure both positions are found using getposasl.
Operand types: vector1: Array vector2: Array Return Value: array
Example: resultant-vector = [vector1,vector2] call VBS_vVelUnit
VBS_vMultiply
Returns vector multiplied by scale.
Operand types: vector: Array scale>: Number Return Value: Array
Example: resultant-vector = [vector,scale] call VBS_vMultiply
VBS_vAdd
Returns vector1 added to vector2.
Operand types: vector1: Array vector2: Array Return Value: Array
Example: resultant-vector = [vector1,vector2] call VBS_vAdd
