Lua is a script language frequently used in game development. Typically the game engine is written in C/C++ and the game itself is defined in Lua. Meaning setting up behaviour, placement of objects like powerups, doors, enemies etc is done in Lua. That way the game can be quickly tweaked without having to go through a time consuming re-compile.

But I am not going to go in depth about the different usage of Lua, nor explain the language itself. An online book at the Lua web page does that very well already. I will here assume you already have some basic knowledge about Lua.

Sol2 is an open source software project. Sol3 (sol2 v3.0) - a C Lua API wrapper with advanced features and top notch performance - is here, and it's great!

25.3 – A Generic Call Function. As a more advanced example, we will build a wrapper for calling Lua functions, using the vararg facility in C. Our wrapper function (let us call it callva) receives the name of the function to be called, a string describing the types of the arguments and results, then the list of arguments, and finally a list of pointers to variables to store the results; it.
Now, you should be able to wrap any C library by writing a lua wrapper. We still have some caveats: We will have to write a wrapping function for each of the functions in your C library to ‘parse’ the arguments( luaLchecknumber etc.).
Anatomy of a Lua to C Call; Putting It All Together; Make an msleep Function; We've Just Scratched the Surface; Introduction Earlier you read the Calling Lua From a C Program web page showing how to call Lua from C. There are a lot of instructions with no examples, always leaving something out, so you have to keep trying various things.

However finding any documentation on how to wrap a C++ class so that it can be used in Lua is difficult. One could of course use one of the ready made bridges. But here we are going to look at how to do it yourself.

The tricky part is deciding on how to do it. Because Lua is such a flexible language there is really a lot of ways you could achieve it.

The naive approach

First lets look at several options, what works and doesn't. My first approach was to light user data to store a pointer to my C++ class. I will use a Sprite class and related classes as examples here as that was the type of classes I was wrapping.

staticintnewSprite(lua_State *L)
{
int n = lua_gettop(L); // Number of arguments
if(n != 4)
returnluaL_error(L, 'Got %d arguments expected 4', n);
double x = luaL_checknumber (L, 1);
double y = luaL_checknumber (L, 2);
double dir = luaL_checknumber (L, 3);
double speed = luaL_checknumber (L, 4);
Sprite *s = newSprite(Point2(x, y), dir, speed);
lua_pushlightuserdata(L, s);
return1;
}

The code snippet above shows a naive implementation of this approach. Unfortunately it doesn't work. The problem is that a light user data is just a simple pointer. Lua does not store any information with it. For instance a metatable which we could use to define the methods the class supports.

An approach with limited functionality

The next approach would be to use user data. Unlike light user data it can store a reference to a metatable.

staticintnewSprite(lua_State *L)
{
int n = lua_gettop(L); // Number of arguments
if(n != 4)
returnluaL_error(L, 'Got %d arguments expected 4', n);
// Allocate memory for a pointer to to object
Sprite **s = (Sprite **)lua_newuserdata(L, sizeof(Sprite *));
double x = luaL_checknumber (L, 1);
double y = luaL_checknumber (L, 2);
double dir = luaL_checknumber (L, 3);
double speed = luaL_checknumber (L, 4);
*s = newSprite(Point2(x, y), dir, speed);
lua_getglobal(L, 'Sprite'); // Use global table 'Sprite' as metatable
lua_setmetatable(L, -2);
return1;
}

For us to be able to use sprite like this we need to register class first. Basically we need to create a table Sprite which contains all the methods that our user data should support.

// Show registration of class
staticconst luaL_Reg gSpriteFuncs[] = {
// Creation
{'new', newSprite},
{'position', position},
{'nextPosition', nextPosition},
{'setPosition', setPosition},
{'render', render},
{'update', update},
{'collision', collision},
{'move', move},
{'accelerate', accelerate},
{'rotate', rotate},
{NULL, NULL}
};
voidregisterSprite(lua_State *L)
{
luaL_register(L, 'Sprite', gSpriteFuncs);
lua_pushvalue(L,-1);
lua_setfield(L, -2, '__index');
}

This will allow us to create instances of Sprite and call methods on it in Lua like this:

-- Create an instance of sprite an call some methods
local sprite = Sprite.new(x, y, dir, speed)
sprite:setPosition(x,y)
sprite:render()

The final approach

In most cases this approach is sufficient but it has one major limitation. It does not support inheritance. You can change the methods of Sprite in Lua but that will change the behavior of all instances of Sprite. What you would want to do is to be able to change method on just the instance and then use that instance as a prototype for new Sprite instances, effectively creating a class inheritance system.

To do this we need to change the instance into being a table. How do we access our C++ object then? Simple, we just store the pointer to it as user data in one of the field of the table. You might think that this time light user data will be sufficient. However the problem is that only user data is informed of garbage collection, not tables or light user data. So if you want to delete the C++ object when corresponding lua table is garbage collected you need to use user data.

So we then arrive at our final solution. We will store a pointer to our C++ object as user data on the key __self in the table that represents our instance. __self is an arbitrary selected name. It could be anything. We will not register Sprite as as the metatable for our instance but instead register the first argument to the new function as it. This will allow us to support inheritance. Further the garbage collection function will be register on a separate table which will be used as metatable only for the user data. This is to allow it to be garbage collected.

staticintnewSprite(lua_State *L)
{
int n = lua_gettop(L); // Number of arguments
if(n != 5)
returnluaL_error(L, 'Got %d arguments expected 5 (class, x, y, dir, speed)', n);
// First argument is now a table that represent the class to instantiate
luaL_checktype(L, 1, LUA_TTABLE);
lua_newtable(L); // Create table to represent instance

// Set first argument of new to metatable of instance
lua_pushvalue(L,1);
lua_setmetatable(L, -2);
// Do function lookups in metatable
lua_pushvalue(L,1);
lua_setfield(L, 1

C++ Lua Wrapper