Application Scripting Interface

Version 2.02.17
Interface Control Document
(last edit: 19 Jul 2012)
This manual is protected by Australian and international copyright laws. No part of this manual may
be reproduced by any process (electronic or otherwise) without the express prior written permission
of Bohemia Interactive Australia Pty Ltd ("BIA").
1. ASI Overview
The VBS2 Application Scripting Interface (ASI) enables external applications to communicate with VBS2 via the
powerful VBS2 scripting language. The ASI is fully bidirectional, allowing externally compiled plug-ins to pass mes-
sages into and receive messages fromVBS2.
The VBS2 scripting language contains hundreds of script commands that performa wide range of functions, from
manipulating AI entities through to defining user interfaces. VBS2 script is also very fast, and has naturally
evolved since the release of Bohemia Interactives first game engine in 2001.
The VBS2 ASI relies on a plug-in methodology, whereby a simple Dynamic Link Library (DLL) is compiled and
placed into the VBS2 plugins folder.
VBS2 ASI operation is relatively simple. Each render frame, VBS2 calls the plugin function OnSimulationStep,
which can invoke any number of VBS2 script commands. In return, a special script command named Plu-
ginFunction can be called directly fromwithin VBS2 scripts, triggers or eventhandlers providing maximumflex-
ibility without the need for complex functions.
This document describes the VBS2 ASI and the requirements for plugin DLLs.
Image 1-1: ASIOverview
2012 Bohemia Interactive Australia Pty Ltd All Rights reserved - Page 2 -
2. Implementation
The VBS2 ASI uses native C functions for the plugin interface and can therefore VBS2 plugins can be created in
almost any programming language.
The list below describes the functions which need to be exported by the DLL:
#define VBSPLUGIN_EXPORT __declspec(dllexport)
VBSPLUGIN_EXPORT void WINAPI RegisterHWND(void *hwnd, void *hins);
VBSPLUGIN_EXPORT void WINAPI RegisterCommandFnc(void *executeCommandFnc);
VBSPLUGIN_EXPORT void WINAPI OnSimulationStep(float deltaT);
VBSPLUGIN_EXPORT const char* WINAPI PluginFunction(const char *input);VBSPLUGIN_EXPORT
These functions and their parameters are described below.
VBSPLUGIN_EXPORT void WINAPI RegisterCommandFnc(void *executeCommandFnc)
RegisterCommandFnc passes the function which the DLL has to call in order to execute VBS2 scripting com-
mands. The executeCommandFnc is of the following type.
typedef int (WINAPI * ExecuteCommandType)(const char *command, char *result, int resultLength);
VBSPLUGIN_EXPORT void WINAPI RegisterHWND(void *hwnd, void *hins);
RegisterHWND passes the VBS2 windows handle and the instance id. These handles can be used if the plugin
creates a windows graphical user interface.
VBSPLUGIN_EXPORT void WINAPI OnSimulationStep(float deltaT)
In each render frame VBS2 calls the function OnSimulationStep for every registered plugin. The deltaT param-
eter passes the time in seconds since the last call. During the execution of this function the VBS2 simulation is
paused. It is therefore the responsibility of the plugin not to consume too much time per simulation step since that
would result in a low frame rate for VBS2.
VBSPLUGIN_EXPORT const char* WINAPI PluginFunction(const char *input)
PluginFunction is the function that gets called by executing the script call PluginFunction fromwithin VBS2.
[VBS2 1.30] To improve the development time well working with DLLs with VBS2, two new script commands
were added. loadPlugins and unloadPlugins.
l LoadPlugins will attempt to Load the dlls located in the VBS2\Plugins folder.
l unLoadPlugins will unload all the loaded plugins in the VBS2\Plugins folder that are in memory.
Please note, it is advised that if any threads are executing during the Unload Phase to terminate and exit on Proc-
cess Dll Unattached.
2012 Bohemia Interactive Australia Pty Ltd All Rights reserved - Page 3 -
3. Examples
To illustrate how the plugin systemworks the following example is provided. This example simply changes the
overcast (cloud cover) value of the VBS2 simulation. Assume the following code is placed in VBSplugin.cpp:
#include <windows.h>
#include "VBSPlugin.h"
// Command function declaration
typedef int (WINAPI * ExecuteCommandType)(const char *command, char *result, int resultLength);
// Command function definition
ExecuteCommandType ExecuteCommand = NULL;
The beginning of the plugin defines the type of the ExecuteCommandType and defines a function pointer called
ExecuteCommand to store the callback function passed fromVBS2 during the RegisterCommandFnc:
VBSPLUGIN_EXPORT void WINAPI RegisterCommandFnc(void *executeCommandFnc)
{
ExecuteCommand = (ExecuteCommandType)executeCommandFnc;
}
The following code shows how executeCommandFnc gets stored as ExecuteCommand which is used to invoke
script commands in VBS2:
VBSPLUGIN_EXPORT void WINAPI OnSimulationStep(float deltaT)
{
ExecuteCommand("0 setOvercast 1", NULL, 0);
}
This code calls the required VBS2 script command(s). In this example the sky overcast value is set to 1 every sim-
ulation step (see the VBS2 Command Reference for a listing of all script commands).
The pluginFunction is called each time VBS2 executes the script command pluginFunction. This scripting func-
tion can be called at any time froma trigger, a VBS2 script (.sqf or .sqs file) or a scripted eventhandler (via the
addEventHandler script command).
_
ret = pluginFunction [PLUGINNAME, text or value]
PLUGINNAME above is the name of the plugin without the .dll extension.
In the above example the string text or value would be passed as const char *input to the PluginFunction.
This information can then be parsed and additional ExecuteCommand functions invoked before returning a string
value to the VBS2 script via the variable _ret. Note: The return value has to be an array.
VBSPLUGIN_EXPORT const char* WINAPI PluginFunction(const char *input)
{
static const char result[]="[10, \"test\", 12.4]";
return result;
}
The final part of the simple example plugin consists of a standard DllMain function:
BOOL WINAPI DllMain(HINSTANCE hDll, DWORD fdwReason, LPVOID lpvReserved)
2012 Bohemia Interactive Australia Pty Ltd All Rights reserved - Page 4 -
{
switch(fdwReason)
{
case DLL_PROCESS_ATTACH:
OutputDebugString("Called DllMain with DLL_PROCESS_ATTACH\n");
break;
case DLL_PROCESS_DETACH:
OutputDebugString("Called DllMain with DLL_PROCESS_DETACH\n");
break;
case DLL_THREAD_ATTACH:
OutputDebugString("Called DllMain with DLL_THREAD_ATTACH\n");
break;
case DLL_THREAD_DETACH:
OutputDebugString("Called DllMain with DLL_THREAD_DETACH\n");
break;
}
return TRUE;
}
Additional examples can be found in the VBS2_ASI archive shipped with VBS2. The two windows GUI examples
were created using wxWidgets which can be downloaded from: http://www.wxwidgets.org/ (link opens in new
browser window)
The examples were written in Visual Studio 2005 but it should be possible to compile themin different envi-
ronments.
Note: Weapon Jitter
If the user is experiencing odd behaviour for example with the script command SetWeaponDirection and the
weapon is jittering back and forward this is due to the engine calling the script commands out of sync. To
remove the weapon jitter prior to VBS2 Version Build Number: 5936 it is advised to use the Spawn command to
execute each script command via the DLL plugin.
For users of VBS2 with Build Number equal or greater than 5936 use OnSimulationStep. Script commands
executed within OnSimulationStep are executed in sync with the game internal script engine and do not require
the 'spawn' command to be used.
2012 Bohemia Interactive Australia Pty Ltd All Rights reserved - Page 5 -
4. Support
The VBS2 Support Resource webpage can be found at:
http://www.bisimulations.com/support
For any type of assistance with VBS2, please use the following support email and we will respond to your query
with urgency.
support@bisimulations.com
The BIA VBS2 support forums are located at:
https://forums.bisimulations.com/
The VBS2 website contains a range of media and handouts relating to VBS2:
http://www.bisimulations.com/
The BI Community Wiki is the main repository of knowledge pertaining to the BI Game Engine:
http://community.bistudio.com
2012 Bohemia Interactive Australia Pty Ltd All Rights reserved - Page 6 -