ltdiff – diffing and patching of Lua tables released

October 11, 2014

Just published ltdiff a Lua snipped that allows diffing and patching of Lua tables. It is published on MoonRocks. The Rock page can be found here: and the repository is here:

ltdiff can be used to reduce the amount of data needed to be transmitted in order to synchronize two tables. Beware that there is some overhead especially for nested tables with only few entries.

Also when doing version control of data stored in Lua files this can be handy to see what has changed.

I originally wrote the script when I implemented the Quake3 networking model for a prototype game in LÖVE. The Quake3 networking model is very elegant that automatically reduces traffic by sending only changes to each client that haven’t been sent already (which is done with similar code published now in ltdiff). A good introduction to the model can be found here: I dearly hope to find some time to actually turn that prototype into an actual game.


LÖVE for Android 0.9.1b released

August 29, 2014

Yesterday I released a new version of LÖVE for Android, a fully featured Android port of the awesome 2d game framework LÖVE. Most excitingly you can now use vibration in your games.

Here is the complete list of changes for version 0.9.1b:

You can download pre-built APKs from


RBDL bugfix release 2.3.2

some very fine people found some bugs in RBDL which made me release another bugfix release. If you are using RBDL version 2.3.0 or 2.3.1 make sure to update as soon as possible.

You can find the newest version here:

Direct downloads here:

And here the list of changes: 29 August 2014: New version 2.3.2:


GLIMGUI released

March 26, 2014

Ages ago I wrote a nice article about how I searched for a simple GUI system for a game that I was working at the time. I ended up writing my own GUI system that was using the IMGUI approach and I am still very happy with this. It indirectly inspired @the_vrld to create Quickie which is an IMGUI system for my favourite 2D game framework LÖVE.

In the article I had written that I plan to release a simple library that can be used as a starting point for more advanced IMGUI explorations. Turns out I never did publish it so here we go:

Grab the code from:

It is licensed under the MIT license and as said very basic but with ~500 lines it should also be very easy to adjust and extend it. It is written in plain C and only depends on OpenGL and glut. Only ASCII strings are supported but if you have a fully featured unicode rendering function available it should be very easy to plug it in (look at glimgui_printxy(float x, float y, const char str*, ...)).

Here are some screenshots (very basic but easy-peasy to pimp): main_menu options

And here the full source code for the UI including the button logic that was used for the screenshots:

void draw_ui () {
  glimgui_prepare ();

  // Drawing of the GUI

  // We have two GUIs that are indicated by the global gui_layout value
  if (gui_layout == 0) {
    glimgui_label (99, "Main Menu", 20, 20, 1, 1); 

    if (glimgui_button (1, "Some Button", 220, 100, 180, 50)) {
      printf ("Some Button was pressed!\n");

    if (glimgui_button (2, "Options", 220, 180, 180, 50)) {
      gui_layout = 1;
      printf ("Switching to Options!\n");

    if (glimgui_button (3, "Quit", 220, 380, 180, 50)) {
      printf ("Quit!\n");
  } else {
    glimgui_label (99, "Options", 20, 20, 1, 1); 

    if (glimgui_button (1, "Some Other Button", 220, 100, 180, 50)) {
      printf ("Some Other Button was pressed!\n");

    glimgui_label (98, "Enter your name:", 150, 180, 1, 50);

    static char name[32] = { "IMGUI fan\0" };

    if (glimgui_lineedit (2, name, 16, 290, 195, -1, 20)) {
      printf ("Changed name value: '%s'\n", name);

    glimgui_label (97, "Enter your age:", 150, 210, 1, 50);

    static char age[32] = { "99\0" };

    if (glimgui_lineedit (3, age, 3, 290, 225, -1, 20)) {
      printf ("Changed age value: '%s'\n", age);

    if (glimgui_button (4, "Back", 220, 380, 180, 50)) {
      printf ("Switching back!\n");
      gui_layout = 0;

  glimgui_finish ();

Nice, ey?


To port my game I ported a game engine to android (Part II)

March 9, 2014

tl;dr: In the first part of this article I wrote about the motivations and the first steps I made to port the LÖVE engine to Android. Here I write about some technical difficulties that were solved and a few very interesting features the port now has. Also I created a small incomplete list of people who have contributed to this port.

Running a Real Game

I was really stoked when I saw the nogame screen the first time on my phone. A big helper for this was the GLES port of @slime73. There was almost no change required to get this far. The next thing up was to load an actual game. For this I had to somehow load the game. Undearneath LÖVE use physfs and comes with a custom wrapper for it. After some experiments I figured out that the Android NDK supports standard file I/O to the sd-card if you give the App write permissions to external storage (i.e android.permission.WRITE_EXTERNAL_STORAGE). With this knowledge in hand I implemented loading of the game found in /mnt/sd-card/lovegame. This allowed me to start my game on the phone without having to change a single line of the original Ludum Dare submission:

Running the game unveiled a bug in the GLES code when pushing new transformations but the fix was simple. From that on the game “just worked”. Including audio for which I did not have to change a single line of code!

Make it Work

Packaging Games

Now the port seemed it a very capable state. Something essential that was missing was creating a game Android package of the LÖVE engine + game into a proper Android package. I could already load games that were placed to /mnt/sdcard however LÖVE games are usually distributed either with the LÖVE binaries as OS specific packages or as .love files which is simply the game project folder packed into a zip file. Also LÖVE can directly load .zip files to run the games contained in them.

On Android on the other hand Apps can only open files that are stored in the assets/ folder. Luckily SDL2 allows accessing files in the assets folder without much hassle using the SDL_RWops. To create a packaged I simply added the file to the assets and when starting the App it would open the file using SDL_RWops and copy it to the internal storage and then load it using the standard LÖVE code. While this worked well this has the huge drawback that games would consume twice the memory: in the package’s asset/ folder and then in the internal storage. I could have tried to delete the latter when exiting the app but this didn’t work reliably enough.

Instead inspired by a hint of @slime73 I switched to the inofficial 2.1 code of physfs (which can be obtained using the official physfs merurial repository). Physfs 2.1 comes with PHYSFS_mountMemory that allows to load archives from memory instead of actual files, which works perfectly. I still have to copy the game from the assets/ directory into a memory buffer but it is much nicer and also uses less overall memory in the app statistics. (Physfs unfortunately introduced a bug but that is avoided in my port using a small hack).

LuaJIT instead of Lua

Another improvement that I wanted to do was to use LuaJIT instead of stock Lua. I had started with the latter as I wanted to first get things work and clean up things later. LuaJIT (which is also the now default in LÖVE) has quite a performance advantage in many cases over standard Lua — even on ARM. Setting up LuaJIT for the LÖVE port was quite a hassle. It comes with its own build system that I did not manage to integrate into Android’s NDK build system unfortunately. Eventually I resorted to adding the LuaJIT binaries to the repository along with a small script that builds it using the LuaJIT build system and the required Android specific parameters.

When testing LuaJIT with the LÖVE code unfortunately I had worse performance than using standard Lua. It took me a long time to figure out what might be the cause for it. To be honest I am still not entirely sure what exactly, however when reading this thread I tried the older 2.0.1 version and I could finally enjoy the performance gains. One nice thing about Android is that the JIT part of LuaJIT actually works.

As far as I know Apple sadly prohibits code generation on iOS which makes JIT impossible (see comment about iOS at

Updating of Libraries and Proper Linking

The build system for the external libraries was created using @schattenkindnet‘s older port. Some of the libraries that LÖVE uses have been updated since then and so I went on to update them. For some it was a lot of work to figure out which compiler flags were actually required or parts of the files were created during the build system which then again made me cross compile code using autotools (scary!) and extract files. Openal-soft was also challenging as it used CMake for which a CMake Toolchain script had to be used to create the proper configuration header files.

Eventually I ended up with all the files required such that I could use Android’s ndk-build to build everything (except LuaJIT). In the same time I also made sure that I link against all LGPL libraries dynamically whereas everything else is linked statically to reduce the binary size. Updating the libraries was worth it as also fixed audio performance.

Multi-Touch API

It wouldn’t be a proper mobile game engine if it didn’t have a touch API. I received a patch by piernov which fixed this. Eventually this code was replaced by the love.touch that was introduced to the experimental repository shortly afterwards and aims to be compatible with a future iOS port.

Make it nice

Additionally to the more or less technical things above the LÖVE port has a few very nice additions:

Accelerometer as Joystick: instead of adding a special sensor API read the accelerometer using SDL’s joystick API. This involved fixing a bug in SDL2 which was done by Jairo Luiz

Icon: Seppi (@josefnpat) created a fantastic logo out that mixes the Android with the LÖVE logo: ic_launcher

File Association: Since beta2 the Android LÖVE App adds a (somewhat experimental) file association. At least using Chrome mobile it lets you download .love files from the web such that you can open them from your Downloads activity. Also .love files attached to emails can be opened directly using the LÖVE App. Large parts of this was also made by Jairo Luiz

Game Editing on Device: Since LÖVE uses Lua and the code gets compiled/interpreted on run-time it allows for editing the game on the device itself without a host computer. Heck! It would even be possible to create whole games on the Android device without a PC!

Create Games for OUYA: People have even tried the port on Ouya. And guess what: it works!

Sensible Default Mappings: A touch event is reported as a left mouse button event. The back key maps to the escape key. For simple games this is sufficient to make it work.


I am currently working on getting my game released on the Google Play Store. It has been approved already and but I at the moment I am cleaning up some edges. But I hope to release it soonish to the public. Follow me on twitter or subscribe to the blog and you’ll get notified.

Also publishing the LÖVE App via the play store would be an idea. Maybe with some kind of launcher to simplify running of different games?


This all was only possible due to the fantastic works of others. Even though the risk is extremely high that I will forget valuable contributors I want to list some (let me know if I missed someone or something):


To port my game I ported a game engine to android (Part I)

February 21, 2014

tl;dr: I ported a game of mine to Android the LÖVE engine using the Android NDK to port a game of mine to Android. The port works pretty well and you can get games on Google Play with it. Making it open-source helped to get highly valued contributions and was tested much better than I could have ever done myself. SDL2 is magic. You can get it from This article is the first part that describes the initial steps of how I ported the engine to Android.


Last year I participated in the 26th installment of the Ludum Dare event. The theme was minimalism and I ended up with a nice game that fit the theme quite well both in terms of controls and visuals. Already then I thought that it would work well on a touch device.

For the game I used an awesome framework to make 2D games in Lua, namely LÖVE that I have been using since my very first game jam experience (fond memories!). There were some efforts to port an older version of the engine to Android which I could not get to run unfortunately.

Foreign Languages

I thought I could use the opportunity to learn something new. So I set out to play around using C# and MonoGame. Doing most of my stuff in Linux I could not create assets under Linux which was a big problem for me. Also having additional costs to actually get it to run on Android did not help to convince me. I totally see the service provided by Xamarin as worth its money, however for just wanting to play around and in combination with the asset problem this simply did not seem worth continuing to explore.

Next up was libgdx. It’s a very powerful framework that enjoys big popularity. I also got a first prototype running but it took me quite some time. Not having been exposed to Java enough I had problems with it’s objects everywhere type of thinking. Also being spoiled with LÖVE and Lua it felt too verbose for the simple things I was trying to do.

On September 18th 2013 I ordered two books: OpenGL ES 2 for Android: A Quick-Start Guide and Android NDK Beginner’s Guide. I ended up reading the latter much more. Being a native C/C++ programmer this wasn’t too surprising but still this marks a date where I still considered Java (in the end I gifted the Android OpenGL ES 2 book to a friend of mine who is working hard on a new game using libgdx – you should check it out!).

First Native Steps

I first started off using the testgles2.c example in SDL2. I was surprised how easy it was to port a SDL2 program to Android using the NDK. I made some random changes to get a feel for it but ultimately I removed all the rendering code and only colored the background that reacted on touch events, i.e. when a touch was registered it would turn red, otherwise the color decays to black.

After reading some about porting libraries to Android using the NDK I felt brave enough to port Lua to Android. It was pretty straight forward once I figured that you had to explicitly link against it in the SDLActivity class.

Already then some signs were read correctly:

First I ran scripts that I loaded from hard coded strings but then I found out about SDL2’s SDL_RWops. It massively facilitates reading and writing of files including those found in the asset/ folder. I exported some functions to Lua (including SDL.Log that is still found in LÖVE for Android) which allowed me to call an update function in Lua and also a function that gets called when a touch event was detected:

That was roughly the second day I played around with the SDL2 and Android!

Bits of Android LÖVE

I then ventured out to actually port LÖVE knowing that the most basic components should work (SDL2 + Lua + an apparently existing GLES port of @slime73). Worst case sound wouldn’t work and maybe some image types could not be loaded.

I took some inspiration of the older port made by @schattenkindnet. I completely rewrote the NDK build script and split it up in several somewhat independent native projects with their own file. This allowed me to focus on one library at a time and also I did not have to recompile everything only because I had modified the big global file.

I had it compiling on December 5th but I ran into some nasty issues with the OpenGL extension managing tool/library glad. It tried to locate the addresses of the OpenGL functions using SDL_GL_GetProcAddress() which in turn would calls eglGetProcAddress. That function however returns NULL for functions that are required in the initialization of glad. However with NULL as a result it would be interpreted as a failed initialization of glad, hence the whole graphics module of LÖVE would simply not work (and all this took me ages to figure out and I spammed the code of LÖVE with gazillions of SDL_Log() calls in the C code and SDL.log() statements in the Lua boot code ). Eventually the fix was to not only rely on SDL_GL_GetProcAddress() but also to manually check for the addresses using the good old dlsym function.

On December 8th I had the first working nogame screen on Android (it actually features the nogame screen of the then unreleased LÖVE 0.9.0):

This concludes the first part. There were some more bumps that waited to be fixed but I’ll write about those another time. Thanks for reading this far.

Continue to Part II…

Löve for Android – Alpha1

December 17, 2013


Over the last few weeks I made attempts to create a native port the awesome 2D game engine Löve to Android. So far it seems to work for relatively simple games. This was mainly possible due to the great GLES port of Alex Szpakowski (@/slime73).

Here are some e if you want to give it a try.


  1. Extract a game to /sdcard/lovegame, i.e. i.e. main.lua must be located at /sdcard/lovegame
  2. Download the Löve app from
  3. Run the app


This is super early alpha. Not sure yet what works and it’s possible that it may not work as expected.

Custom Types in LuaTables++ Done Right

October 22, 2013

Even though I am qute happy with LuaTables++ I figured storing and retrieval of custom types could be made even nicer. In my previous post I presented how one could add a custom type (i.e. a C++ struct or class) such that it can be assigned to values in Lua. It still required knowledge of the Lua C-API and would furthermore have made assignment of nested values more cumbersome. It now dawned to me that I could re-use facilities in LuaTables++ to circumvent both points.

For a struct of the form:

struct CustomType {
    string name;
    double age;
    bool drunken;
    double position[3];

especially setting the values of the double position[3] array would require creation of a new table which can be a bit cumbersome if one is not familiar with Lua’s stack. However this kind of functionality is already included in LuaTables++. Using the new API one can now implement the LuaTableNode::getDefault<CustomType>(const CustomType &value) function as:

CustomType LuaTableNode::getDefault<CustomType>(const CustomType &default_value) {
    CustomType result = default_value;

    if (exists()) {
        LuaTable custom_table = stackQueryTable(); = custom_table["name"].get<std::string>();
        result.age = custom_table["age"];
        result.drunken = custom_table["drunken"];
        result.position[0] = custom_table["position"][1];
        result.position[1] = custom_table["position"][2];
        result.position[2] = custom_table["position"][3];


    return result;

and similarly the LuaTableNode::set<CustomType>(const CustomType &value) as:

void LuaTableNode::set<CustomType>(const CustomType &value) {
    LuaTable custom_table = stackCreateLuaTable();

    // set the fields of the custom type
    custom_table["name"] =;
    custom_table["age"] = value.age;
    custom_table["drunken"] = value.drunken;
    custom_table["position"][1] = value.position[0];
    custom_table["position"][2] = value.position[1];
    custom_table["position"][3] = value.position[2];

    // restore the stack

One has to keep in mind that Lua starts its indices at 1 instead of 0. But apart from that I guess it should now be quite easy to add any kind of structs or classes even with complex member variables. If you have a suggestion to make it even simpler, let me know!


Using Lua Scripts as Config Files from C++

October 16, 2013

tl;dr: LuaTables++ is a library that allows you to access values from Lua scripts in an easy manner. Custom types (i.e. structs or classes) can be easily added so that storing and retrieval to and from Lua is super simple. Serialization to strings is included. Code available here (MIT license). Handling of custom classes / structs is explained here.


For my visualization tool MeshUp I am using jsoncpp to store the configurations files. However it dawned to me that it should be easy to implement a library that allows to store and retrieve values from Lua scripts similarly easy as jsoncpp. As Lua has a nicer syntax than JSON this would allow me to store the configuration as Lua scripts and thus getting all the scripting capabilities there as well.


The last few days I spent some time to pimp the my LuaTables (which I mentioned here) library to make it more intuitive to use from C++ and I ended up something very nice. It even deserves a renaming to LuaTables++. First, an example:

-- agentsettings.lua
person = {
    name = "James Bond",
    age = 42.,
    drunken = true,
    address = {
        country = "United Kingdom"

return person

Can be accessed using LuaTables++ using:

LuaTable ltable = LuaTable::fromFile("myfile.lua")

std::string name = ltable["name"];
double age = ltable["age"];
bool drunken = ltable["drunken"];
std::string country = ltable["address"]["country"];

Similarly you can set values:

ltable["drunken"] = false;

And also convert the table back to a string, e.g. to save the configuration back to a file:

std::string config_string = ltable.serialize();

Custom Types

Update: I have found a much better solution on how to handle custom types with LuaTables++.

This was very nice, but it gets better: LuaTables++ uses some templating magic inside which can be used to add reading and writing for structured data. E.g. to add the following custom type:

struct CustomType {
    CustomType() :
        name ("unnamed"),
        age (-1.),
        drunken (false) {}

    string name;
    double age;
    bool drunken;

one has to implement two functions:

Here the function for converting from LuaTables++ to the C++ CustomType:

template<> CustomType LuaTableNode::getDefault<CustomType>(const CustomType &default_value) {
    CustomType result = default_value;

    if (stackQueryValue()) {
        lua_getfield (luaTable->L, -1, "name"); = lua_tostring (luaTable->L, -1);
        lua_pop (luaTable->L, 1);

        lua_getfield (luaTable->L, -1, "age");
        result.age = lua_tonumber (luaTable->L, -1);
        lua_pop (luaTable->L, 1);

        lua_getfield (luaTable->L, -1, "drunken");
        result.drunken = lua_toboolean (luaTable->L, -1);
        lua_pop (luaTable->L, 1);


    return result;

And here the function to store a C++ CustomType to LuaTables++:

template<> void LuaTableNode::set<CustomType>(const CustomType &value) {

    // create new table for the CustomType
    lua_newtable(luaTable->L);  // parent, CustomTable

    // set the fields of the custom type
    lua_pushstring (luaTable->L, "name");
    lua_pushstring (luaTable->L,;
    lua_settable (luaTable->L, -3);

    lua_pushstring (luaTable->L, "age");
    lua_pushnumber (luaTable->L, value.age);
    lua_settable (luaTable->L, -3);

    lua_pushstring (luaTable->L, "drunken");
    lua_pushboolean (luaTable->L, value.drunken);
    lua_settable (luaTable->L, -3);

    // add table of CustomType to the parent
    stackPushKey(); // parent, CustomTable, key
    lua_pushvalue(luaTable->L, -2); // parent, CustomTable, key, CustomTable
    lua_settable(luaTable->L, -4);

    // restore the stack

Once this is done, one can directly store and retrieve any CustomType to Lua:

// Create a new Custom Type
CustomType agent007; = "James Bond";
agent007.age = 42.;
agent007.drunken = true;

// Store it in LuaTables++
ltable["agents"][123] = agent007;

// Retrieve it from LuaTables++
CustomType other_agent = ltable["agents"][123];

One nice thing about this is, that once you have implemented the set() and getDefault() functions you automatically can serialize and de-serialize CustomTypes. Yeeeehaaaa!


LuaTables++ is available from only depends on the STL and Lua, which should be easy to fulfill. It is licensed under the MIT license (same as Lua).

Fun Fact: Around the same time Elias Daler implemented something similar to retrieve values from a Lua script His article also contains a brief introduction how the internals work.


Switching between Lua and LuaJIT using CMake

August 26, 2013

The more I work with Lua, the more I get addicted to it. Lua itself is a formidable language and additionally it is (somewhat) fun to write wrappers to C/C++ code.

Lua itself is fast, but it can be made even faster by using LuaJIT, which is one of the fastest scripting language implementations available. The nice thing about LuaJIT is, that it is both API and ABI compatible to the standard Lua 5.1 implementation. This means that you simply need to link against the LuaJIT library instead of the Lua library and you get increased performance for free*!

For most of my C/C++ code I am using CMake as a build tool, which is does its job most of the time, albeit its language and syntax is rather cumbersome (especially compared to Lua). There is premake, a build system using Lua, which looks very interesting, however right now I have too little time to move my stuff over to it.

CMake comes with scripts to find Lua 5.0 and 5.1 but not to find LuaJIT. So I wrote my own FindLua.cmake script that searches for Lua 5.1 or LuaJIT depending on the value of the variable LUA_USE_LUAJIT option. Adjusting this variable allows easy switching between the standard Lua and LuaJIT.

CMake caches most of its variables and therefore you cannot change the type of Lua implementation using the CMake GUI. To alleviate this you can use the following lines, that ensure the invalidation of the cached CMake variables and nice and snappy switching between the implementations from the CMake GUI:

OPTION (LUA_USE_LUAJIT "Use LuaJIT instead of default Lua" OFF)

Here is full FindLua.cmake script:

# Copyright (c) 2013 Martin Felis &lt;;
# License: Public Domain (Unlicense:
# Try to find Lua or LuaJIT depending on the variable LUA_USE_LUAJIT.
# Sets the following variables:
#   Lua_FOUND
# Use it in a CMakeLists.txt script as:
#   OPTION (LUA_USE_LUAJIT "Use LuaJIT instead of default Lua" OFF)
    SET (LUA_LIBRARY_NAME luajit-5.1)
    SET (LUA_INCLUDE_DIRS /usr/include/luajit-2.0 /usr/local/include/luajit-2.0)
    SET (LUA_INCLUDE_DIRS /usr/include/lua5.1 /usr/local/include/lua5.1)

* the only “downside” of using LuaJIT instead of Lua that I faced so far is that you have ensure all your wrappers actually return an integer. Otherwise LuaJIT crashes when it calls a wrapped function. But you should return an from a integer function anyways, so it just encourages better code.