Monday, June 3, 2013

Script your Game with Lua

This is a video tutorial series, based on a presentation that I did recently at the Brisbane Game Technology Group.  Big shout out to Ash and the guys there for an excellent local tech meet up.

Its about how to add in support for scripting parts of your game in Lua.  I'm not here trying to teach how to code in Lua - there's other great talks about that.  This is also not a tutorial about how to write a game in Lua - which is something you can do these days, especially with frameworks like Corona.

This tutorial is however for you if you have a game written in Objective-C, or in C++, or possibly even a Unity game, and you want to know how to start using Lua snippets or scripts in your game.  You might want to do that because:

  • you have content creators working on your team who need to add game logic
  • you have text based assets that can use scripting to add functionality
  • you just don't want to have to implement everything in a compiled language
  • you want to add configurable behaviour to some game elements, like special AI
As a case study for this tut, I added some AI - albeit very simple chasing behaviours - to an open source tutorial project done by Viktor Lidholt, maintainer of the CocosBuilder project.  Viktor's excellent CocosDragon tutorial had just the right mix of content, so I did some improvements to it, and then used that as a base for adding in some unit AI, via Lua scripting.


The tutorial is presented in Objective-C for the iOS platform, but some of the techniques will trade over to other platforms.  Please let me know if you come up with a recipe for C# that is reliable and I'll reference it here.  There are sources out there for doing that, but I haven't been able to verify then.

To save you having to peer at the code on-screen, or type it in manually, I have made the whole tutorial available as a GitHub repo, so you can download it from:  The code for the tutorial can be downloaded from here: https://github.com/sarah-j-smith/LuaTut

The presentation was over an hour, so as a screencast with <10 minute YouTube segments its as a result in 8 parts - I have tried below to break these into functional components so you can go straight to the parts that interest you most.

But to get the full context, and to learn the knowledge behind the "do this, then do that" instructions it is a great idea to go through all the videos.  If you have some questions, or something does not make sense when you just skip to the video that sounds most interesting or relevant it may be because that content was in another section.

Part 1 - Intro, Context, Scope of Tut, Why Use Lua? - Security Issues



Part 2 - What's Covered?  What do you mean a "Lua API for my game"...?



Part 3 - Coding begins.  Showing the goal project with AI scripts.  Getting Lua inside.



Part 4 - LuaEngine class - the main integration point.



Part 5 - Lua Runtime, reading a config file



Part 6 - Beginning a scripting API for Lua to call into your game, embedding scriptlets



Part 7 - More scripting API, API registration and using full scripts for game objects


Part 8 - Implementing the rest of the API, review



I hope the material here is useful, and I would love to hear from you if you wind up integrating Lua into your game, or even just try out some of the ideas here.

I'd like to thank the folks that make their work available for free including Viktor Lidholt, and Ric Quesada - the guys behind CocosBuilder and Cocos2D-iphone; and also the authors of the free music and graphics (see the in-game credits or the github project for those).

Please let me know if you find any issues so I can fix them up.

Happy game hacking!