Category:Scripting Functions VBS2

From Bohemia Interactive Community

Introduction

A function library has been introduced in v1.19. The function library adds a range of additional functions for use in scripts. These functions are not scripting commands, but rather are sub-routines created from the existing script commands.

The function library supersedes the old VBS1 Functions, although it is possible to re-load those functions for backwards compatibility with VBS1 scripts (see the VBS1 Functions article for more info).

See also: Category:Scripting Commands VBS2

[edit]

Usage

You can only use the function library in .sqf scripts. This means any script that is loaded using the preprocessFile command, or run via the execVM command. The functions can not be used in the editor, or in .sqs scripts.

The following line must be added to the top of every script in which you want to use functions from the library:

#include "\vbs2\headers\function_library.hpp"

To use a specific function, you use the following syntax:

_returnvalue = [parameters] call functionName;

Important note: function names are case sensitive. Incorrect casing will result in no value being returned, and no errors being displayed.

[edit]

How It Works

The below info does not have to be understood in order to use the function library. It is just written for those wanting to know the specifics of how the function library works.

The function library doesn't store functions in global variables, as was done in VBS1. Storing a constant value in a variable is unnecessary and would be a waste of resources, especially when there are dozens of functions available.

Instead, functions are simply "stored" in a defined constant. The constants are all listed in the header file, which is then included at the top of the script. To be more specific, the header file simply lists a number of #defines (one for each function), which look something like the following:

#define fn_vbs_somefunction compile preprocessfile '\vbs2\somewhere\somefunction.sqf'

The preprocessor does a find/replace operation on scripts before they are run, which replaces the small, easy to use word "fn_vbs_somefunction", with the longer, working syntax to the right of it. Example:

    //The line looks like this when written in a script:
_ret = [player, 5] call fn_vbs_somefunction;

    //The line looks like this after the script is preprocessed and loaded:
_ret = [player, 5] call compile preprocessfile '\vbs2\somewhere\somefunction.sqf';

Sqs scripts and code written in the editor are not preprocessed, so they can not use the function library. #defines are also case sensitive, unlike global variables.