From Blue Mars Developer Guidebook

This page is protected and certified by Avatar Reality Inc. Only Editable by Avatar Reality Staff Members.

Contents 1 Overview 1.1 Types 1.2 Operators 1.3 Math 1.4 Strings 1.5 Tables 1.6 Object-Oriented Lua 2 Resources 2.1 Converting from Linden Scripting Language 2.2 Official Lua Site 2.3 User Community 2.4 Online Articles 2.5 Books 2.6 Examples

Overview

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.

Types

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

Operators

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 ~=

Math

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

Strings

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

Tables

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
  print(key,value)
end

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
  print(i,v)
end

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");
                    end

can be written

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

or

GolfGame:OnUpdate(deltaTime)
  System.Log("golf update called");
end

where "self" is passed implicitly. Likewise,

mygolfgame.Start(mygolfgame);

is usually written

mygolfgame:Start();

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

Resources

Converting from Linden Scripting Language

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

Official Lua Site

http://www.lua.org/ contains official news, the reference manual, and source code.

User Community

http://www.lua-users.org/ is a community site with a FAQ, wiki, forum.

http://lua-users.org/wiki/TutorialDirectory is a good comprehensive introduction to Lua

Online Articles

Wikipedia has a good overview.

Online tutorials are available on DevMaster and OnLamp

Books

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

Examples

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.