Lua Language Cheat Sheet

Scripting in Simmetri is based on the Lua language. With a few exceptions, it's syntactically very similar to JavaScript. Here's an informal overview of Lua's syntax to get a quick sense of the language:

Comments

-- Single-line comments begin with a '--'
--[[ Multi-line 
	Comments ]]--

Assignments

v = 1 -- Number (integral or real)
s = "funky" -- String
b = true -- Bool
n = nil -- Empty or unassigned value
f = function(x,y) return x+y end -- Function
t = {} -- Table/array
t[1] = 1 -- Indexed Table element access 
t.x = 2 -- Indexed string Table element access

Note, there is no explicit type declaration for variables. Variable types are defined on assignment.

Comparison

== -- equals
~= -- not equals
< -- less than
> -- greater than
<= -- less than or equals
>= -- greater than or equals

Logical

and
or
not

Arithmetic

v = 1 + 2 -- addition
v = 1 - 2 -- subtraction
v = 1 * 2 -- multiplication
v = 1 / 2 -- division
v = 4 % 2 -- modulo division (remainder) 
v = 2 ^ 16 -- exponentiation
v = -5 -- unary negation

str = "Hello " .. "world" -- string concatenation

tbl = {1,2,3} 
v = #tbl -- The # operator returns the total number of items in a numerically indexed table (3 in this case)

If Statements

if v == 1 then
	-- do something
end

if s == "friend" or s == "relative" then
	-- do something nice
elseif s == "enemy" then
	-- do something mean
else
	-- awkwardly look away
end

Loops

for i=1,10 do
	-- Do something 10 times
end
-- Follows the form: for (var, <=limit [,step=1] ) do

t = {}
t[1] = "evil"
t[2] = "evil"
t[3] = "nice"
t[4] = "extra evil"

for k,v in pairs(t) do
	if v == "nice" then
		-- k would be 3 here
		break
	end
end

while e==nil do
	-- Keep looping until e is something
end

repeat
	-- Keep looping until e is something
until e ~= nil

Functions

function MyFunction(v1, v2)
	return v1 + v2
end

Calling Functions

v = MyFunction(1, 2)
-- calling member functions (note the ':' notation)
n = obj:getName()

Properties

-- Direct property value access (lowercase property name)
obj.active = true
-- Property object accessor (Uppercase property name)
obj:getActiveProperty():setValue(true)

Additional Built-in Types

v = vector2(x,y) -- 2 component vector
v = vector3(x,y,z) -- 3 component vector
v = vector4(x,y,z,w) -- 4 component vector
m = matrix() -- 4x4 row/column matrix (defaults to an identity matrix)
t = milliseconds(ms), seconds(s), minutes(m), hours(h) -- time
s = sphere(point, radius) -- sphere represented by a point and a radius
b = box(min, max) -- axis-aligned box represented by a min and max point
p = plane(a,b,c,d) -- a plane defined by the equation ax+by+cz+d=0
r = ray(point, direction) -- a ray define by a point and a normalized direction
s = segment(point1, point2) -- a segment defined by two points
q = quaternion(x,y,z,w) -- a quaternion to represent rotations about an axis
c = rgba("ff0084") -- returns a vector4 color from an rgba hex color
c = rgba(255,0,132,255) -- returns a vector4 color from 32bit rgba color values
c = hsb(180,0.5,1) -- returns a vector4 color from hue/saturation/brightness values H[0,360] S[0,1] B[0,inf]
b = exists(obj) -- returns true if the given object is valid or false if it's nil or the object has been deleted
n = noise(v) -- where v is a 1/2/3d value, returns a smoothed random value [-1,1] across the given dimensions

Some Useful Built-in Functions

type(obj) -- This function will return a string identifying a Lua type (i.e. "number"), additional built-in type (i.e. "vector3"), or Simmetri object type (i.e. "MeshEntity")
tostring(obj) -- converts a type to a string representation (e.g. "true", "23.0", "x:3 y:4 z:2", etc) 
tonumber(n) -- converts a string to numeric value 
print("msg") -- prints a message to the console 
error("msg") -- stops play and breaks at the line with the given error message
assert(cond [,"error msg"]) -- verifies the condition is true or breaks at the line with the given error message

Please refer to the online Lua manual for a more detailed look at the language: http://www.lua.org/manual/5.2