Lua is a light-weight scripting language designed to extend existing C and C++ programs. Unfortunately, there are very few online tutorials covering this language. I learned how it works mainly by reading the source, and studying the programs included with the distribution. Hopefully, this page will make learning Lua a little easier for those following in my footsteps.

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.

First, you need to download Lua. You can get the source from the Lua download page. If you prefer precompiled binaries, you can check out LuaBinaries or go to the end of this tutorial for the Windows version.

Now we need to install Lua. On Linux you should be able to just extract the files then type "make linux" and "make linux install" as root. See the INSTALL file if you need more help. On Windows download the binaries below and unzip them to "C:\Program Files\lua5.1".

Everything should be ready to go on Linux, but on Windows we'll need to configure Visual C++ so it can find the Lua files.

  1. Open Visual C++ then go to Tools, Options.
  2. Expand "Projects and Solutions".
  3. Click "VC++ Directories".
  4. Choose "Include files" and add a new path "C:\Program Files\lua5.1\include".
  5. Now choose "Library files" and add the path "C:\Program Files\lua5.1\lib\dll".
  6. Click OK

You're now ready to compile your first Lua enabled C++ program.

Your first program with Lua

This program is short and straight forward, but I'll run through what's happening just in case it's not clear.

  1. A pointer to our Lua interpreter is created by calling lua_open().
  2. Lua libraries are loaded with luaL_openlibs(). This provides simple functions like print.
  3. Our script is executed with luaL_dofile(). This reads the file and runs the script.
  4. Finally, Lua is closed properly with lua_close().

Save this file as luatest.cpp. If you'd like to use straight C instead of C++, just name the file luatest.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;

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

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

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

	/* cleanup Lua */
	lua_close(L);

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

	return 0;
}

Here's a simple Lua script, just to make sure that it's working. Save this as test.lua

-- simple test

print "Hello, World!"

Compiling

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

g++ luatest.cpp -llua -ldl -o luatest

Then run the program by typing:

./luatest

If everything worked correctly, the program should print Hello, World!

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

  1. Create a new empty Win32 Console Application Project.
  2. Add the "luatest.cpp" file to your project.
  3. On the menu click Project, luatest 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.

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

  • lua-5.0-win32.zip - Lua 5.0 Headers, Libs, and DLLs for Windows development.
  • luatest.zip - Tutorial Source and Project files for Visual C++ 6 on Windows.
  • luatest.tar.gz - Tutorial Source and Makefile for Linux.

Here are the files for Lua 4.0.

If you've gotten this far then you are well on your way to using Lua in your own projects. The next tutorial will cover calling Lua functions with arguments and returning values from Lua to your C++ program.