VBS1 Functions

From Bohemia Interactive Community
(Redirected from VBS Functions)
Jump to: navigation, search

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