My second tutorial dealt with calling Lua functions from C++. This one deals with just the opposite situation - calling C++ functions from Lua. I couldn't think of a simple example that I was happy with, so I borrowed the average function from the official Lua documentation.

This tutorial now covers version 5.1 of Lua. There are some pretty major differences in each version of Lua. The code shown below will not work in older versions of Lua. If you are still using an older version and don't want to upgrade, I have provided downloads for version 4.0 and 5.0 at the bottom of this tutorial. With that in mind, let's get started.

In this tutorial we will create a function in C++, tell the Lua interpreter about it, and finally call it from Lua and use the results. I will also talk a little about error checking in Lua programs.

Defining the function

The first step is to define the function. All C or C++ functions that will be called from Lua will be called using a pointer of this type:

typedef int (*lua_CFunction) (lua_State *L);

In other words, functions must have a Lua interpreter as the only argument and return only an integer. Since a Lua interpreter is used for the argument, the function can actually take any number of arguments that are read from the stack. The integer returned is actually the number of values that have been pushed on the stack as we will see later. If you have existing C++ functions that you would like to call from Lua, wrappers can easily be created to meet this requirement.

The C++ average() function given below will demonstrate accepting multiple arguments and returning more than one value. Note that it's definition matches the typedef given above.

  1. The lua_gettop() function returns the index of the top of the stack. Since the stack is numbered starting from 1 in Lua, this is also the size of the stack and can be used as the number of arguments passed to the function.
  2. The for loop calculates the sum all of the arguments.
  3. The average of the arguments is pushed onto the stack with lua_pushnumber().
  4. Then the sum of the arguments is pushed onto the stack.
  5. Finally, the function returns 2, indicating two return values have been pushed to the stack.

Now that this function has been defined, we must tell the Lua interpreter about it. This is done in the main() function, just after the Lua interpreter is initialized and the libraries are loaded:

	/* register our function */
	lua_register(L, "average", average);

Save this file as luaavg.cpp. If you'd like to use straight C instead of C++, just name the file luaavg.c and remove the extern "C".

#include <stdio.h>

extern "C" {
	#include "lua.h"
	#include "lualib.h"
	#include "lauxlib.h"
}

/* the Lua interpreter */
lua_State* L;

static int average(lua_State *L)
{
	/* get number of arguments */
	int n = lua_gettop(L);
	double sum = 0;
	int i;

	/* loop through each argument */
	for (i = 1; i <= n; i++)
	{
		/* total the arguments */
		sum += lua_tonumber(L, i);
	}

	/* push the average */
	lua_pushnumber(L, sum / n);

	/* push the sum */
	lua_pushnumber(L, sum);

	/* return the number of results */
	return 2;
}

int main ( int argc, char *argv[] )
{
	/* initialize Lua */
	L = lua_open();

	/* load Lua base libraries */
	luaL_openlibs(L);

	/* register our function */
	lua_register(L, "average", average);

	/* run the script */
	luaL_dofile(L, "avg.lua");

	/* cleanup Lua */
	lua_close(L);

	/* pause */
	printf( "Press enter to exit..." );
	getchar();

	return 0;
}

This simple Lua script calls the function with five arguments and prints both of the returned values. Save this as avg.lua

-- call a C++ function

avg, sum = average(10, 20, 30, 40, 50)

print("The average is ", avg)
print("The sum is ", sum)

Compiling

On Linux you can compile this program by typing this command:

g++ luaavg.cpp -llua -llualib -o luaavg

Then run the program by typing:

./luaavg

If everything worked correctly, the program should print the average and sum of the numbers.

In Visual C++ you'll need to follow these steps:

  1. Create a new empty Win32 Console Application Project.
  2. Add the "luaavg.cpp" file to your project.
  3. On the menu click Project, luaavg Properties.
  4. Expand "Configuration Properties"
  5. Expand "Linker"
  6. Click "Input"
  7. Beside "Additional Dependencies" type lua5.1.lib.
  8. Click OK

At this point, you should be able to press F7 to Build the program.

Before we can run the program, you'll need to put the "lua5.1.dll" file where Windows can find it. Copy the file from "C:\Program Files\lua5.1\lib\dll" to your new Visual C++ project's folder. If your program compiled without errors, you can now press F5 to execute the program.

Error Handling

If you've read the Lua API documentation, you know that I left the error checking out of my version of the average function above. This was done to make it easier to explain, but in a real program you will want to do some error tests. In the example above, we should at least check each argument to make sure that it is a number. This can be done by adding the following piece of code inside the for loop:

if (!lua_isnumber(L, i)) {
	lua_pushstring(L, "Incorrect argument to 'average'");
	lua_error(L);
}

Checks like this are easy to add and can really make debugging easier. This is very important when dealing with a program written in two different languages. You'll find yourself debugging C++ and Lua.

Downloads

Resources

For in depth coverage of the Lua programming language, see Programming In Lua by the creator of the language. Game Development With Lua was written by professional programmers using Lua in a game. If you're interested in using other scripting languages in your game, or even creating your own language, check out Game Scripting Mastery.

Older Versions

Here are the files for Lua 5.0.

Here are the files for Lua 4.0.

  • luaavg-4.zip - Tutorial Source and Project files for Visual C++ 6 on Windows.
  • luaavg-4.tar.gz - Tutorial Source and Makefile for Linux.

You should now be able to set up Lua on your computer, call Lua functions from C++, and call C++ functions from Lua. This will probably be the last Lua tutorial for now. One of these days I'll come up with a more complicated program that ties all of these ideas together. Until then, feel free to experiment on your own and let me know what you come up with.