Introduction

The first part of this two-part series covered the fundamental syntax of the GameMonkey Script language and introduced you to its basic types, including functions and the flexible table object. This part will take you into the realm of embedding GameMonkey within your game or application and aims to give you enough information to experiment with the system and expand your knowledge on your own. If you have not read the first part then please do so as it is assumed that you know the information about GM Script that was laid out in the first article. This article covers the following topics:

• Basic embedding concepts
• Setting up your compiler environment
• Creating the GM virtual machine
• Executing a string as a script
• Loading a script from disk
• Basic Error checking
• Calling a Scripted function
• Creating a host-bound function
• Creating a simple type
• Garbage Collection
• Further study

Basic Embedding Concepts

GameMonkey Script runs as a Virtual Machine environment that requires manual binding to your host application. A virtual machine, as its name implies, is a piece of software that behaves as if it were a computer itself (Wikipedia, 2005). Typically, a virtual machine will execute programs by interpreting its own bytecode which is similar to the machine code used by the CPU on the machine I'm using to write this document. The game (or application) that uses the virtual machine must interact with its interface. You cannot simply call a scripted function or access data directly from your compiler environment - you must access the correct API functions to do so. Typically, the virtual machine has a very basic set of functions and data types; it is up to your game to export an interface of its own to the script environment. As you do this, the game and scripting environment become bound in a symbiotic relationship; in this state, the game is often referred to as the native (as in non-interpreted), or host application in which the scripted machine is embedded (Varanese, 2003).

Setting up your Compiler Environment

Compiler environments can vary quite wildly and so this section is by no means a comprehensive tutorial on setting up GameMonkey Script for your compiler. Unless you've downloaded the gmcore releases provided by the gmCommunity, you will only have the GameMonkey Script implementation as C++ source code. To embed GameMonkey script, you can either compile a static library from the source code or compile the source with your host application. For the sake of convenience, I will go the static-library route and describe the basic method of compiling a static library of the GM Script sources using a typical IDE.

1. Create an empty 'static library' C++ project
2. Locate your relevant platform configuration file(*) and copy it to your src/gm directory of the standard GM Script distribution
3. Import the *.cpp and *.h source files from the src/gm folder excluding the gmDebugger.cpp and gmDebugger.h files. Some examples also require gmCall.h /.cpp which can be found in src/binds
4. Set your compiler settings, altering the optimisation, runtime library and debug settings appropriately
5. Compile the static library and store in an accessible location

Once you have the static library, you can link it to your application like a normal library and compile programs using the GM Script API (assuming, of course, that you tell your compiler where to find the headers).

You will notice that step two has an asterisk next to it. The configuration file gmConfig_p.h is where all platform-specific defines and settings are kept. You can use it to specify the endian-ness of native CPU, the size of common types or even set specific compiler settings. Choosing your platform configuration is relatively simple for common Windows and Linux platforms (both MSVC and GCC), but you may need to edit your configuration file if you're using an exotic compiler and/or platform.

If you have downloaded and installed the gmcore releases from the gmCommunity project, you will notice that the location of these files is different to the standard distribution. This is to make it easier to compile and use the GM environment; gmcore can even detect and load the relevant platform configuration file without needing to copy it across.

Creating the GM Virtual Machine

Before you can use GameMonkey Script in any way you must embed it in your application. To do so, you must create an instance of the virtual machine, which is embodied by the gmMachine class provided by the GameMonkey API.

#include "gmThread.h"

int main()
{
	// Create the GM Machine object on the stack
	gmMachine gm;

	return 0;
}

Example: basic_1.cpp

Compiling and linking should proceed without a problem provided that you a) include the directory containing your GM headers in your project or global search path and b) link to the static library you created earlier. If you run this program you will see nothing special; but it's there. The GameMonkey VM is embedded in your application!

Executing a String as a Script