Scripting with LuaPlus and Cpp

At some point you would probably like to add some scripting to your game.

For example, think of particle emitters or characters. Everytime you change something, you have to recompile. With decent sized projects this could mean making a cup of tea everytime :). With some kind of scripting you could simply change your script and run your game immediately again. The script has changed, and therefore so has the character, particle emitter, AI, etc.

Scripting is a hot item these days. For example, a game I still like quite a lot -Unreal Tournament- consists for a large part of "UnrealScript." This script controls all kinds of objects throughout the game. Elevators, switches, AI, etc.

Here is a small excerpt from UnrealScript:

simulated final function RandSpin( float spinRate)
   {
      DesiredRotation = RotRand();
      RotationRate.Yaw = spinRate * 2 *FRand() - spinRate;
      RotationRate.Pitch = spinRate * 2 *FRand() - spinRate;
      RotationRate.Roll = spinRate * 2 *FRand() - spinRate;    
  }

Looks quite like normal C++ code, doesn't it?

Lua

I was reading through some programming books and read about Lua. Lua is a completely free scripting language. Even for commercial use. Basically the only thing you have to do is to mention it in a readme, and if you want to be really cool, add the Lua logo to your game.

Lua is based on ANSI C. It should compile on any platform. This means that if you ever try to port your game to linux, you don't need to change scripts. Also, Lua can be compiled or just "plain text". If your code (Script) is plain text, Lua will compile it on the fly when you load it in your game.

If you like to see compile errors, and have a compiled script, simply use the command line utility. You do not have to change any code to load "text" or binary Lua files! So, if you're done developping: Compile the Lua files and replace the text versions, and it should work just fine.

The main site of Lua is www.lua.org. Check it out for some more details.

The Language

Lua looks a bit like all kinds of languages: A mix of VB/C++. Loosely typed, "and" instead of "&&", etc. For a good language reference you might find some tutorials online. Or maybe get yourself a nice book about it. Right now I have less than half a day of experience with Lua, so I don't know everything yet either :).

Here is a small example what I'm using as a test script, called test.lua:

health = 100;
 
  PrintNumber(30);
 
 function Add(x, y) 
       return math.cos(x); 
 end
 
 -- function Update(x,y)
 --       return x + y;
 -- end 

LuaPlus

There is one thing I forgot to mention. I'm using an alternative version of Lua, called LuaPlus. This version is modified for better support in (V)C++. It can be used in Managed C environments too. It also comes with a debugger and a "QuickWatch" viewer. I haven't tried those yet, though.

Download the source and the binaries. Include the binary ".lib" files in your project (where you add the DirectX or SDL .libs to normally). You also have to include some files from the LuaPlus source directory. Check out the samples that come with LuaPlus to get it working!

LuaPlus is quite a bit more convenient than Lua 'normal'. There is a tutorial about Lua on Gamedev.net.

health = 100;

This means that a global variable "health", with a value of 100 is created immediatly when the script is loaded.

PrintNumber(30);

PrintNumber is a function I have in my C++ program, the code actually calls my C++ function from the script. This opens many possibilites AddBot("John"), "CreateExplosion(10,20)", etc. This is Lua -> C++.

Next, I also wanted to try C++ -> Lua. This could be great for binding your script to events. Also notice the "math.cos". You can use math in your scripts as well. There's even IO stream support, etc.

I believe you can actually call objects too. I haven't tried that yet, but I probably will later.

The Interface between C++ And Lua(Plus)

C++ and Lua are two different environments. How are those ever going to talk to each other? Internally Lua works with stacks (pushes, pops, should be a bit familiar, I assume). I believe that you have to take care of all the stack push/pops yourself in normal Lua.

With LuaPlus it's a bit different. It's close to normal C++. We'll put the code above to use in our C++ program.

I made a seperate .h file to test around with LuaPlus. I will paste the code here first and then explain it step by step.

#pragma once
  #include "LuaPlus.h"
   using  namespace LuaPlus;
   /* Lua test code
  
  */
 
   static  int LS_PrintNumber(LuaState* state)
   {
      LuaStack args(state);
  
      // Verify it is a number and print it.
        if (args[1].IsNumber()) {
          Log << args[1].GetNumber();
          printf("%f\n", args[1].GetNumber());
        }
      // No return values.
      return 0;
  }
  
  
   void test();
  
   void test() 
   {
      //Create state
      LuaStateOwner state;
      
      //With this the script can access our own C++ functions:
      state->GetGlobals().Register("PrintNumber", LS_PrintNumber);
  
      //Open test file:
      int iret = state->DoFile("test.lua");
      
      //Get a global variable:
      LuaObject sObj = state->GetGlobal("health");
      int mytest = sObj.GetInteger();
      
      //Update the value:
      sObj.AssignInteger(state, 30);
      //Get value again:
       mytest = sObj.GetInteger();
  
      //Call a function in lua:
      LuaFunction<float> Add =  state->GetGlobal("Add");
      float myret = Add(3.14f,0.0f);
      
  }

I have the habit of simply setting breakpoints in my code, and check out the value. Hence I don't 'print' much.

At the top of my code you will see the required declarations needed for the Lua file. Then follows a custom Print function, found in one of the LuaPlus examples. Then the last "Test" function is my test setup.

States

States are individual scripts, or environments. Every seperate script runs in its own state. If you want to run four scripts, you can't do that with one state, unless you unload it every time. Loading takes time, so you would want to use multiple states. (That's how I understood it from the docs)

// Create state
      LuaStateOwner state;
      
       // With this the script can access our own C++ functions:
      state->GetGlobals().Register("PrintNumber", LS_PrintNumber);

The above code creates a state variable, and registers my earlier mentioned LS_PrintNumber function.

The name it's registered as is "PrintNumber". I do this before loading the acutal script, since PrintNumber is called immediately (not within a function) from the Lua script. As seen above in my Lua code.

// Open test file:
       int iret = state->DoFile("test.lua");

This code simply opens (and if needed, compiles) the lua code. If it doesn't load because of errors, it will return an error code. 0 is OK. The rest is an error. You can lookup the table with errors from the Lua site. It's like 4-5 kinds of errors. The compiler returns way more descriptive errors, hence it's always useful to see why your code doesn't compile using this command line program:

E:\LuaPlus\Bin>luaplusc "E:\src\test.lua"
  luaplusc: E:\src\test.lua:6: unexpected symbol near `/'

Note that there are multiple ways to run a script. You can also use DoString(string) to run a script from a string you loaded somewhere. (or generated using an interface, etc.)

 

// Get a global variable:
      LuaObject sObj = state->GetGlobal("health");
       int mytest = sObj.GetInteger();

Here we get our global health variable, which we declared at the first line, remember? LuaPlus has all kinds of functions: GetInteger, GetString, GetDouble, GetFloat, etc. to get the right type of variable.

Also notice the "LuaObject" we are using to get the value. We now have a reference to the "health" variable.

Which also means we can update it:

// Update the value:
      sObj.AssignInteger(state, 30);
       // Get value again:
       mytest = sObj.GetInteger();

"Health" is now 30. Again, many functions: AssignFloat, AssignString, etc. The auto complete list (In VC++) that pops up when you type the '.' is quite straight forward.

// Call a function in lua:
      LuaFunction< float> Add =  state->GetGlobal("Add");
       float myret = Add(3.14f,0.0f);

This calls our "Add" function in Lua, from our C++ code. Pretty nice, first get a pointer to the function and then call the function. Notice my Add function does not do an add. It returns the cosinus, something I wanted to test.

Also notice the "float". This could be an integer, double, etc. Depending on your function in the Lua code. I think it's quite obvious.

Final words

I hope this simple introduction to Lua helps someone starting with Lua. I'm a complete starter right and are simply writing this to remember it myself after my Uni tests soon :).