Scripting API

The FS2_Open scripting API is intended to be as cross-platform and as language non-specific as possible. However, it is generally assumed that the most popular language will be Lua.

Code Description

Part One: Basic API and Scripting Hooks

Things To Know

script_system

This object abstracts a scripting session. It is generally used to allow for easy construction/destruction of whatever is necessary to initialize scripting system objects, and make sure that the right language session data is passed. Its constructor takes one argument, the name of the scripting session (for easy debugging)

script_system->CreateLuaSession(libraries)

Initializes a Lua session. Until this is called, you will not be able to use Lua at all and fs2_open should ignore code chunks that use it.

script_system->ParseChunk(debugname)

Parses a 'code chunk'. These are snippets of code encapsulated by symbols such as square brackets or parentheses. It stores a handle to the parsed script in memory (Probably bytecode).

script_system->RunBytecode(handle):Actually executes a code chunk that has been parsed with ParseChunk

Example

This snippet of code (using FS2_Open functions) will parse a file that has scripting after each "$Global:" variable identifier. After all the scripting has been parsed, it will evaluate every hook, once.

script_system Script_system;
std::vector<script_hook> Script_globalhooks;

//Initialize Lua
Script_system.CreateLuaState(Lua_libraries);

//Parse file
read_file_text("scripting.tbl");
reset_parse();
while(optional_string("$Global:"))
{
	Script_globalhooks.push_back(st->ParseChunk());
}

//Execute hooks
for(uint i = 0; i < Script_globalhooks.size(); i++)
{
	Script_system.RunBytecode(Script_globalhooks[i]);
}

Part Two: The Higher-Level Lua Library

Things To Know

script_lua_func_list

A function list array, used to store the name, function pointer, and descriptive text for library functions.

script_lua_obj_func_list

Same as a function list, except for object member functions and operators

script_lua_obj_list

An object list array, used to store the name, function object list, and descriptive text for objects.

script_lua_lib_list

A library function/object list, used to store the library name, function list, object list, and descriptive text. It can then be used to create a Lua session by passing it to CreateLuaSession()

SCRIPT_END_LIST

Ends the above lists

lua_cvar<>

A template used as an easy way of ensuring that a given object in Lua has the correct name and type everywhere.

LUA_OPER_*

A series of defines that can be used in place of an object member function name in the list, to cause the callback function to be used when that operator is present. Not very reliable right now.

script_lua_callback

Return value for a Lua callback function (ie a C function that is called from Lua)

script_parse_args

Call from within a Lua function callback to convert the passed arguments to C variables. Uses a format string to check for correct arguments and variable type, followed by pointers to the destination variables. The following list shows formatting characters, followed by the Lua value and the C variable type that must be passed for the value to be stored.

'b' - boolean (bool*)

'd' - number (double*)

'f' - number (float*)

'i' - number (int*)

'o' - object (uses the lua_cvar variable's Parse() function with *object)

'p' - object pointer (uses the lua_cvar variables ParsePtr() function with **object, where object is the actual one allocated by Lua)

's' - string (char**)

'|' - specifies that all arguments after this are optional.

script_return_args

Call from with a Lua function callback to convert the passed arguments to C variables. Uses the same format as script_parse_args, except that objects use Return() instead of Parse(), and 'p' is not supported.

LUA_RETURN_NOTHING

A define used for when a function doesn't use script_return_args

Example

A (very small) math library, that provides the function 'math.lvec(x,y,z)'. After this example you could then pass Lua_libraries to CreateLuaSession() to access the function.

//Define the local-vector object
static lua_cvar<vec3d>		l_lvec("lvec");

//Define the callback function
script_lua_callback lua_fs2_lvec(lua_State *L)
{
	vec3d v3 = vmd_zero_vector;
	script_parse_args(L, "|fff", &v3.xyz.x, &v3.xyz.y, &v3.xyz.z);

	//Note that script_return_args with the "o" parameter creates a new object in Luaspace
	//which is managed by Lua
	return script_return_args(L, "o", l_lvec.Return(&v3));
}

//For this example, lvec has no member functions
static const script_lua_obj_func_list lua_math_lvec_funcs[] = {
	{SCRIPT_END_LIST},
};

//Add the callback to the library's function list
static const script_lua_func_list lua_math_lib[] = {
	{"lvec", lua_fs2_lvec, "Creates a new local vector","number,number,number","lvec"},
	{SCRIPT_END_LIST},
};

//Add the object to the library's object list
static const script_lua_obj_list lua_math_lib_obj[] = {
	{l_lvec.GetName(), lua_math_lvec_funcs, "Local vector"},
	{SCRIPT_END_LIST},
};

//Add the library function and object lists to Lua_libraries
const script_lua_lib_list Lua_libraries[] = {
	{"math", lua_math_lib, lua_math_lib_obj, "Math library"},
	{SCRIPT_END_LIST},
};