Lua is a general purpose scripting language. It is well-known for having a small and fast implementation but a wide set of features including co-operative threading (co-routines), closures, self-style object orientation, and so on. Lua is more expressive and faster than all of the mainstream scripting languages and is used in many computer games.

It is used extensively for scripting objects and for defining maps and so on. A little knowledge of Lua can go a very long way whether you are a programmer, artist, or even user.

To learn Lua, read chapter 2 of http://www.lua.org/manual/5.2/(external link)


Lua is used in Grit with some modifications that make Lua code written for Grit incompatible with a regular Lua interpreter and regular Lua programs incompatible with Grit.

It should be possible to make any non-Grit Lua code work in Grit with minor modifications and the same performance. It is very unlikely that Grit Lua code will work outside of the customized Grit Lua VM.


All Lua files are UTF-8. The string class in Lua has been completely replaced by one that understands unicode. E.g. #"£" is 1, not 2. The most visible difference is that the syntax for regular expressions has changed. The new syntax is that of ICU's regular expression engine. For documentation, see sections "Regular Expression Metacharacters", "Regular Expression Operators" and "Replacement Text" on this page http://userguide.icu-project.org/strings/regexp(external link)

Support for 3d vectors and quaternions

For performance reasons, we cannot use userdata or tables for our vector3 and quat objects. Thus, the VM has been modified so that vector3 and quat are types just like 'number', 'boolean' and 'nil'. They are copied by value and are not garbage collected.

   Q_ID = quat(1,0,0,0)      -- constructing quaternions and 3d vectors
   V_ID = vector3(0,0,0)
   V_NORTH = vector3(0,1,0)
   V_EAST  = vector3(1,0,0)

   local v2 = vector3(1,2,3)
   print(v2*v2)                   -- pointwise multiplication
   print(dot(v2,v2))              -- dot product
   print(norm(v2))                -- normalise
   print(cross(V_NORTH,V_EAST))   -- cross product
   print(-v2)                     -- opposite direction, same length


   print(Q_ID * v2)

   local q2 = quat(180,vector3(0,0,1))
   print(q2 * v2)  -- transform a vector by a quaternion

   local q3 = Q_ID * q2 -- concatenate quaternion transformations
   print(q3 * v2)
   print(inv(q3) * q3 * v2)  -- invert a quaternion (only valid if #(q3)==1 approximately)

   print(v2==v2)  -- equality is pointwise on the elements

   print(#v2) -- length
   print(#q2) -- length (should be 1 for quaternions used to represent rotations)

   print(unpack(v2)) -- explode into x, y, z
   print(unpack(q2)) -- explode into w, x, y, z

   print(quat(90, vector3(0,0,1)) * (V_NORTH + V_EAST)) -- angle/axis constructor form
   print(quat(V_NORTH, V_EAST))                         -- quat between two direction vectors
   print(quat(V_NORTH, V_EAST) * V_NORTH)


NaN (Not a number)

If you divide by zero in regular lua, you get a NaN value that goes on to pollute other code, making debugging difficult. In Grit we instead trap the divide by zero with an error instead of returning NaN.

Category:File Formats?