Lua Game Development Cookbook

You can use a directory structure as shown in the following diagram. If you intend to implement your application for multiple platforms, always divide platform-specific files into separate directories.

The Lib directory contains all the Lua module files and binary libraries.

However, each operating system uses its own file naming convention for binary libraries. The Lua language doesn't have an easy way to obtain the OS name. For this purpose, you can download and use the Lua script module os_name.lua from https://gist.github.com/soulik/82e9d02a818ce12498d1.

You should copy this file into your project directory so that the Lua interpreter can find it.

The require function in the Lua language uses a set of default paths defined in package.path and package.cpath string variables. With your new directory structure, you'd have to change those two variables manually for each operating system, which could be cumbersome.

Instead, you can define a Lua script to build up these two string variables from a generic list of paths for both Lua script files and binary libraries.

In the first step, you need to create a list of directories:

-- A list of paths to lua script modules
local paths = {
  '{root}/{module}',
  '{root}/lib/{module}',
  '{root}/lib/external/{module}',
  '{root}/lib/external/platform-specific/{platform}/{module}',
}
-- A list of paths to binary Lua modules
local module_paths = {
  '?.{extension}',
  '?/init.{extension}',
  '?/core.{extension}',
}

Strings enclosed with curly brackets will be substituted with the following values:

Binary module filename extensions that are platform dependent are also set in a table:

-- List of supported OS paired with binary file extension name
local extensions = {
  Windows = 'dll',
  Linux = 'so',
  Mac = 'dylib',
}

Now, you need to set root_dir which is the current working directory of the application and the current platform name as follows:

-- os_name is a supplemental module for
-- OS and CPU architecture detection
local os_name = require 'os_name'

-- A dot character represent current working directory
local root_dir = '.'
local current_platform, current_architecture = os_name.getOS()

local cpaths, lpaths = {}, {}
local current_clib_extension = extensions[current_platform]

Before you start building the path list, you need to check whether the current platform has defined binary module extensions as follows:

if current_clib_extension then
  -- now you can process each defined path for module.
  for _, path in ipairs(paths) do
    local path = path:gsub("{(%w+)}", {
      root = root_dir,
      platform = current_platform,
    })
    -- skip empty path entries
    if #path>0 then
      -- make a substitution for each module file path.
      for _, raw_module_path in ipairs(module_paths) do
        local module_path = path:gsub("{(%w+)}", {
          module = raw_module_path
        })
        -- add path for binary module
        cpaths[#cpaths+1] = module_path:gsub("{(%w+)}", {
          extension = current_clib_extension
        })
        -- add paths for platform independent lua and luac modules
        lpaths[#lpaths+1] = module_path:gsub("{(%w+)}", {
          extension = 'lua'
        })
        lpaths[#lpaths+1] = module_path:gsub("{(%w+)}", {
          extension = 'luac'
        })
      end
    end
  end
  -- build module path list delimited with semicolon.
  package.path = table.concat(lpaths, ";")
  package.cpath = table.concat(cpaths, ";")
end

With this design, you can easily manage your module paths just by editing paths and module_paths tables.

Keep in mind that you need to execute this code before any require command.

This recipe builds content for two variables that are used in the require function—package.path and package.cpath.

Both variables use a semicolon as a delimiter for individual paths. There's also a special character—the question mark which is substituted with the module name. Note that the path order might not be as important in this case as with our default list of paths. The path order might cause problems if you expect to use a module out of the project directory structure. Therefore, a customized set of paths from this recipe should always be used before the default set of paths.

The Lua language allows the use of hierarchical structure of modules. You can specify a submodule with package names delimited by a dot.

require 'main_module.submodule'

A dot is always replaced with the correct directory separator.

Code from this recipe will be probably used more than once in your project so that it can be moved into the Lua module file with similar algorithms. The module file can use the following structure:

-- algoritms.lua

-- Placeholder for a stack data structure code 

return {
  stack = stack,
}

This module structure can be used with algorithms from other recipes as well to keep everything organized.

The following code contains a local definition of the stack function. You can remove the local statement to make this function global or include it as part of the module:

local function stack()
  local out = {}
  out.push = function(item)
    out[#out+1] = item
  end
  out.pop = function()
    if #out>0 then
      return table.remove(out, #out)
    end
  end
  out.iterator = function()
    return function()
      return out.pop()
    end
  end
  return out
end

This stack data structure can be used in the following way:

local s1 = stack()
-- Place a few elements into stack
for _, element in ipairs {'Lorem','ipsum','dolor','sit','amet'} do
  s1.push(element)
end

-- iterator function can be used to pop and process all elements
for element in s1.iterator() do
     print(element)
end

Calling the stack function will create a new empty table with three functions. Push and pop functions use the property of the length operator that returns the integer index of the last element. The iterator function returns a closure that can be used in a for loop to pop all the elements. The out table contains integer indices and no holes (without empty elements). Both the functions are excluded from the total length of the out table.

After you call the push function, the element is appended at the end of the out table. The Pop function removes the last element and returns the removed element.

The code from this recipe can be placed into the algorithms.lua file as in the Making a stack recipe.

The queue data structure will consist of a constructor that returns a new table with three functions: a push, a pop, and an iterator. The resulting table uses the modified version of the length operator to get the right length of the queue:

local function queue()
  local out = {}
  local first, last = 0, -1
  out.push = function(item)
    last = last + 1
    out[last] = item
  end
  out.pop = function()
    if first <= last then
      local value = out[first]
      out[first] = nil
      first = first + 1
      return value
    end
  end
  out.iterator = function()
    return function()
      return out.pop()
    end
  end
  setmetatable(out, {
    __len = function()
      return (last-first+1)
    end,
  })
  return out
end

A new queue data structure can be created by calling the queue function:

local q1 = queue()
-- Place a few elements into queue
for _, element in ipairs {'Lorem','ipsum','dolor','sit','amet'} do
  q1.push(element)
end

-- You can use iterator to process all elements in single for loop
for element in q1.iterator() do
  -- each queue element will be printed onto screen
  print(element)
end

This algorithm uses a pair of integer indices that represent positions of the first and the last element of the queue. This approach provides element insertion and deletion in constant time. Because the original length operator isn't suitable for this case, a modified one is provided.

The iterator function creates a new closure that is used in a for loop. This closure is called repeatedly until the pop function returns an empty result.

This recipe will use the following shortcuts:

local ti = table.insert
local tr = table.remove

-- removes element from table by its value
local tr2 = function(t, v)
  for i=1,#t do
    if t[i]==v then
      tr(t, i)
      break
    end
  end
end

It's recommended to put it all together in one Lua module file.

The priority queue can be defined as in the following code:

return function pqueue()
  -- interface table
  local t = {}

  -- a set of elements
  local set = {}
  -- a set of priority bags with a elements
  local r_set = {}
  -- sorted list of priorities
  local keys = {}

  -- add element into storage, set its priority and sort keys
  --  k - element
  --  v - priority
  local function addKV(k, v)
    set[k] = v
    -- create a new list for this priority
    if not r_set[v] then
      ti(keys, v)
      table.sort(keys)
      local k0 = {k}
      r_set[v] = k0
      setmetatable(k0, {
        __mode = 'v'
      })
    -- add element into list for this priority
    else
      ti(r_set[v], k)
    end
  end

  -- remove element from storage and sort keys
  local remove = function(k)
    local v = set[k]
    local prioritySet = r_set[v]
    tr2(prioritySet, k)
    if #prioritySet < 1 then
      tr2(keys, v)
      r_set[v] = nil
      table.sort(keys)
      set[k] = nil
    end
  end; t.remove = remove

  -- returns an element with the lowest priority
  t.min = function()
    local priority = keys[1]
    if priority then
      return r_set[priority][1] or {}
    else
      return {}
    end
  end

  -- returns an element with the highest priority
  t.max = function()
    local priority = keys[#keys]
    if priority then
      return r_set[priority][1] or {}
    else
      return {}
    end
  end

  -- is this queue empty?
  t.empty = function()
    return #keys < 1
  end
  -- simple element iterator, retrieves elements with
  -- the highest priority first
  t.iterate = function()
    return function()
      if not t.empty() then
        local element = t.max()
        t.remove(element)
        return element
      end
    end
  end
  -- setup pqueue behavior
  setmetatable(t, {
    __index = set,
    __newindex = function(t, k, v)
      if not set[k] then
        -- new item
        addKV(k, v)
      else
        -- existing item
        remove(k)
        addKV(k, v)
      end
    end,
  })
  return t
end

This priority queue algorithm uses three tables: set, r_set, and keys. These tables help to organize elements into so-called priority bags. The first one, set contains elements paired with their priorities. It's also used when you try to obtain element priority from the queue. The second one, r_set contains priority bags. Each bag represents a priority level. The last one keys contains a sorted list of priorities, which is used in the extraction of elements from a minimal or maximal priority bag.

Each element can be inserted in a way similar to the Lua table with the exception that the inserted element is used as a key and priority is stored as a value:

priority_queue[element] = priority

This form of access can be used to update element priority. Elements with minimal or maximal priority can be extracted using the min or max function respectively;

local min_element = priority_queue.min()
local max_element = priority_queue.max()

Note that elements remain in the priority queue until you delete them with the remove function;

priority_queue.remove(element)

Priority queue can be queried with the empty function that returns true if there's no element in the queue;

priority_queue.empty()

You can use the iterator function in for loop to process all queue elements sorted by their priority:

for element in priority_queue.iterator() do
  -- do something with this element
end

In this recipe, you'll need to define our own iterator function, which will return every entry of a sparse array in deterministic order. In this case, the iterator function can be included in your code as a global function to accompany pairs and ipairs functions; or you can put it in a Lua module file not to pollute the global environment space.

This code shows a very simple sparse array iterator without any caching:

function ipairs_sparse(t)
  -- tmpIndex will hold sorted indices, otherwise
  -- this iterator would be no different from pairs iterator
  local tmpIndex = {}
  local index, _ = next(t)
  while index do
    tmpIndex[#tmpIndex+1] = index
    index, _ = next(t, index)
  end
  -- sort table indices
  table.sort(tmpIndex)
  local j = 1

  return function()
    -- get index value
    local i = tmpIndex[j]
    j = j + 1
    if i then
      return i, t[i]
    end
  end
end

The following lines of code show the usage example for iteration over a sparse array;

-- table below contains unsorted sparse array
local t = {
  [10] = 'a', [2] = 'b', [5] = 'c', [100] = 'd', [99] = 'e',
}
-- iterate over entries
for i, v in ipairs_sparse(t) do
  print(i,v)
end

The Lua language uses iterator functions in the control structure called the generic for. The generic for calls the iterator function for each new iteration and stops when the iterator function returns nil. The ipairs_sparse function works in the following steps:

Each call to ipairs_sparse prepares a new index table called index. The index consists of (integer, entry) pairs.

In this recipe, you will create three versions of a module that contains one local variable, one variable accessible from outside the module, one function that returns a simple value, and a function that uses a value from the current module.

There are three types of modules that are commonly used:

The first case is used mostly with modules that contain an interface to third-party libraries. The second type of module is used less often, but it's useful if you need multiple instances of the same object, for example, a network stack. The last one uses a similar approach as in the previous case, but this time there's always only one instance of the object. Many games use the singleton object for the resource management system.

-- module1.lua
local var1 = 'ipsum'
local function local_function1()
  return 'lorem'
end

local function local_function2(self)
  return var1 .. self.var2
end
-- returns module interface
return {
  lorem = local_function1,
  ipsum = local_function2,
  var2 = 'sit',
}

-- module2.lua
local M = function()
  local instance
  local var1 = 'ipsum'
  instance = {
    var2 = 'sit',
    lorem = function()
      return 'lorem'
    end,
    ipsum = function(self)
      return var1 .. self.var2
    end,
  }
  return instance
end

return M

-- module3.lua
local instance

local M = function()
  if not instance then
    local var1 = 'ipsum'
    instance = {
      var2 = 'sit',
      lorem = function()
        return 'lorem'
      end,
      ipsum = function(self)
        return var1 .. self.var2
         end,
    }
  end
  return instance
end

return M

Modules are used with the require function that registers them in the global table modules.loaded. This table contains the compiled code of every module used and ensures that each module is loaded only once.

Object modules return a local variable M, which contains an object interface. However, you can use any other name for this variable. Choosing between tables or closure as object contained is mostly a matter of application design.

Variable var1 is always hidden from the outside world and can be changed only by the exposed function. Variable var2 is freely accessible and can be modified anytime.

The following lines of code show the usage patterns for all three types of module:

local module1 = require 'module1'
local module2 = require 'module2'
local module3 = require 'module3'
-- create two instances of module2
local module2_A = module2()
local module2_B = module2()
-- try to create an instance of module2 twice
local module3_A = module3()
local module3_B = module3()

-- usage of a module with interface table
print('Module 1 - Before:', module1:lorem() .. module1:ipsum())
module1.var2 = 'amet'
print('Module 1 - After:', module1:lorem() .. module1:ipsum())

-- usage of a module in a form of an object
print('Module 2a - Before:', module2_A:lorem() .. module2_A:ipsum())
module2_A.var2 = 'amet'
print('Module 2a - After:', module2_A:lorem() .. module2_A:ipsum())
print('Module 2b - After:', module2_B:lorem() .. module2_B:ipsum())

-- usage of a module in a form of a singleton object
print('Module 3a - Before:', module3_A:lorem() .. module3_A:ipsum())
module3_A.var2 = 'amet'
print('Module 3a - After:', module3_A:lorem() .. module3_A:ipsum())
print('Module 3b - After:', module3_B:lorem() .. module3_B:ipsum())

This recipe will show error handling on a simple function that can exit prematurely with the error message:

 local function f1(a, b)
  assert((a == 1), "The first parameter must be equal to 1")
  print(b)
  return a+1
end

Here's how you can catch a nonfatal error with pcall by emulating the try and catch block:

function try(fn, catch_fn)
  local status, msg = pcall(fn)
  if not status then
    catch_fn(msg)
  end
end

try(function()
  f1(2, 3) -- this will throw "an exception"
end, function(e)
  print('An exception occured:', e)
  error('Throw exception')
end)

The next recipe shows how to create your own specialized xpcall2 function that can handle input parameters for a function:

local function xpcall2(fn, ...)
  local arg = {...}
  return xpcall(
    -- function wrapper to pass function arguments
    function(...)
      return fn(unpack(arg))
    end,
    -- error function
    function(msg)
      return debug.traceback(msg, 3)
    end
  )
end

print(xpcall2(f1, 2, 'a'))

The whole principle of the try and catch block emulation in Lua relies on the pcall function that catches the error message and pushes it into the catch block function.

The only weakness of this approach is that you can't get more information because you're handling errors outside of the scope of where the error occurred.

This issue can be solved with xpcall which handles error before stack unwinding so you can use the debug library to get more information about the error.

Xpcall2 works as a wrapper function that not only passes parameters into protected function calls, but also handles getting the trace back with the debug.traceback function and returns results or a status code with an error message.

The first thing you need to do before starting is to get the Lua binary library and the header files. After this step, you can download the Lutok2 header files and use them in your project.

On Windows:

On Linux:

In both cases, you'll need the C++ compiler that can handle C++11 version of the standard C++ language. You can use clang or gcc compiler under the Unix-like environment, or the recent version of Microsoft Visual C++.

In the following steps, you'll see most common scenarios of using the Lua language in your C/C++ project. Most of the Lutok2 code samples are paired with equivalent Lua C API code so that you can see what the equivalent C code looks like without using the Lutok2 library.

#include <lutok2/lutok2.hpp>

int main(int argc, char ** argv){
  lutok2::State state;
  return 0;
}

#include <lua.hpp>

int main(int argc, char ** argv){
  lua_State * state = luaL_newstate();
  return 0;
}

#include <lutok2/lutok2.hpp>

using namespace lutok2;
   
   /* A function to be exposed should always use following form:
    * Input argument : A reference to Lutok2 State object
    * Output variable: An integral number of return values
    */ 
int lua_example_myfunction(State & state){
  // C/C++ code to be invoked
  return 0;
}

extern "C" LUA_API int luaopen_example(lua_State * current_state){
  State * state = State(current_state);
  Module myModule;
  /* Expose lua_example_myfunction function in
   * Lua language environment.
   * Key value represents a function name in Lua.
   * Value should always be a function pointer.
   */
  myModule["myfunction"] = lua_example_myfunction;
  
  /* This module will return a Lua table
   * that exposes all functions listed in myModule.
   */
  state->stack->newTable();
  state->registerLib(myModule);
  return 1;
}

#include <lua.hpp>

static int lua_example_myfunction(lua_State * L){
  return 0;
}

static const struct luaL_Reg module[] = {
  {"myfunction", lua_example_myfunction},
  {NULL, NULL}
};

extern "C" LUA_API int luaopen_example(lua_State * L){
  lua_newtable(L);
  luaL_register (L, NULL, module);
  return 1;
}

int lua_example_myfunction(State & state){
  void * userData = (void*)123456789;
  Stack * stack = state->stack;

  stack->push<bool>(true);
  stack->push<int>(12345);
  stack->push<LUA_NUMBER>(12345.6789);
  stack->push<const std::string &>("A text");
  stack->push<void*>(userData);
  stack->newTable();
    stack.setField<bool>("boolean", false);
    stack.setField<int>("integer", (int)12345);
    stack.setField<LUA_NUMBER>("number", (lua_Number)12345.6789);
    stack.setField<const std::string &>("string", "A text");
    stack.setfield<void *>("userData", userData);
  return 6;
}

static int lua_example_myfunction(lua_State * L){
  void * userData = (void*)123456789;
  lua_pushboolean(L, (int)true);
  lua_pushinteger(L, 12345);
  lua_pushnumber(L, 12345.6789);
  lua_pushstring(L, "A text");
  lua_pushlightuserdata(L, userData);
  lua_newtable(L);
    lua_pushboolean(L, (int)false);
    lua_setfield(L, -2, "boolean");
    lua_pushinteger(L, 12345);
    lua_setfield(L, -2, "integer");
    lua_pushnumber(L, 12345.6789);
    lua_setfield(L, -2, "number");
    lua_pushstring(L, "A text");
    lua_setfield(L, -2, "A text");
    lua_pushlightuserdata(L, userData);
    lua_setfield(L, -2, "userData");
  return 6;
}

state.stack->to<DATA_TYPE_NAME>(index);

int integerValue = state.stack->to<int>(1);

int integerValue = luaL_checkinteger(L, 1);

#ifndef EXAMPLE_OBJECT_H
#define EXAMPLE_OBJECT_H

#include <string>

class ExampleObject {
public:
  int x;
  inline const std::string helloWorld(){
    return "Hello world";
  }
};
#endif

#ifndef LUA_EXAMPLE_OBJECT_H
#define LUA_EXAMPLE_OBJECT_H

#include "ExampleObject.hpp"

class LuaExampleObject : public Object<ExampleObject> {
public:
  explicit LuaExampleObject(State * state) :
    Object<ExampleObject>(state){
    /* Properties handle access to member variables
     * with getter and setter functions
     */
    LUTOK_PROPERTY("x", &LuaExampleObject::getX, &LuaExampleObject::setX);
    // Methods allow you to call member functions
    LUTOK_METHOD("helloWorld",
      &LuaExampleObject::helloWorld);
  }
  
  ExampleObject * constructor(State & state, bool & managed);
  void destructor(State & state, ExampleObject * object);
  int getX(State & state, ExampleObject * object);
  int setX(State & state, ExampleObject * object);
  int helloWorld(State & state, ExampleObject * object);
};
#endif

#include <lutok2/lutok2.hpp>
using namespace lutok2;

#include "LuaExampleObject.hpp"

ExampleObject * LuaExampleObject::constructor(State & state, bool & managed){
  return new ExampleObject;
}

void LuaExampleObject::destructor(State & state, ExampleObject * object){
  delete object;
}

int LuaExampleObject::getX(State & state, ExampleObject * object){
  state.stack->push<int>(object->x);
  return 1;
}

int LuaExampleObject::setX(State & state, ExampleObject * object){
  if (state.stack->is<LUA_TNUMBER>(1)){
    object->x = state.stack->to<int>(1);
  }
  return 0;
}

int LuaExampleObject::helloWorld(State & state, ExampleObject * object){
  state.stack->push<const std::string &>(object->helloWorld());
  return 1;
}

#include <lutok2/lutok2.hpp>
using namespace lutok2;

#include "LuaExampleObject.hpp"

extern "C" LUA_API int luaopen_example(lua_State * current_state){
  // State object is freed automatically after Lua state closes!
  State * state = new State(current_state);
  Stack * stack = state->stack;

  // Prepare main module interface table
  stack->newTable();
  
  /* Object interface registration always returns Lua function
   * with object constructor.
   */
  state->registerInterface<LuaExampleObject>(
    "LuaExample_ExampleObject");
  /* A new instance of ExampleObject can be obtained by
   * calling ExampleObject function from main interface table.
   */
  stack->setField("ExampleObject");
  return 1;
}

local exampleModule = require 'Example'

local example_object = exampleModule.ExampleObject()
example_object.x = 5
print(example_object.x)
print(example_object.helloWorld())

The Lutok2 library contains most of the commonly used Lua C API functions while sanitizing access to class objects.

The core of this library is divided into two sections:

All Lutok2 classes are encapsulated in Lutok2 namespace, so there should be no naming conflicts with other libraries. It contains automatic management of the Lua state for these use cases:

Class wrapper objects use the template form of lutok2::Object as a generic base class that handles most of the work in order to register the class interface in the current Lua environment. The template parameter is mandatory and specifies what class will be wrapped.

lutok2::Object<CLASS_NAME>

The constructor of the class wrapper must always be present, as it defines what methods or properties will be available in the Lua environment. It's called automatically during interface registration. The body of the constructor usually consists of several macros that specify the class members. There are two macros you can use, which are as follows:

The member functions are defined by their name as a string value and a function pointer. The member variables use a similar notation while using two function pointers. The first one points to the getter function that returns a value of the member variable. The second one points to the setter function that sets the value of the member variable. If you don't want to allow the member variable modification, you can use the pointer to the nullMethod function instead of your own setter function. This will effectively block any changes to the member variable from the Lua script.

Another part of the C++ class wrapper is the functions that manage object instance creation and destruction—constructor and destructor. The constructor method is called when you actually call the object constructor in the Lua environment and it gives you space to actually create a new object instance. There's a reference to the managed argument, which you can change to the false value if the object instance is managed elsewhere. This will also cause that destructor method won't be called upon garbage collection in the Lua environment:

CLASS_NAME * constructor(State & state, bool & managed);

The destructor method is called when the object is freed in the Lua environment during garbage collection. This is the place where you can clean up and free up the object's instance:

  void destructor(State & state, CLASS_NAME * object);

The LuaSDL module depends on many external libraries. To make the module preparation easier, there's a LuaSDL project repository at GitHub with support for the CMake building system. This project repository contains all the necessary external libraries, which make module building process a breeze.

You'll need to have the following software installed to successfully build the LuaSDL module:

The building process of LuaSDL is the same on both Windows and Linux operating systems with minor differences:

Note that Microsoft Visual Studio will generate the .dll binary files in the bin directory, whereas, Linux users will find the same binary files in the lib directory. You can copy all the binary files into one directory where your Lua application resides. This will ensure that the Lua interpreter finds all the necessary binary modules.

LuaSDL uses libSDL 1.2, which is more than 5 years old. Despite being no longer maintained, the LuaSDL package is considered as stable.

LuaSDL2 is being developed at the time of writing. You can access the source code from GitHub at https://github.com/soulik/LuaSDL-2.0.git.

Before running your Lua script with LuaSDL, make sure you've got the LuaSDL module with all the dependencies in the same directory. However, you can always override the PATH environmental variable so that your application can find the necessary libraries. Note that the path environment variable is managed in the operating system and it's not for the Lua module location!

First, you must load the LuaSDL module file. If this step fails, you are either missing the correct libSDL library or one of the dependencies:

require 'LuaSDL'

You can define your own assertion check function with the optional SDL error reporting:

function SDL_assert(condition, msg)
  local msg = (msg and msg .. ": " .. SDL.SDL_GetError())
  return assert(condition, msg)
end

You have to set up the default window parameters as follows:

local window_x_pos = 128
local window_y_pos = 128
local window_width = 640
local window_height = 480
local window_bpp = 0
local window_flags = 0

LuaSDL must be initialized with SDL.SDL_Init before any use:

SDL_assert(SDL.SDL_Init(SDL.SDL_INIT_EVERYTHING) >= 0, "Couldn't initialize SDL")

LuaSDL places the window randomly upon creation. You can override this by setting the environmental variable SDL_VIDEO_WINDOW_POS:

SDL.SDL_putenv(string.format("SDL_VIDEO_WINDOW_POS=%d,%d",window_x_pos, window_y_pos))

To set a window caption, you have to call the SDL.SDL_WM_SetCaption function:

SDL.SDL_WM_SetCaption("LuaSDL Example", "Example")

Now, you can create a window with the SDL.SDL_SetVideoMode function, which returns the SDL_Surface object as a userdata:

local screen = SDL_assert(SDL.SDL_SetVideoMode(window_width, window_height, window_bpp, window_flags))

You can use the event loop invariant or just use a break statement on the application exit:

local running = true

It's more efficient to use the table of event functions than the usual approach with the if, elseif, and else statements. Each table key is an integer constant in this case:

local events = {
  [SDL.SDL_MOUSEMOTION] = function(event_struct)
    local event_struct = event_struct.motion
    -- do something when this event occurs
  end,
  [SDL.SDL_MOUSEBUTTONDOWN] = function(event_struct)
    local event = event_struct.button
  end,
  [SDL.SDL_MOUSEBUTTONUP] = function(event_struct) 
    local event = event_struct.button
  end,
  [SDL.SDL_KEYDOWN] = function(event_struct) 
    local event = event_struct.key
    local key = event_struct.keysym.sym
  end,
  [SDL.SDL_KEYUP] = function(event_struct) 
    local event = event_struct.key
    local key = event_struct.keysym.sym
  end,
  [SDL.SDL_VIDEORESIZE] = function(event_struct) 
      local event = event_struct.resize
  end,
  [SDL.SDL_QUIT] = function(event_struct) 
      running = false
  end,
}
-- prepare local instance of SDL_Event object
local local_event = SDL.SDL_Event_local()

while (running) do
  -- check for events in the poll
  if (SDL.SDL_PollEvent(local_event)~=0) then
    local event_fn = events[local_event.type]
    if type(event_fn)=='function' then
      event_fn(local_event)
    end
  end
end

The SDL.SDL_Quit function ensures that all the temporary objects are freed upon application exit:

SDL.SDL_Quit()

Using the LuaSDL library must follow a certain pattern to ensure correct management of resources and events. Events are used as a primary source of information about user interaction with your application. The LuaSDL library can detect mouse movement, keyboard input, change of application window size, and a request to close your application.

The whole process of event processing uses event polling where you use the SDL.SDL_PollEvent function in each step of the main application loop to obtain information about the event that has occurred. This function may return a value 0 if there are no events to process. In this case, you can use this free time to process game logic. This recipe uses a skeleton table for event processing functions called events.

The most important event, SDL.SDL_QUIT, is received when the user closes the application window. You should clean up all the resources and LuaSDL state as well. Don't forget to use the SDL.SDL_Quit function before exiting your application to ensure all the previously used memory is freed.