Lua (Tutorial)

From DmWiki

Welcome to the Lua wiki tutorial by Russell Long

Table of contents

1 Introduction 2 Chapter One 2.1 Getting Ready 3 Loading and executing a simple script 4 External Links

Introduction

Lua is a fast,small scripting language that has a gained a large amount of popularity within the gamedev scene. This article deals with the setting up of Lua, basic functionality, usage with c/c++ and finally advanced concepts.

Chapter One

Getting Ready

Firstly head over to http://www.lua.org/ftp/ and grab 5.0.2. Unzip the archive to your desired location. We will start with a simple C application.

You will need to link to lua.lib and lualib.lib

#include <lua.h>
#include <lualib.h>
#include <lauxlib.h>
int main()
{
      //initalise a lua state
      lua_State *L = lua_open();
      
      //close this current lua state
      lua_close(L);
      return 1;
}

For C++ users we need to wrap the Lua includes in an extern

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

If you can compile and execute the above code, then congratulations! Next we need to initialise some Lua side libs. We'll also provide Lua with a string argument to process.

int main (void) 
{
   lua_State *L = lua_open(); 
  //lua base libs; comment the next 4 lines if you are using Lua version 5.11
   lua_baselibopen(L);
   lua_iolibopen(L);
   lua_strlibopen(L);
   lua_mathlibopen(L);  
   char myArg[] = "result = 2 * 2";
   luaL_dostring(L,myArg);
   lua_pushstring(L,"result")
   lua_gettable(L,LUA_GLOBALSINDEX);
   int result = lua_tonumber(L,-1);
   printf("Value of result is %d\n",result);
   lua_close(L);
   return 0;
}

Welcome to the Lua stack! C/C++ and lua communicate via the lua stack to address the problems of dynamic and static systems, also that of memory management

Hopefully from the above example, 4 will be the printed value. Firstly luaL_dostring loads and executes a string in the current lua state (which is L in our case). We know that the Result will contain the value 4 but we need to retrieve this value from lua by acessing the lua stack. Firstly we use lua_pushstring to PUSH on the stack the string "value". We then use lua_gettable with the argument "LUA_GLOBALSINDEX" as our variable result is considered of a global scope. This retrieves the result variable from lua and palces it on the stack where our string is. Next we need to retrieve this value from the lua stack by using lua_toxxxxxx(L,INDEXVALUE). We need a quick explanation of how the indexing works.

If we used 1, this would correspond to the value at the TOP of the stack, 2 would be the second and so on until MAX_STACK size. Having -1, corresponds to the last stacked item, -2 next to last and so on. So in our case we can use 1 or -1.

But what if "result" isn't a number but something else? how would we cope with this? Well we can use lua_isxxxxx(L,-1); on a stack item, this returns 1 on confirmation and 0 otherwise. We can also test for the type of any item on the stack by using lua_type(L,INDEXVALUE)

Loading and executing a simple script

We'll start off with a simple appliance of a lua script, setting the size of a applications resolution at startup.

 screenWidth = 800
 screenHeight = 600

and save that as settings.lua and place into your executable directory

int main (void) 
{
  lua_State *L = lua_open(); 
  //lua base libs; comment the next 4 lines if you are using Lua version 5.11
  lua_baselibopen(L);
  lua_iolibopen(L);
  lua_strlibopen(L);
  lua_mathlibopen(L);
  int width,height;
  if(luaL_loadfile(L,"settings.lua") || lua_pcall(L,0,0,0))
     printf("Error failed to load %s",lua_tostring(L,-1));
  else
  {
       lua_getglobal(L,"screenWidth");
       if(lua_isnumber(L,-1))
          width = lua_tonumber(L,-1);
       else
       {  
            printf("Error screenWidth is NAN\n");
            width = 600;
       }
       lua_getglobal(L,"screenHeight");
       if(lua_isnumber(L,-1))
          height = lua_tonumber(L,-1);
       else
       {  
            printf("Error screenHeight is NAN\n");
            height = 480;
       }
  }
  lua_close(L);
  // initialise screen yadda
  return 0;
}

In this instance I have used lua_getglobal which in essence an alias for pushstring and gettable in the previous example. we are also introduced to luaL_loadfile and lua_pcall. loadfile loads the file and pcall executes the file. If there is a problem with the file pcall returns 1. More on pcall later.

External Links

• lua.org (http://www.lua.org) - Lua official site.
• lua wiki (http://lua-users.org/wiki/) - Several tutorials for learning Lua. Wiki style.
• An Introduction to Lua (http://www.gamedev.net/reference/articles/article1932.asp) - Although a little old (it uses Lua 4.0.1, so the source code won't compile), this is a very comprehensive tutorial.