Latest Updates 2014-01-28 and Base64

I had been spending a lot of time learning and exploring AngelScript. I won't be writing anymore AngelScript articles for Gamedev.net, but from time to time, I'll post blog entries on it.

These days, because of personal reasons of the other team members, Auxnet progress has slowed down a lot, but I hope to get back to it soon. While I wait for everyone to catch up, I've been experimenting with some new engine concepts. I've decided to build a little test engine currently code-named "Engine X" to try out the concepts. It'll be a multiplatform (Windows / Android) 2D tile-based engine that will use AngelScript as the scripting language. I'm not sure how much time I'll be able to devote to it though because it'll go on the back burner once things with Auxnet ramp up again.

I've got the base rendering and user input stuff working on Windows. Later I'll build it for Android. In the meantime, I've been working on adding support for a tile layer. I don't have time to make an editor so I'm going to use Tiled which can be found at mapeditor.org . I want to build a simple loader for it. The format is in XML so it's not overly complicated, but there was one thing that's new to me.

The tile data is stored in Base64. At first, I didn't know what this was so I decided to do a little research. Base64 is an encoding that takes data whether binary or text and encodes it using only 64 characters. This is useful when transmitting data over protocols that may alter the data. As it turns out, the pioneers of the Internet and email weren't forward thinking enough to think that more than 7-bits (thank you ASCII) would be needed for transmitting a text character. Base64 can also be used to store complex data inside things like XML. There are different forms of Base64, but they all work on the same general principle, It's used as a way to store binary data as plain text. It's not a complicated encoding. Basically you take three 8-bit bytes and break into four 6-bit units. The 6-bit units will be from 0-63. To make sure the values will be able to be transmitted without being garbled, the final character for each value is determined by the following table.

The above table is for Multipurpose Internet Mail Extensions (MIME). Other versions of Base64 use a similar table, but in some of them the characters used for values 62 and 63 are different. The above characters are good because they are supported by the majority of text encodings and aren't the same as any XML or HTML tags. For binary data to be converted into Base64, the number of bytes should be a multiple of three. If not, it should be padded with zeros. When this padding occurs, and special 65th character, '=', is used instead instead of the normal 0, 'A' character. This means '=' will only appear at the end if there was padding.

 Here's an example:

Now, I'll continue working on loading the map. Hope to have a working tiled-based rendering system within the next 7 days.

Programming By Example - Adding AngelScript to a Game Part 3

For Part 1: Programming By Example - Adding AngelScript to a Game Part 1
For Part 2: Programming By Example - Adding AngelScript to a Game Part 2
For Part 3: Programming By Example - Adding AngelScript to a Game Part 3

Introduction

This is part 3 of the article "Adding AngelScript to an Existing Game". In this series, I've been adding AngelScript to the XACTGame sample that can be found in the Direct X SDK. I hope to explain many of the needed concepts so others will be able to add scripting to their games.

AngelScript Concepts Covered

• Using Script Header Files
• Getting the Value of Script Global Variables in C++
• Exposing Different Interfaces
• Calling Script Functions with Parameters From C++

What will be Scripted
In the final part of this series, I'll use AngelScript to script much of the game logic inside of the XACTGame sample application. Here's a list of the functions that I'll script:

• void FireAmmo()
• void HandleAmmoAI( float fElapsedTime )
• void HandleDroidAI( float fElapsedTime )
• void CreateDroid()
• float GetDistFromWall( D3DXVECTOR3 P1, D3DXVECTOR3 P2, D3DXVECTOR3 P3, D3DXVECTOR3 N )
• void DroidPickNewDirection( int A )
• void DroidChooseNewTask( int A )
• void CheckForAmmoToDroidCollision( int A )
• void CheckForInterAmmoCollision( float fElapsedTime )
• void CheckForAmmoToWallCollision( int A )
• void CreateAmmo( int nIndex, D3DXVECTOR4 Pos, D3DXVECTOR4 Vel )

Of all of these functions, only the first four need to be accessed by C++. The others will only be called by other script functions. The code here is all runs while the game is being played. It's different from the InitApp() function that I scripted in part one. The InitApp function, also needed access to the camera and menu settings while these functions don't so instead of putting all of the script functions in one file, I'll divide it into two files--"initapp.as" and "gamelogic.as".

Using Script Header Files

Eventhough I use separate script files, there are some constants defined in "game.h" that I'd like to use in both files. AngelScript doesn't have built-in support for includes and can only parse scripts and doesn't have any functions to load files. However, if you remember from part 1, AngelScript has an optional add-on called Script Builder that can load files, handle includes and some C-sytle preprocessor directives, and removes meta data tags from the script before compilation. Now I will add the a new file "constants.as"

// constants.as
// This is an AngelScript File
//--------------------------------------------------------------------------------------
// Consts
//--------------------------------------------------------------------------------------

// Will carry over to C++ code if modified in script ----------------------------------------
const uint MAXANISOTROPY            = 8; // MAXANISOTROPY is the maximum anisotropy state value used when anisotropic filtering is enabled.
const float GROUND_ABSORBANCE       = 0.2f; // GROUND_ABSORBANCE is the percentage of the velocity absorbed by ground and walls when an ammo hits.
const float AMMO_ABSORBANCE         = 0.1f; // AMMO_ABSORBANCE is the percentage of the velocity absorbed by ammos when two collide.
const int MAX_AMMO                  = 10;  // MAX_AMMO is the maximum number of ammo that can exist in the world.
const int MAX_DROID                 = 50;
const uint DROID_HITPOINTS          = 20;
const float AMMO_SIZE               = 0.10f; // AMMO_SIZE is the diameter of the ball mesh in the world.
const float DROID_SIZE              = 0.5f;
const float DROID_MIN_HEIGHT        = 0.5f;
const float DROID_HEIGHT_FLUX       = 0.5f;
const uint DROID_TURN_AI_PERCENT    = 40;
const uint DROID_MOVE_AI_PERCENT    = 40;
const uint DROID_MOVE_TIME_MIN      = 2000;
const uint DROID_MOVE_TIME_FLUX     = 3000;
const uint DROID_CREATE_DELAY_FLUX  = 2500;
const float DROID_DEATH_SPEED       = 3.0f;
const float AUTOFIRE_DELAY          = 0.15f; // AUTOFIRE_DELAY is the period between two successive ammo firing.
const float CAMERA_SIZE             = 0.2f; // CAMERA_SIZE is used for clipping camera movement
const float GRAVITY                 = 3.0f; // GRAVITY defines the magnitude of the downward force applied to ammos.
const float DROID_VELOCITY          = 2.0f; // MIN_VOL_ADJUST is the minimum volume adjustment based on contact velocity.
const float BOUNCE_TRANSFER         = 0.8f; // BOUNCE_TRANSFER is the proportion of velocity transferred during a collision between 2 ammos.
const float BOUNCE_LOST             = 0.1f; // BOUNCE_LOST is the proportion of velocity lost during a collision between 2 ammos.
const float REST_THRESHOLD          = 0.005f; // REST_THRESHOLD is the energy below which the ball is flagged as laying on ground.  // It is defined as Gravity * Height_above_ground + 0.5 * Velocity * Velocity
const float PHYSICS_FRAMELENGTH     = 0.003f; // PHYSICS_FRAMELENGTH is the duration of a frame for physics handling when the graphics frame length is too long.

// Will not carry over to C++ code if modified in script ------------------------------------
const float PI                      = 3.14159f;

// MinBound and MaxBound are the bounding box representing the cell mesh.
const float GROUND_Y                = 3.0f; // -GROUND_Y is the Y coordinate of the ground.
const D3DXVECTOR3           g_MinBound( -6.0f, -GROUND_Y, -6.0f );
const D3DXVECTOR3           g_MaxBound( 6.0f, GROUND_Y, 6.0f );

Even though this file will be used as an AngelScript "header file", it doesn't need header guards. The Script Builder add-on will check for that automatically. Later when I want to include it inside my other AngelScript files, I can include it just as I would in C/C++.

// include common constant variable definitions
#include "constants.as"

Getting the Value of Script Global Variables in C++

You may have noticed in the 'constants.as' file, two comments one of which says, "Will carry over to C++ code if modified in script." The constants defined in 'constants.as' are the same as the ones defined in 'game.h'. It would be nice if I can change the values in 'constants.as' and have them carry over into the C++ code. This is possible in AngelScript. The asIScriptModule class contains the compiled script and it has methods that can be used to get the value stored in its global variables. To get a global variable from AngelScript, first we need to get the variables index. We can do this by calling one of the following methods: GetGlobalVarIndexByName() or GetGlobalVarIndexByDecl(). Once you have the index, you can retrieve a pointer to the variables memory location. I've written this short template function for retrieving a global variable from AngelScript. The function doesn't do any type checking; that's the responsibility of the programmer.

template <class t>
// returns -1 if not found
int GetGlobal(asIScriptModule *module, char *declaration, T &out_val)
{
 int index = module->GetGlobalVarIndexByDecl(declaration);
 if(index < 0) return -1;

 // get the variable from AngelScript and cast to our type
 T *var_ptr = (T *)module->GetAddressOfGlobalVar(index);

 // set the value
 out_val = *var_ptr;

 return 1;
}

From this, I wrote a class that will retrieve the values from AngelScript and provide functions to get the data. I'll store the class in the ScriptContextData struct and pass it to the functions that need it.

class CXACTGameScriptConstants
{
    public:
        void SetContantsFromScript(asIScriptModule *module)
        {
            int result;
            result = GetGlobal(module, "const uint MAXANISOTROPY", maxanisotropy); assert(result >= 0);
            result = GetGlobal(module, "const float GROUND_ABSORBANCE", ground_absorbance); assert(result >= 0);
            result = GetGlobal(module, "const float AMMO_ABSORBANCE", ammo_absorbance); assert(result >= 0);
            result = GetGlobal(module, "const int MAX_AMMO", max_ammo); assert(result >= 0);
            result = GetGlobal(module, "const int MAX_DROID", max_droid); assert(result >= 0);
            result = GetGlobal(module, "const uint DROID_HITPOINTS", droid_hitpoints); assert(result >= 0);
            result = GetGlobal(module, "const float AMMO_SIZE", ammo_size); assert(result >= 0);
            result = GetGlobal(module, "const float DROID_SIZE", droid_size); assert(result >= 0);
            result = GetGlobal(module, "const float DROID_MIN_HEIGHT", droid_min_height); assert(result >= 0);
            result = GetGlobal(module, "const float DROID_HEIGHT_FLUX", droid_height_flux); assert(result >= 0);
            result = GetGlobal(module, "const uint DROID_TURN_AI_PERCENT", droid_turn_ai_percent); assert(result >= 0);
            
            // Some parts ommitted because of length
            ....
        }

        unsigned int get_maxanisotropy() const { return maxanisotropy; }
        float get_ground_absorbance() const { return ground_absorbance; }
        float get_ammo_absorbance() const { return ammo_absorbance; }
        int get_max_ammo() const { return max_ammo; }
        int get_max_droid() const { return max_droid; }
        unsigned int get_droid_hitpoints() const { return droid_hitpoints; }
        float get_ammo_size() const { return ammo_size; }
        float get_droid_size() const { return droid_size; }
        float get_droid_min_height() const { return droid_min_height; }
        float get_droid_height_flux() const { return droid_height_flux; }
        unsigned int get_droid_turn_ai_percent() const { return droid_turn_ai_percent; }

        // Some parts ommitted because of length
        ....

    private:
        // helper function for getting global data from AngelScript
        template <class t>
        // returns -1 if not found
        int GetGlobal(asIScriptModule *module, char *declaration, T &out_val)
        {
            int index = module->GetGlobalVarIndexByDecl(declaration);
            if(index < 0) return -1;

            // get the variable from AngelScript and cast to our type
            T *var_ptr = (T *)module->GetAddressOfGlobalVar(index);

            // set the value
            out_val = *var_ptr;

            return 1;
        }

        unsigned int maxanisotropy;
        float ground_absorbance;
        float ammo_absorbance;
        int max_ammo;
        int max_droid;
        unsigned int droid_hitpoints;
        float ammo_size;
        float droid_size;
        float droid_min_height;
        float droid_height_flux;
        unsigned int droid_turn_ai_percent;
    
        // Some parts ommitted because of length
        ....
};

Exposing Different Interfaces

Now again, "initapp.as" and "gamelogic.as" don't need access to all of the same parts of the C++ interface. To limit access, AngelScript uses access mask. These are bit flags that we set when registering our interface and also when we loading our scripts. To simplify things, I'll use only two types.

const unsigned int ScriptInterfaceMask_SetupOnly = 0x01; // interface can only be called by modules with this mask
const unsigned int ScriptInterfaceMask_Gameplay  = 0x02; // interface can only be called by modules with this mask
const unsigned int ScriptInterfaceMask_All       = ScriptInterfaceMask_SetupOnly | ScriptInterfaceMask_Gameplay; // interface can only be called both modules types

To set the access mask for our interface, we use the SetDefaultAccessMask() method inside asIScriptEngine. To add this support, the following changes are needed to the RegisterGameInterface() function inside as_scripting.cpp

int RegisterGameInterface(asIScriptEngine *scriptengine)
{
 int result;

 // Set Acces Mask ---------------------------------------------------------------------
 scriptengine->SetDefaultAccessMask(ScriptInterfaceMask_All); 
 // Bindings made in this section are accessible to everything -------------------------

 // Register STD String (Needed to help me test my implementation)
 RegisterStdString(scriptengine);

 // Register Arrays
 RegisterScriptArray(scriptengine, true);

 // Register print function (Needed to help me test my implementation)
 result = scriptengine->RegisterGlobalFunction("void print(const string &in)", asFUNCTION(print), asCALL_CDECL);
 if(result < 0) return result;

 // Set Acces Mask ---------------------------------------------------------------------
 scriptengine->SetDefaultAccessMask(ScriptInterfaceMask_Gameplay); 
 // Bindings made in this section are accessible to game play related scripts ----------

 // Register enum GAME_MODE
 result = RegisterEnumGAME_MODE(scriptengine);
 if(result < 0) return result;

 result = RegisterD3DXMathFunctions(scriptengine);
 if(result < 0) return result;

 result = RegisterD3DXCOLOR(scriptengine);
 if(result < 0) return result;

 result = RegisterDROID_STATE(scriptengine);
 if(result < 0) return result;

 result = RegisterAMMO_STATE(scriptengine);
 if(result < 0) return result;

 result = RegisterGameStateInterface(scriptengine);
 if(result < 0) return result;

 result = RegisterAudioInterface(scriptengine);
 if(result < 0) return result;

 result = RegisterCameraInterface(scriptengine); // FireAmmo() needs to get the view
 if(result < 0) return result;

 // Set Acces Mask ---------------------------------------------------------------------
 scriptengine->SetDefaultAccessMask(ScriptInterfaceMask_SetupOnly); 
 // Bindings made in this section are accessible to setup related scripts --------------

 result = RegisterDialogInterface(scriptengine);

 return result;
}

The Script Builder add-on can only load one at a time module. A module can be made up of a collection of script files, but the functions in the module have same access mask. Since we want our modules to have different access masks we'll need to change the LoadScript() from part 1.

int LoadScript(asIScriptEngine *scriptengine, ScriptContextData &contextdata)
// Note in earlier articles I passed the Script Builder object as a reference, but this isn't
// needed as once the module has been created, the script builder object no longer has any use.
{
 int result;

 // The CScriptBuilder helper is an add-on that loads the file,
 // performs a pre-processing pass if necessary, and then tells
 // the engine to build a script module.
 CScriptBuilder builder;

 // load initapp.as into a module -----------------------------------------------------------------------------
 result = builder.StartNewModule(scriptengine, "InitAppModule"); 
 if( result < 0 ) 
 {
  // If the code fails here it is usually because there
  // is no more memory to allocate the module
  MessageBoxA(NULL, "Unrecoverable error while starting a new module.", "AngelScript Message", MB_OK);
  return result;
 }

 // set the modules access mask
 builder.GetModule()->SetAccessMask(ScriptInterfaceMask_All); // give init app full access

 // load the script
 result = builder.AddSectionFromFile("initapp.as");
 if( result < 0 ) 
 {
  // The builder wasn't able to load the file. Maybe the file
  // has been removed, or the wrong name was given, or some
  // preprocessing commands are incorrectly written.
  MessageBoxA(NULL,"Please correct the errors in the script and try again.", "AngelScript Message", MB_OK);
  return result;
 }
 result = builder.BuildModule();
 if( result < 0 ) 
 {
  // An error occurred. Instruct the script writer to fix the 
  // compilation errors that were listed in the output stream.
  MessageBoxA(NULL,"Please correct the errors in the script and try again.", "AngelScript Message", MB_OK);
  return result;
 }

 // load gamelogic.as into a module ----------------------------------------------------------------------
 result = builder.StartNewModule(scriptengine, "GameModule"); 
 if( result < 0 ) 
 {
  // If the code fails here it is usually because there
  // is no more memory to allocate the module
  MessageBoxA(NULL, "Unrecoverable error while starting a new module.", "AngelScript Message", MB_OK);
  return result;
 }

 // set the modules access mask
 builder.GetModule()->SetAccessMask(ScriptInterfaceMask_Gameplay); // only give gameplay access

 // load the script
 result = builder.AddSectionFromFile("gamelogic.as");
 if( result < 0 ) 
 {
  // The builder wasn't able to load the file. Maybe the file
  // has been removed, or the wrong name was given, or some
  // preprocessing commands are incorrectly written.
  MessageBoxA(NULL,"Please correct the errors in the script and try again.", "AngelScript Message", MB_OK);
  return result;
 }
 result = builder.BuildModule();
 if( result < 0 ) 
 {
  // An error occurred. Instruct the script writer to fix the 
  // compilation errors that were listed in the output stream.
  MessageBoxA(NULL,"Please correct the errors in the script and try again.", "AngelScript Message", MB_OK);
  return result;
 }

 ...
}

Calling Script Functions with Parameters From C++

Remember in part 1, I stored the AngelScript script function pointer for InitApp. I'll do the same with the new script function

// enumerations -------------------------------------------------------------
enum ScriptFunctionIDs
{
 Function_InitApp = 0,
 Function_FireAmmo,
 Function_HandleAmmoAI,
 Function_HandleDroidAI,
 Function_CreateDroid
};

const unsigned int max_script_functions = 5;

struct ScriptContextData
{
 asIScriptContext *ctx;
 asIScriptFunction *script_functions[max_script_functions];

 void ExecuteFunction(ScriptFunctionIDs func_id);
};

I've created a helper function for finding the script function and displaying a message if the script can't be found.

asIScriptFunction *GetScriptFunction(asIScriptModule *mod, char *declaration)
{
 asIScriptFunction *func = mod->GetFunctionByDecl(declaration);
 if(func == NULL)
 {
  MessageBoxA(NULL,"AngelScript Message - The script function missing. Please add it and try again.", declaration, MB_OK);
  return NULL;
 }
 return func;
}

Now with that function, I just need to add the following to the end of the LoadScript function.

// Find the function that is to be called. 
asIScriptModule *modInitApp = scriptengine->GetModule("InitAppModule");
contextdata.script_functions[Function_InitApp] = GetScriptFunction(modInitApp, "void InitApp()");
if( contextdata.script_functions[Function_InitApp] == 0 ) return -1;

asIScriptModule *modlogic = scriptengine->GetModule("GameModule");
contextdata.script_functions[Function_FireAmmo] = GetScriptFunction(modlogic, "void FireAmmo()");
if( contextdata.script_functions[Function_FireAmmo] == 0 ) return -1;

contextdata.script_functions[Function_HandleAmmoAI] = GetScriptFunction(modlogic, "void HandleAmmoAI( float fElapsedTime )");
if( contextdata.script_functions[Function_HandleAmmoAI] == 0 ) return -1;

contextdata.script_functions[Function_HandleDroidAI] = GetScriptFunction(modlogic, "void HandleDroidAI( float fElapsedTime )");
if( contextdata.script_functions[Function_HandleDroidAI] == 0 ) return -1;

contextdata.script_functions[Function_CreateDroid] = GetScriptFunction(modlogic, "void CreateDroid()");
if( contextdata.script_functions[Function_CreateDroid] == 0 ) return -1;

To call the scripts, I made an ExecuteFunction() which I created and put into the ScriptContextData structure. It takes a value from the ScriptFunctionIDs enum as a parameter. This worked well as the InitApp() function doesn't take any parameters, but now I want to support call script functions from C++ that have parameters. Executing scripts functions from C++ is a 4-step process. First, you should call Prepare() which will allow the script context to prepare the stack. Next, if there are parameters, the paremeters should be set. One of the following asIScriptContext methods can be used for primitive types:

 int SetArgDWord(int arg, asDWORD value);
 int SetArgQWord(int arg, asQWORD value);
 int SetArgFloat(int arg, float value);
 int SetArgDouble(int arg, double value);
 int SetArgByte(int arg, asBYTE value);
 int SetArgWord(int arg, asWORD value);

The 'arg' parameter is the index of the parameter in the functions paramter list. After the parameters have been set, you should call Execute(). Finally, to get the return value, use one of the following functions:

 asDWORD GetReturnDWord();
 asQWORD GetReturnQWord();
 float   GetReturnFloat();
 double  GetReturnDouble();
 asBYTE  GetReturnByte();
 asWORD  GetReturnWord();

To handle these changes in code, I'll divide the ExecuteFunction() into two separate methods--PrepareFunction() and ExecuteFunction(). If the function has paramters, one of the SetArg methods can be called between the prepare and execute calls.

int PrepareFunction(ScriptFunctionIDs func_id)
{
 // I'm no longer checking for a valid context here. It's up to the application writer to ensure 
 // that the context is valid before calling this
 return ctx->Prepare(script_functions[func_id]);
}

int ExecuteFunction()
{
 // I'm no longer checking for a valid context here. It's up to the application writer to ensure 
 // that the context is valid before calling this
 int result = ctx->Execute();
 if( result != asEXECUTION_FINISHED )
 {
  // The execution didn't complete as expected. Determine what happened.
  if( result == asEXECUTION_EXCEPTION )
  {
   // An exception occurred, let the script writer know what happened so it can be corrected.
   MessageBoxA(NULL, ctx->GetExceptionString(), "An exception occurred.", MB_OK);
   return -1;
  }
 }
 return result;
}

Converting the C++ code to AngelScript

All that's left to do is to convert the code from C++ to AngelScript. AngelScript and C++ have almost identical syntax so this isn't too much of a problem. When registering the C++ objects and bindings with AngelScript, I did change things. For example, to access the game state object, the C++ code directly access the g_GameState variable whereas in my bindings, I give limited through a namespace 'GAME_STATE'. Also, the DirectX math functions use pointers, but in my bindings, I use references. Here's an example of the FireAmmo()function in AngelScript:

void FireAmmo()
{
    // Check to see if there are already MAX_AMMO balls in the world.
    // Remove the oldest ammo to make room for the newest if necessary.
    double fOldest = GAME_STATE::AmmoQ[0].fTimeCreated;
    int nOldestIndex = 0;
    int nInactiveIndex = -1;
    for( int iAmmo = 0; iAmmo < MAX_AMMO; iAmmo++ )
    {
        if( !GAME_STATE::AmmoQ[iAmmo].bActive )
        {
            nInactiveIndex = iAmmo;
            break;
        }
        if( GAME_STATE::AmmoQ[iAmmo].fTimeCreated < fOldest )
        {
            fOldest = GAME_STATE::AmmoQ[iAmmo].fTimeCreated;
            nOldestIndex = iAmmo;
        }
    }

    if( nInactiveIndex < 0 )
    {
        GAME_STATE::AmmoQ[nOldestIndex].bActive = false;
        GAME_STATE::nAmmoCount--;
        nInactiveIndex = nOldestIndex;
    }

    int nNewAmmoIndex = nInactiveIndex;

    // Get inverse view matrix
    D3DXMATRIXA16 mInvView;
 float det = 0.0;
 D3DXMatrixInverse(mInvView, det, FirstPersonCamera::CameraGetViewMatrix());
    //D3DXMatrixInverse( &mInvView, NULL, g_Camera.GetViewMatrix() );

    // Compute initial velocity in world space from camera space
    D3DXVECTOR4 InitialVelocity( 0.0f, 0.0f, 6.0f, 0.0f );
 D3DXVec4Transform(InitialVelocity, InitialVelocity, mInvView);
    //D3DXVec4Transform( &InitialVelocity, &InitialVelocity, &mInvView );
    D3DXVECTOR4 InitialPosition( 0.0f, -0.15f, 0.0f, 1.0f );
 //D3DXVec4Transform(InitialPosition, InitialPosition, mInvView);
    D3DXVec4Transform( InitialPosition, InitialPosition, mInvView );

    AUDIO::PlayAudioCue(AUDIO::Cue_iAmmoFire);
 //PlayAudioCue( g_audioState.iAmmoFire );

    CreateAmmo( nNewAmmoIndex, InitialPosition, InitialVelocity );
}

AngelScript is almost like an extension to C++. This code is almost exactly like its C++ counterpart and because of the array add-on introduced in part 2 of this series, the arrays can be easily shared.

Results and Conclusion

The XACTGame sample runs almost exactly the same when using AngelScript to write some parts of it as opposed to coding the entire project in C++. The goal of this article was to show how to add AngelScript to a project and also to test out the languages capabilites. For the most part, the app runs without any slowdowns. When the project runs in "Release Mode", it runs exactly like it did when built 100% in C++, but there is a slowdown when the player fires too many projectiles in "Debug Mode". I traced this to the collision detection code which I also decided to do in AngelScript. By reducing the number of active projectiles, I was able to get the performance back in the range of the C++ levels. This is to be expected because of the usual debugging overhead. I was surprised at how nicely it worked in "Release Mode". Changing the constants in 'constants.as' successfully changes the project without recompiling. AngelScript is a language that should be considered if you're thinking about adding scripting to your C++ project. It's easy to learn if you have a C++ background and it binds with C++ very well. I hope that I was able to cover the major points for adding AngelScript to your game.

Coding style in this article

Listed in the best practices for AngelScript is to always check the return value for every function. In most of the AngelCode examples and in the manual an assert is used to check for errors. I don't use the assert, instead I've been using "if(result < 0) return result;". This can easily be replaced by "assert(r >= 0);" as is used in the AngelScript documentation. Also, my goal with this project was to change the XACTGame sample as little as possible. The XACTGame sample was designed to show certain techniques such as adding graphics and audio, and it uses a simple framework.

Getting AngelScript

You can download the latest version of the AngelScript SDK from the AngelCode website. http://www.angelcode.com/ You'll find an excellent manual that explains the API in detail.

Note on Microsoft Source Code

Because Microsoft code was used in this program, I want to state some terms from the Direct X SDK EULA. The XACTGame sample was created by Microsoft and Microsoft owns the copyright. Changes made by Dominque Douglas have been clearly marked. Use of the source code provided does not change the license agreement for using Microsoft code. Microsoft code cannot be modified to work on non-Microsoft operating systems and Microsoft is not responsible for any claims related to the distribution of this program. Refer to the license agreement in the Direct X SDK for details.

Downloading This Project

The source code can be downloaded here: XACTGameAngelScript-Part3.zip

 Download note: Because of the size, this does not include the media files needed by the project such as the audio files and graphics files. You'll need to copy the "media" folder from the XACTGame sample in the Direct X SDK. You may need to alter the project's include and library directories to match your system. For simplicity, the AngelScript add-ons that were used in this project have been included. The project is a Visual Studio 2010 solution.

With this final part of the series, I've decided to also include the binary versions of the project.

XACTGameAngelScript-Binaries.zip

XACTGameAngelScript-Binaries - With Media.zip

Programming By Example - Adding AngelScript to a Game Part 2

For Part 1: Programming By Example - Adding AngelScript to a Game Part 1
For Part 2: Programming By Example - Adding AngelScript to a Game Part 2
For Part 3: Programming By Example - Adding AngelScript to a Game Part 3

Introduction

This is part 2 of the article Adding AngelScript to an Existing Game. In the first installment, This article series focuses on how to add a scripting language to a game and goes beyond just teaching a scripting language's API. Using the XACTGame example from the Microsoft Direct X SDK, I will detail the entire process. In part 1, I discussed some AngelScript basics and I showed how to add some bindings so the script can communicate with the C++ code. Then I scripted the InitApp() function. This article will build on the concepts from part 1 and in it, I'll code the remaining bindings so the script can call the proper C++ functions. In part 3, I'll write the remaining scripts. AngelScript Concepts Covered

• Binding a C++ Interface to the script
  • Registering a Scoped Reference Type
  • Registering a POD Vale Type
  • Registering an Array as a Global Property
  • Registering functions with overloads

Adding Scripting to More Functions

As we did in part 1, we need to continue to survey the code to see what the dependencies are. Then we'll be able to figure out what bindings we'll need. Here are the remaining functions that I'll script and their dependencies. void FireAmmo();

• D3DXVECTOR4
• D3DXMATRIXA16
• D3DXMatrixInverse()
• D3DXVec4Transform()
• g_Camera.GetViewMatrix()
• AMMO_STATE
• PlayAudioCue( g_audioState.iAmmoFire );

void DroidPickNewDirection( int A );

• D3DXQUATERNION
• D3DXQuaternionRotationYawPitchRoll
• D3DXMatrixRotationQuaternion
• DROID_STATE
• AI_STATE
• GAME_STATE - DROID_STATE DroidQ[MAX_DROID];

void DroidChooseNewTask( int A );

• rand()
• GAME_STATE - DROID_STATE DroidQ[MAX_DROID];
• D3DXMatrixRotationQuaternion
• D3DXMATRIXA16
• Play3DAudioCue( g_audioState.iDroidScan, &g_GameState.DroidQ[A].vPosition );

void HandleDroidAI( float fElapsedTime );

• GAME_STATE - DROID_STATE DroidQ[MAX_DROID];
• D3DXQuaternionSlerp
• D3DXMATRIXA16
• D3DXMatrixRotationQuaternion
• D3DXQUATERNION

void HandleAmmoAI( float fElapsedTime ); CheckForInterAmmoCollision() CheckForAmmoToWallCollision( A ); CheckForAmmoToDroidCollision( A );

• GAME_STATE
• DROID_STATE
• AMMO_STATE

While, I'd prefer to not write any more object types, after looking at that list, it seems like I'll need to make these new types

• D3DXVECTOR4
• D3DXMATRIXA16
• D3DXQUATERNION
• DROID_STATE
• AMMO_STATE

Registering a Scoped Reference Type for D3DXMATRIXA16

Adding the D3DXVECTOR4 and D3DXQUATERNION won't be hard considering they're almost exactly like D3DXVECTOR3. All it will take is some copying and pasting and some searching and replacing. The XACTGame sample application uses D3DXMATRIXA16 this class inherits from D3DXMATRIX and overloads the new and delete operators to keep things 16 bit aligned. Because of these special memory requirements, we can't create the object as a value type, we'll need to create it as a reference type. A reference type is an object that resides in dynamic memory; however, to use reference types, we'd have to add reference counting to the object which is not something we want to add. Thankfully AngelScript provides a special type of reference type just for this situation called a scoped reference type. To create an scoped reference type we'll need a function call like this:

r = engine->RegisterObjectType("D3DXMATRIXA16", 0, asOBJ_REF | asOBJ_SCOPED);

With reference types, we don't register constructors. Instead we register factories. A factory should create the object using dynamic memory. We also need a release function that AngelScript will use to delete the object. This is what we'll need for the D3DXMATRIXA16 type.

static D3DXMATRIXA16 *D3DXMATRIXA16_Factory()
{
  return new D3DXMATRIXA16;
}

static D3DXMATRIXA16 *D3DXMATRIXA16_FactoryCopy(const D3DXMATRIXA16 &other)
{
  return new D3DXMATRIXA16(other);
}

static D3DXMATRIXA16 *D3DXMATRIXA16_FactoryFromfloats(float _11, float _12, float _13, float _14,
                                                      float _21, float _22, float _23, float _24,
                                                      float _31, float _32, float _33, float _34,
                                                      float _41, float _42, float _43, float _44)
{
  return new D3DXMATRIXA16(_11, _12, _13, _14,
                           _21, _22, _23, _24,
                           _31, _32, _33, _34,
                           _41, _42, _43, _44);
}

static void D3DXMATRIXA16_Release(D3DXMATRIXA16 *s)
{
  if( s ) delete s;
}

I'll register the operators the same way I did or D3DXVECTOR3 and D3DXVECTOR4 with one exception. When using scoped reference types, "any function that either takes or returns the type by value in C++ must be wrapped in order to permit AngelScript to manage the life time of the values."(from the AngelScript manual) This means that will need to changed the binary operators so they return a pointer in C++, and a handle in AngelScript.

static D3DXMATRIXA16 *Matrix_opMul /* operator * */ ( const D3DXMATRIXA16 &lhs, const D3DXMATRIXA16 &rhs)
{
 // (From AngelScript Manual) any function that either takes or returns the type by value in C++ must
 // be wrapped in order to permit AngelScript to manage the life time of the values
 return new D3DXMATRIXA16(lhs * rhs);
}

Here's the function for registering the D3DXMATRIXA16 type. Redundant parts of the code have been omitted.

int RegisterD3DXMATRIXA16(asIScriptEngine *engine)
{
 int r;

 // Register the string type
 r = engine->RegisterObjectType("D3DXMATRIXA16", 0, asOBJ_REF | asOBJ_SCOPED);
 if(r < 0) return r;

 // with reference types we register factores and not constructors
 r = engine->RegisterObjectBehaviour("D3DXMATRIXA16", asBEHAVE_FACTORY, "D3DXMATRIXA16 @f()", asFUNCTION(D3DXMATRIXA16_Factory), asCALL_CDECL);
 r = engine->RegisterObjectBehaviour("D3DXMATRIXA16", asBEHAVE_FACTORY, "D3DXMATRIXA16 @f(const D3DXMATRIXA16 &in)", asFUNCTION(D3DXMATRIXA16_FactoryCopy), asCALL_CDECL);
 r = engine->RegisterObjectBehaviour("D3DXMATRIXA16", asBEHAVE_FACTORY, 
  "D3DXMATRIXA16 @f(float, float, float, float, float, float, float, float, float, float, float, float, float, float, float, float)",
  asFUNCTION(D3DXMATRIXA16_FactoryFromfloats), asCALL_CDECL);
 r = engine->RegisterObjectBehaviour("D3DXMATRIXA16", asBEHAVE_RELEASE, "void f()", asFUNCTION(D3DXMATRIXA16_Release), asCALL_CDECL_OBJLAST);

 r = engine->RegisterObjectMethod("D3DXMATRIXA16", "D3DXMATRIXA16 &opMulAssign( const D3DXMATRIXA16 &in)", asFUNCTION(Matrix_opMulAssign), asCALL_CDECL_OBJLAST);
 if(r < 0) return r;
 r = engine->RegisterObjectMethod("D3DXMATRIXA16", "D3DXMATRIXA16 &opAddAssign( const D3DXMATRIXA16 &in)", asFUNCTION(Matrix_opAddAssign), asCALL_CDECL_OBJLAST);
 if(r < 0) return r;
 r = engine->RegisterObjectMethod("D3DXMATRIXA16", "D3DXMATRIXA16 &opSubAssign( const D3DXMATRIXA16 &in)", asFUNCTION(Matrix_opSubAssign), asCALL_CDECL_OBJLAST);
 if(r < 0) return r;
 r = engine->RegisterObjectMethod("D3DXMATRIXA16", "D3DXMATRIXA16 &opMulAssign( float)", asFUNCTION(Matrix_opMulAssignF), asCALL_CDECL_OBJLAST);
 if(r < 0) return r;
 r = engine->RegisterObjectMethod("D3DXMATRIXA16", "D3DXMATRIXA16 &opDivAssign( float)", asFUNCTION(Matrix_opDivAssign), asCALL_CDECL_OBJLAST);
 if(r < 0) return r;

 // instead of returning a value, the operator must return a handle because this is a scoped reference type
 r = engine->RegisterObjectMethod("D3DXMATRIXA16", "D3DXMATRIXA16 @Matrix_opMul(const D3DXMATRIXA16 &in)", asFUNCTION(Matrix_opMul), asCALL_CDECL_OBJFIRST);
 if(r < 0) return r;
 r = engine->RegisterObjectMethod("D3DXMATRIXA16", "D3DXMATRIXA16 @Matrix_opAdd(const D3DXMATRIXA16 &in)", asFUNCTION(Matrix_opAdd), asCALL_CDECL_OBJFIRST);
 if(r < 0) return r;
 r = engine->RegisterObjectMethod("D3DXMATRIXA16", "D3DXMATRIXA16 @Matrix_opSub(const D3DXMATRIXA16 &in)", asFUNCTION(Matrix_opSub), asCALL_CDECL_OBJFIRST);
 if(r < 0) return r;

 // some code omitted
 ...

 r = engine->RegisterObjectMethod("D3DXMATRIXA16", "D3DXMATRIXA16 &opAssign(const D3DXMATRIXA16 &in)", asMETHODPR(D3DXMATRIXA16, operator =, (const D3DXMATRIXA16&), D3DXMATRIXA16&), asCALL_THISCALL);
 if(r < 0) return r;

 r = engine->RegisterObjectMethod("D3DXMATRIXA16", "bool opEquals(const D3DXMATRIXA16 &in) const", asFUNCTION(MatricesEqual), asCALL_CDECL_OBJFIRST);
 if(r < 0) return r;

 // register the properties
 r = engine->RegisterObjectProperty("D3DXMATRIXA16", "float _11", asOFFSET(D3DXMATRIXA16,_11));
 if(r < 0) return r;
 r = engine->RegisterObjectProperty("D3DXMATRIXA16", "float _12", asOFFSET(D3DXMATRIXA16,_12));
 if(r < 0) return r;
 r = engine->RegisterObjectProperty("D3DXMATRIXA16", "float _13", asOFFSET(D3DXMATRIXA16,_13));

 // some code omitted
 ...

 return r;
}

There's one more thing I want to mention about this type. The D3DXMATRIXA16 type is derived from D3DMATRIX which has a union so the data can be accessed through an array or through individual floats. When I add this to AngelScript, I won't add support for the array.

typedef struct _D3DMATRIX {
    union {
        struct {
            float        _11, _12, _13, _14;
            float        _21, _22, _23, _24;
            float        _31, _32, _33, _34;
            float        _41, _42, _43, _44;

        };
        float m[4][4];
    };
} D3DMATRIX;

Registering a POD Vale Type

The DROID_STATE struct is a little special in that it doesn't have any constructors, destructors, or pointers. Also, copying and assignment can be done using a bit-to-bit copy. Because of this, we can register it with the flag asOBJ_POD. When using this flag, we don't have to supply a constructor, destructor, or assignment operator.

int RegisterDROID_STATE(asIScriptEngine *scriptengine)
{
 int r;

 // register AI_STATE enum
 r = scriptengine->RegisterEnum("AI_STATE");
 if(r < 0) return r;

 r = scriptengine->RegisterEnumValue("AI_STATE", "AI_TURNING", (int)AI_TURNING);
 if(r < 0) return r;

 r = scriptengine->RegisterEnumValue("AI_STATE", "AI_MOVING", (int)AI_MOVING);
 if(r < 0) return r;

 r = scriptengine->RegisterEnumValue("AI_STATE", "AI_STOPPED", (int)AI_STOPPED);
 if(r < 0) return r;

 // Register DROID_STATE as POD Value type
 // Register a primitive type, that doesn't need any special management of the content
 r = scriptengine->RegisterObjectType("DROID_STATE", sizeof(DROID_STATE), asOBJ_VALUE | asOBJ_APP_CLASS | asOBJ_POD);

 r = scriptengine->RegisterObjectProperty("DROID_STATE", "bool bActive", asOFFSET(DROID_STATE,bActive));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "D3DXVECTOR3 vPosition", asOFFSET(DROID_STATE,vPosition));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "D3DXVECTOR3 vVelocity", asOFFSET(DROID_STATE,vVelocity));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "D3DXVECTOR3 vNudgeVelocity", asOFFSET(DROID_STATE,vNudgeVelocity));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "AI_STATE aiState", asOFFSET(DROID_STATE,aiState));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "float fTargetRotation", asOFFSET(DROID_STATE,fTargetRotation));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "D3DXQUATERNION qTarget", asOFFSET(DROID_STATE,qTarget));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "D3DXQUATERNION qStart", asOFFSET(DROID_STATE,qStart));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "D3DXQUATERNION qCurrent", asOFFSET(DROID_STATE,qCurrent));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "float fRotInterp", asOFFSET(DROID_STATE,fRotInterp));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "float fTaskTimer", asOFFSET(DROID_STATE,fTaskTimer));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "int nHitPoints", asOFFSET(DROID_STATE,nHitPoints));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "float fDeathAnimation", asOFFSET(DROID_STATE,fDeathAnimation));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "float fAlpha", asOFFSET(DROID_STATE,fAlpha));
 if(r < 0) return r;
 r = scriptengine->RegisterObjectProperty("DROID_STATE", "D3DXCOLOR Specular", asOFFSET(DROID_STATE,Specular));

 return r;
}

I'll handle the AMMO_STATE structure the same way. To see how this is coded, see "scriptdroidammostates.cpp" in the source code for this article.

Arrays - Getting The Droid State

Now there's one big thing to consider now.XACTGame sample apps's DROID_STATE and AMMO_STATE information are stored in arrays inside of the GAME_STATE struct. C/C++ static arrays cannot be registered directly with AngelScript because AngelScript can't garuntee the lifetime of the array. Applications that want to use arrays need to register an array type. The AngelScript SDK comes with an add-on that can be used to register arrays, the class CScriptArray. This is a very useful class, but because it's for generic arrays, elements can't be accessed without converting back and forth between the type and void pointers. This means I can't just plug it into my C++ code. To get around this, I've written a STL-style wrapper for the CScriptArray class that behaves much like std::vector. Now all I have to do is change the array declaration to this:

CScriptArraySTL<AMMO_STATE> AmmoQ;
CScriptArraySTL<DROID_STATE>  DroidQ;

You can download the CScriptArraySTL class, by checking out the following blog entry: Blogspot post: C++ STL-Style Array That's Compatible with AngelScript I'll also add a Reset() method to the GAME_STATE class and register it with AngelScript so the script will be able to reset the state. The Reset() method will also be important because the XACTGame sample previously just used ZeroMemory(),a macro that calls memset(), to clear the data. This will no longer work because of the CScriptArraySTL array. I've also added clear to the droid state

// Reset in GAME_STATE
void Reset()
{
 // Reset here so we don't have to use ZeroMemory which messes up the CScriptArraySTL<> arrays
 gameMode  = GAME_RUNNING;

 nAmmoCount  = 0;
 fAmmoColorLerp = 0.0f;
 BlendToColor = (DWORD)0;
 BlendFromColor = (DWORD)0;

 nDroidCount = 0;
 nMaxDroids = 0;

 bDroidCreate   = false;
 bMassDroidKill   = false;
 fDroidCreateCountdown = 0.0f;

 bDroidMove  = false;
 bAutoAddDroids = false;

 // clear the static arrays
 ZeroMemory(gamePad, sizeof(DXUT_GAMEPAD) * DXUT_MAX_CONTROLLERS);
    
 // reset Ammo array
 AmmoQ.resize(MAX_AMMO);
 for(auto it = AmmoQ.begin(); it < AmmoQ.end(); it++)
 {
  (*it).clear();
 }

 // reset the Droid array
 DroidQ.resize(MAX_DROID);
 for(auto it = DroidQ.begin(); it < DroidQ.end(); it++)
 {
  (*it).clear();
 }
}

// changes to RegisterGameStateInterface
...
result = scriptengine->RegisterGlobalFunction("void Reset()", asMETHOD(GAME_STATE, Reset), asCALL_THISCALL_ASGLOBAL, &g_GameState);
if(result < 0) return result;

// initialize the droid state and ammo state arrays
result = g_GameState.DroidQ.InitArray(scriptengine, "array");
if(result < 0) return result;

result = g_GameState.AmmoQ.InitArray(scriptengine, "array");
if(result < 0) return result;
 
// register the droid state and ammo state arrays
result = scriptengine->RegisterGlobalProperty("array DroidQ", g_GameState.DroidQ.GetRef());
if(result < 0) return result;

result = scriptengine->RegisterGlobalProperty("array AmmoQ", g_GameState.AmmoQ.GetRef());
if(result < 0) return result;
...

Registering the remaining math functions

While keeping each type in it's own source file, I've decided to clean up the DirectX math bindings by making one header that and function that will add all of the types and functions. I had to make wrappers for most of the functions because the Direct X math functions use pointers but I want to use references with my AngelScript value type objects, and the wrapped functions will just return void and not a pointer to the out parameter. Also, even though it's not a Direct X math function, I've also decided to add my rand binding here as well with one change. Instead of just using the normal rand(), I'm going to change it so it takes the min and max values as a parameter.

static int rand(int min, int max)
{
 int diff = max - min;
 return (rand() % diff) + min;
}

Now when I register the function, I'll have to do it a little differently because I just overloaded rand() so it now has two versions with different params. So AngelScript knows which version to use, we need to register it like this: result = scriptengine->RegisterGlobalFunction("int rand(int, int)", asFUNCTIONPR(rand, (int, int), int), asCALL_CDECL); The asFUNCTIONPR macro takes 3 parameters--the function name, the parameter list, and the return type. This function registers all of the needed math functions.

int RegisterD3DXMathFunctions(asIScriptEngine *scriptengine)
{
 int result;

 // register our types first
 result = RegisterD3DXVECTOR3(scriptengine);
 if(result < 0) return result;
 result = RegisterD3DXVECTOR4(scriptengine);
 if(result < 0) return result;
 result = RegisterD3DXQUATERNION(scriptengine);
 if(result < 0) return result;
 result = RegisterD3DXMATRIXA16(scriptengine);
 if(result < 0) return result;

 // register the global functions
 result = scriptengine->RegisterGlobalFunction("void D3DXMatrixInverse(D3DXMATRIXA16 &out, float &out, const D3DXMATRIXA16 &in)", asFUNCTION(MatrixInverse), asCALL_CDECL);
 if(result < 0) return result;
 result = scriptengine->RegisterGlobalFunction("void D3DXVec4Transform(D3DXVECTOR4 &out, const D3DXVECTOR4 &in, const D3DXMATRIXA16 &in)", asFUNCTION(Vec4Transform), asCALL_CDECL);
 if(result < 0) return result;
 result = scriptengine->RegisterGlobalFunction("void D3DXQuaternionRotationYawPitchRoll(D3DXQUATERNION &out, float, float, float)", asFUNCTION(QuaternionRotationYawPitchRoll), asCALL_CDECL);
 if(result < 0) return result;
 result = scriptengine->RegisterGlobalFunction("void D3DXMatrixRotationQuaternion(D3DXMATRIXA16 &out, const D3DXQUATERNION &in)", asFUNCTION(MatrixRotationQuaternion), asCALL_CDECL);
 if(result < 0) return result;
 result = scriptengine->RegisterGlobalFunction("void D3DXQuaternionSlerp(D3DXQUATERNION &out, const D3DXQUATERNION &in, const D3DXQUATERNION &in, float t)", asFUNCTION(QuaternionSlerp), asCALL_CDECL);
 if(result < 0) return result;

 // add rand() here
 result = scriptengine->RegisterGlobalFunction("int rand(int, int)", asFUNCTIONPR(rand, (int, int), int), asCALL_CDECL);

 return result;
}

Handling Audio

I won't script any of the audio functions, but some of the other functions that I will script need access to some of the audio functionality. I'll need to give access to the following functions:

 HRESULT PlayAudioCue( XACTINDEX iCueIndex );
 HRESULT Play3DAudioCue( XACTINDEX iCueIndex, D3DXVECTOR3* pvPosition );
 void SetNumDroidsForAudio( int nDroidCount );

Adding these should be easy enough, but I'll need to wrap PlayAudioCue() and Play3DAudioCue() because they take the cue index as a parameter. I don't want to provide access to those variables so instead I'll make an enum that's a list of all of the cue indices and the wrapped functions will take the enum as a parameter.

enum AudioCues
{
    Cue_iAmmoBounce = 0,
    Cue_iAmmoFire,
    Cue_iDroidDestroyed,
    Cue_iDroidScan,
    Cue_iBackgroundMusic,
    Cue_iRoomRumble
};

XACTINDEX GetCueIndex(AudioCues cue)
{
 switch(cue)
 {
  case Cue_iAmmoBounce:
   return g_audioState.iAmmoBounce;
  case Cue_iAmmoFire:
   return g_audioState.iAmmoFire;
  ... // some code omitted
 }

 return 0;
}

void PlayAudioCueWrapper( AudioCues cue )
{
 PlayAudioCue(GetCueIndex(cue));
}

void Play3DAudioCueWrapper( AudioCues cue, const D3DXVECTOR3 &vPosition )
{
 Play3DAudioCue(GetCueIndex(cue), (D3DXVECTOR3 *)&vPosition);
}

int RegisterAudioInterface(asIScriptEngine *scriptengine)
{
 int result;

 // set the namespace
 result = scriptengine->SetDefaultNamespace("AUDIO"); 
 if(result < 0) return result;

 // first register our enum
 result = scriptengine->RegisterEnum("AudioCues");
 if(result < 0) return result;

 result = scriptengine->RegisterEnumValue("AudioCues", "Cue_iAmmoBounce", (int)Cue_iAmmoBounce);
 if(result < 0) return result;

 result = scriptengine->RegisterEnumValue("AudioCues", "Cue_iAmmoFire", (int)Cue_iAmmoFire);
 if(result < 0) return result;

 ... // some code omitted

 result = scriptengine->RegisterGlobalFunction("void PlayAudioCue(AudioCues)", asFUNCTION(PlayAudioCueWrapper), asCALL_CDECL);
 if(result < 0) return result;

 result = scriptengine->RegisterGlobalFunction("void Play3DAudioCue(AudioCues, const D3DXVECTOR3 &in)", asFUNCTION(Play3DAudioCueWrapper), asCALL_CDECL);
 if(result < 0) return result;

 result = scriptengine->RegisterGlobalFunction("void SetNumDroidsForAudio(int)", asFUNCTION(SetNumDroidsForAudio), asCALL_CDECL);
 if(result < 0) return result;

 // reset back to global namespace
 result = scriptengine->SetDefaultNamespace(""); 

 return result;
}

Conclusion

It's taken some time, but now I have finished all of the needed bindings between AngelScript and C++ that I'll need. Now that all of the bindings are complete, I need to work on adding the scripts. AngelScript is a very powerful scripting language and I hope to show some of its features in part 3 of this article. In part 3 of this article, I'll write all of the scripts, I'll also show how to restrict bindings to some scripts.

Coding style in this article

Listed in the best practices for AngelScript is to always check the return value for every function. In most of the AngelCode examples and in the manual an assert is used to check for errors. I don't use the assert, instead I've been using [tt]if(result < 0) return result;[/tt]. This can easily be replaced by [tt]assert(r >= 0);[/tt] as is used in the AngelScript documentation. Also, my goal with this project was to change the XACTGame sample as little as possible. The XACTGame sample was designed to show certain techniques such as adding graphics and audio, and it uses a simple framework.

Getting AngelScript

You can download the latest version of the AngelScript SDK from the AngelCode website. http://www.angelcode.com/ You'll find an excellent manual that explains the API in detail.

Note on Microsoft Source Code

Because Microsoft code was used in this program, I want to state some terms from the Direct X SDK EULA. The XACTGame sample was created by Microsoft and Microsoft owns the copyright. Changes made by Dominque Douglas have been clearly marked. Use of the source code provided does not change the license agreement for using Microsoft code. Microsoft code cannot be modified to work on non-Microsoft operating systems and Microsoft is not responsible for any claims related to the distribution of this program. Refer to the license agreement in the Direct X SDK for details.

Downloading This Project

The source code can be downloaded here: XACTGameAngelScript-Part2.zip Download note: Because of the size, this does not include the media files needed by the project such as the audio files and graphics files. You'll need to copy the "media" folder from the XACTGame sample in the Direct X SDK. You may need to alter the project's include and library directories to match your system. For simplicity, the AngelScript add-ons that were used in this project have been included. The project is a Visual Studio 2010 solution.

C++ STL-Style Array That's Compatible with AngelScript

I've been working on a new class that I think will be useful to programmers working with AngelScript. AngelScript is nice because its data types are so similar to C++ that it's easy to bind it and share data. There's one thing that doesn't have an easy one-to-one AngelScript counterpart and that's static arrays. I can understand the reasoning behind this as the script has no mechanism that it can use to garuntee the life time of the array. AngelScript does have a nice add-on for arrays that's generic and can add arrays for any type, but I wanted something easier. I decided to make a template class that would wrap the CScriptArray add-on and give it an interface like std::vector including stl-style iterators.

Using the class.
The CScriptArraySTL class was designed so that the array can be created in C++ and then shared with AngelScript as a registered property, or as the return value of a registered functon. It is a template class that takes two template parameters.

template <class T, class TArrayClass = CScriptArray>
class CScriptArraySTL

The first parameter is the type, and the second parameter is the internal array class that has been registered with AngelScript. The default array class is the CScriptArray add-on that is included in the AngelScript SDK. To use this it, you must also include the CScriptArray add-on in your project and register it with AngelScript using the RegisterScriptArray() function. The internal array class is given as a template argument to allow the programmer to be able to use there own array implementation.

Declaring a variable:

// uses CScriptArray addon internally
// for this to work, std::string should be registered with AngelScript.
// This can be done using the ScriptStdString add-on.
CScriptArraySTL <std::string> string_array;

// uses a user-defined array type called CScriptArrayInt
// this type should be a specialized version of CScriptArray that only handles integers
CScriptArraySTL <int, CScriptArrayInt> int_array;

InitArray()
You can create variables using CScriptArraySTL anytime, but you can't use it until after the CScriptArraySTL object has been initialized using the InitArray() method. Here's the declaration for that function:

// Initializes the array so it can be directly accessed using AngelScript
// This must be called before the array can be used
int InitArray(asIScriptEngine *engine, char *declaration, size_type init_length = 0);

asIScriptEngine *engine
The first parameter is a pointer to the script engine. To maximize compatibility with AngelScript, this class uses creates it's internal data using the types that have been registered with AngelScript.

char *declaration
The second parameter is how you would write the type for this array in AngelScript. This allows the class to match its type with AngelScript. For example, if the class holds integers, it should be written "array<int>".

size_t init_length
This is the initial size of the array.

GetRef()
This function returns a pointer to the internal array class and can be registered with AngelScript as a property or returned from a function that has been registered with AngelScript.

Release()
This will release a reference to the array. After this method has been called, the CScriptArraySTL class will no longer be able to access the array data; however, as arrays are reference types in AngelScript, the data may still exist inside AngelScript until the reference count is zero. This method should be called before the script engine is released.

Sample Code

// Create the script engine
asIScriptEngine *engine = asCreateScriptEngine(ANGELSCRIPT_VERSION);

// Register needed add-ons
RegisterStdString(engine);
RegisterScriptArray(engine, true);

// setup our string array
CScriptArraySTL <std::string> string_array;
string_array.InitArray(engine, "array<string>");

// register our array as a global variable in the script
r = engine->RegisterGlobalProperty("array<string> string_array", string_array.GetRef()); assert( r >= 0 );

// do other things and load and run scripts
...

// Release the array
string_array.Release();

// Release the script engine
engine->Release();

Get the Source.
The source code and a example project can be found on GitHub. If you copy the "scriptarraystl" folder to the AngelScript SDK add_on folder, the project directory paths should work. Only a Visual Studio 2010 solution is being provided, but you should be able to run it using other compilers. To use this class in your project, all you need to do is include "ScriptArraySTL.h" The class has been implemented entirely in one header file.

GitHub link: https://github.com/squaredprogramming/scriptarraystl

____________________________________________________________________

Here's the complete list of the methods that I've implemented for the class.

// Constructors, Destructors and AngelScript initialization -------------------------------
CScriptArraySTL(void);
~CScriptArraySTL(void);

// Initializes the array so it can be directly accessed using AngelScript
// This must be called before the array can be used
int InitArray(asIScriptEngine *engine, char *declaration, size_type init_length = 0);

// returns a pointer to an array class that can be used in an AS script
TArrayClass *GetRef();

// Releases a reference to the array. After this is called, this class can
// no longer access the array data, but the data may still exist inside
// AngelScript until the refernce count is 0.
void Release();

// Capacity ----------------------------------------------------------------------------------

// returns the number of elements in the array
size_type size() const;
 
// resizes the array, adding unitialized data if the new size is bigger than the old size or
// deleting data if the new size is smaller
void resize(size_type n);

// returns true if the array is empty
bool empty() const;

// grows the buffer capacity
void reserve(size_type n);


// iterators ----------------------------------------------------------------------------
// returns an iterator to the begining of the array
iterator begin();

// returns an iterator to the end of the array
iterator end();

// returns a constant iterator to the begining of the array
const_iterator cbegin() const;

// returns a constant iterator to the end of the array
const_iterator cend() const;

// returns a constant iterator to the begining of the array
iterator begin() const;

// returns a constant iterator to the end of the array
iterator end() const;

// returns a reverse iterator to the begining of the array
reverse_iterator rbegin();

// returns a reverse iterator to the end of the array
reverse_iterator rend();

// returns a constant reverse iterator to the begining of the array
const_reverse_iterator crbegin() const;

// returns a constant reverse iterator to the end of the array
const_reverse_iterator crend() const;

// returns a constant reverse iterator to the begining of the array
const_reverse_iterator rbegin() const;

// returns a constant reverse iterator to the end of the array
const_reverse_iterator rend() const;

// Element Access -----------------------------------------------------------------------

// returns a reference to an element in the array. This will not throw an out-of-range exception.
// undefined behavior if out of range.
reference operator[](size_type index);

// returns a const reference to an element in the array. This will not throw an out-of-range exception.
// undefined behavior if out of range.
const_reference operator[](size_type index) const;

// returns a reference to an element in the array. This will throw an out-of-range exception.
reference at(size_type index);

// returns a constant reference to an element in the array. This will throw an out-of-range exception.
const_reference at(size_type) const;

// returns a reference to the first element
// undefined if empty
reference front();

// returns a constant reference to the first element
// undefined if empty
const_reference front() const;

// returns a reference to the last element
// undefined if empty
reference back();

// returns a constant reference to the last element
// undefined if empty
const_reference back() const;

// Modifiers ------------------------------------------------------------------------------------

// adds a value to the end of the array
void push_back (const value_type& val);

// removes the last element
void pop_back();

// assigns new data to the array using iterators.
template <class inputiterator=""&rt;
void assign (InputIterator first, InputIterator last);

// fills the array 
void assign (size_type n, const value_type& val);

// clears the contents of the array
void clear()