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

generated by LDoc 1.4.3 Last updated 2026-11-19 19:33:48