Lua Programming

From Blue Mars Developer Guidebook

Jump to: navigation, search
There are security restrictions on this article



Lua is the scripting language used in CryEngine to customize missions, game rules, AI behaviors, and entities. These articles focus on implementing Entity Scripts for minigame development. The version of Lua used in Blue Mars is Lua 5.1.


Lua's popularity as a game scripting language is due to its simplicity and small footprint. Lua has a few primitive data types, including:

  • string
  • number
  • boolean

and one aggregate type:

  • table


Most of the math expressions in Lua are the same as in other programming languages. Some exceptions:

The logical operators are and, or, and not.

String concatentation is performed with ..

# is the length operator for strings and tables.

The numeric not-equal check is performed with ~=


Additional math operations are provided by the Lua math library and CryEngine Lua Utilities. CryEngine provides additional support for vectors.


Additional string operations, such as formatting and pattern matching, are available in the standard Lua string library


Tables are the only aggregate type in Lua. A table is a collection of key-value pairs.

mytable = { name="Bob", age=25 }

Note that the entries are separated by commas. The "name" field can be accessed by name.field or name[field]

You can iterate through a table with pairs.

for key,value in pairs(mytable) do

Tables can also implement arrays.

myarray = { "Bob", "Judy", "Carlos" }

Arrays are really tables with implicit numeric keys.

Note that unlike many other programming languages, array indices in Lua begin with 1. So myarray[1] is "Bob".

You can iterate through an array with ipairs.

for i,v in ipairs(myarray) do

Additional table operations are available in the standard Lua table library.

Object-Oriented Lua

Lua also uses tables to support an object-oriented style of programming. Classes are implemented as tables, member variables are implemented as key-value pairs in the table, member functions (or methods) are also key-value pairs, where the values are functions.

Some syntactic sugar facilitates this. The function definition:

GolfGame.OnUpdate = function(self,deltaTime)
                       System.Log("golf update called");

can be written

     System.Log("golf update called");


  System.Log("golf update called");

where "self" is passed implicitly. Likewise,


is usually written


See this object orientation tutorial for a more complete explanation, and Entity Scripts for examples of how this is used in CryEngine.


Converting from Linden Scripting Language

We have a brief guide to converting from LSL to Lua.

Official Lua Site contains official news, the reference manual, and source code.

User Community is a community site with a FAQ, wiki, forum. is a good comprehensive introduction to Lua

Online Articles

Wikipedia has a good overview.

Online tutorials are available on DevMaster and OnLamp


Programming in Lua is online (first edition) and the second edition is available for purchase:

Game Scripting Mastery and Core Techniques and Algorithms in Game Programming have chapters on Lua.

Game Programming Gems volumes 5-7 have articles on integrating Lua into game engines.

Game Development with Lua


All Lua source code (CryEngine does not load compiled Lua files), including CryEngine Lua Utilities, Entity Scripts, Avatar Reality Utilities and Minigames can be found in the directory Game/Scripts.

Problems with this wiki page? Contact us either by: Support Email or Support Ticket System

Blue Mars Guidebook Privacy Policy
Blue Mars Guidebook Community Guidelines

Personal tools