Lua
TheoTown uses Lua 5.2 for plugin scripts. This topic introduces the language features you need to get started. For a complete reference, see the official Lua 5.2 manual. You can try examples that use only standard Lua in the online Lua demo. TheoTown-specific examples must run in the game.
Variables
Variables hold values. Use local to declare one and = to assign a value:
local a = 42 -- A number local b = 'Text' -- A string local c = 7.5 + a -- Another number local d = {} -- A table d.x = b -- Store b under the key x
-- starts a comment: Lua ignores the rest of that line. Strings can use single or double quotes. Numbers can have fractional parts.
Scopes
A variable's scope determines where it can be used. Lua has local variables, globals, and entries in tables:
local x = 42 -- Local to this part of the script y = 42 -- Global: no local declaration function foo(z) local result = x + z -- z is a local parameter; x is visible here return result end
A global can be accessed by other scripts. Prefer local for your own variables to avoid accidentally overwriting another script's values. A table entry, such as d.x, belongs to the table rather than being a separate global.
Locals declared inside a block are not visible after that block ends:
local answer if true then answer = 42 end print(answer) -- 42
If local answer were placed inside the if block, that variable would not be available afterward. Lua globals are stored in a special table behind the scenes.
Tables
A table stores values under keys. Create one with {}:
local t = {} t[42] = 7 t['xyz'] = 'ok' print(t[42]) -- 7 print(t.xyz) -- ok; same entry as t['xyz']
For string keys that are valid names, t.xyz is a convenient way to write t['xyz']. You can create a table with entries already in it:
local position = { x = 7, y = 8 } print(position.x) -- 7
A table can also act like a list. Items without explicit keys are numbered starting at 1:
local letters = { 'a', 'b', 'c' } print(letters[1]) -- a
Tables can contain other tables and keys of different types:
local data = { label = 'Town', position = { x = 7, y = 8 }, [42] = 'answer' } print(data.position.y) -- 8
This makes tables useful for both collections and structured data. A key with no value returns nil.
Functions
A function groups code that can be called later. Parameters receive values; return sends a value back:
local function add(x, y) return x + y end print(add(39, 3)) -- 42
Without an explicit return, a function returns nil. Functions are also values: you can store or pass them like any other value.
Global and local functions
function foo() ... end defines a global function. Other scripts can access or overwrite it, so prefer a local function for helpers used only by your script:
local function greet(name) print('Hello, '..name) end greet('Mayor')
A named function definition is shorthand for assigning a function value. For example, function foo(x) ... end is similar to foo = function(x) ... end.
Local functions must be declared before code that needs to refer to them. If two functions refer to each other, declare both names first:
local first, second first = function() second() end second = function() print('Called') end first()
Dot and colon functions
A table can hold functions:
local item = {} function item.show() print('Hi') end item.show()
Use : when the function needs access to the table itself. Lua passes the table as a first argument named self:
local counter = { value = 0 } function counter:inc(amount) self.value = self.value + amount end counter:inc(1) -- Equivalent to counter.inc(counter, 1) print(counter.value) -- 1
The dot and colon forms are interchangeable only when you supply the correct arguments. Follow the form used in the API documentation: Draft.getDraft(...) uses a dot, but a method on the returned draft uses a colon:
local draft = Draft.getDraft('$someid') if draft then local title = draft:getTitle() print(title) end
TheoTown callbacks such as function script:init() use a colon because they operate on the attached script.
Control structures
A condition is false only when its value is false or nil. In particular, 0, '', and the string 'false' are all true in Lua.
You can combine conditions with and, or, and not. Use == to compare for equality and ~= for inequality; <, <=, >, and >= compare ordered values. and and or return one of their operands, which is useful for choosing a fallback:
local name = suppliedName or 'Unnamed'
if
Use if to choose which code runs:
local x = 42 if x == 42 then print('yes') elseif x > 42 then print('larger') else print('smaller') end
Only the first matching branch runs. elseif and else are optional.
while
A while loop repeats as long as its condition is true:
local x = 1 while x <= 3 do print(x) -- 1, then 2, then 3 x = x + 1 end
Make sure something in the loop can make its condition false.
for
A numeric for loop has a start, end, and optional step. Lua includes the end value if the step reaches it:
for i = 0, 10, 2 do print(i) -- 0, 2, 4, 6, 8, 10 end
The loop variable i is local to the loop. To visit a table's keys and values, use pairs; it does not promise a particular order:
local scores = { north = 42, south = 7 } for key, value in pairs(scores) do print(key, value) end
For TheoTown Array objects, :forEach(function(item) ... end) is another way to visit elements.
do blocks
Use do ... end to group statements and keep their local variables inside that block:
do local temporary = 42 end print(temporary) -- nil, unless a global named temporary exists
The same rule applies to if and loop bodies. Declare a local before a block if you need to use it afterward.
Garbage collection
Lua automatically reclaims tables and other values when your script can no longer reach them:
for i = 1, 10000000 do local temporary = { x = i } end
The tables from earlier iterations are no longer needed, so Lua can free their memory. You usually do not need to manage memory yourself. Avoid keeping large tables in long-lived variables after you have finished using them.
Libraries
TheoTown's libraries, including City, Draft, and Drawing, are listed as Modules in the documentation. They are available by name in your scripts without a require statement.
Some standard Lua libraries are available too, although TheoTown restricts some operations. For their full API, see the Lua documentation index:
print(math.floor(7.8)) -- 7 print(string.upper('hello')) -- HELLO print(table.concat({'a', 'b', 'c'})) -- abc