Vbs2 Asi Manual

VBS2™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 maybe reproduced by any process (electronic or otherwise) without the express prior written permissionof Bohemia Interactive Australia Pty Ltd ("BIA").

1. ASI Overview

The VBS2 Application Scripting Interface (ASI) enables external applications to communicate with VBS2 via thepowerful VBS2 scripting language. The ASI is fully bidirectional, allowing externally compiled plug-ins to pass mes-sages into and receivemessages from VBS2.

The VBS2 scripting language contains hundreds of script commands that perform awide range of functions, frommanipulating AI entities through to defining user interfaces. VBS2 script is also very fast, and has naturallyevolved since the release of Bohemia Interactive’s first game engine in 2001.

The VBS2 ASI relies on a plug-in methodology, whereby a simple Dynamic Link Library (DLL) is compiled andplaced into theVBS2 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 from within VBS2 scripts, triggers or eventhandlers providingmaximum flex-ibility without the need for complex functions.

This document describes the VBS2 ASI and the requirements for plugin DLLs.

Image 1-1: ASI Overview

© 2012 Bohemia Interactive Australia Pty Ltd AllRights reserved - -

2. Implementation

The VBS2 ASI uses native C functions for the plugin interface and can therefore VBS2 plugins can be created inalmost 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 VBS2windows handle and the instance id. These handles can be used if the plugincreates 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 ispaused. It is therefore the responsibility of the plugin not to consume toomuch time per simulation step since thatwould 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 from within VBS2.

[VBS2 1.30] To improve the development time well working with DLLs with VBS2, two new script commandswere added. loadPlugins and unloadPlugins.

l LoadPluginswill attempt to Load the dlls located in the VBS2\Plugins folder.

l unLoadPluginswill unload all the loaded plugins in the VBS2\Plugins folder that are inmemory.

Please note, it is advised that if any threads are executing during the Unload Phase to terminate and exit on Proc-cess Dll Unattached.


3. Examples

To illustrate how the plugin system works the following example is provided. This example simply changes theovercast (cloud cover) value of the VBS2 simulation. Assume the following code is placed in VBSplugin.cpp:

#include <windows.h>#include "VBSPlugin.h"

// Command function declarationtypedef int (WINAPI * ExecuteCommandType)(const char *command, char *result, int resultLength);// Command function definitionExecuteCommandType ExecuteCommand = NULL;

The beginning of the plugin defines the type of the ExecuteCommandType and defines a function pointer calledExecuteCommand to store the callback function passed from VBS2 during the RegisterCommandFnc:

VBSPLUGIN_EXPORT void WINAPI RegisterCommandFnc(void *executeCommandFnc){

ExecuteCommand = (ExecuteCommandType)executeCommandFnc;}

The following code shows how executeCommandFnc gets stored as ExecuteCommandwhich is used to invokescript 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 VBS2CommandReference 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 from a trigger, a VBS2 script (.sqf or .sqs file) or a scripted eventhandler (via theaddEventHandler 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 stringvalue 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)


{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 exampleswere created using wxWidgets which can be downloaded from: http://www.wxwidgets.org/ (link opens in newbrowser window)

The examples were written in Visual Studio 2005 but it should be possible to compile them in different envi-ronments.

Note: Weapon JitterIf the user is experiencing odd behaviour for example with the script command SetWeaponDirection and theweapon is jittering back and forward this is due to the engine calling the script commands out of sync. Toremove the weapon jitter prior to VBS2 Version Build Number: 5936 it is advised to use the Spawn command toexecute each script command via the DLL plugin.For users of VBS2 with Build Number equal or greater than 5936 use OnSimulationStep. Script commandsexecuted within OnSimulationStep are executed in sync with the game internal script engine and do not requirethe 'spawn' command to be used.


http://www.wxwidgets.org/

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 wewill respond to your querywith urgency.

[email protected]

The BIA VBS2 support forums are located at:

https://forums.bisimulations.com/

The VBS2website contains a range of media and handouts relating to VBS2:

http://www.bisimulations.com/

The BI Community Wiki is themain repository of knowledge pertaining to the BI Game Engine:

http://community.bistudio.com


http://www.bisimulations.com/support

mailto:[email protected]

https://forums.bisimulations.com/

http://www.bisimulations.com/

http://community.bistudio.com/

Vbs2 Asi Manual

Documents

Transcript of Vbs2 Asi Manual