Introduction

TheoTown plugins can use Lua scripts to react to game events, draw on the screen, and add behavior to plugin objects. This guide walks through a small script plugin. If you are new to Lua, the Lua topic explains the language basics; the library reference covers TheoTown's available functions.

Quick Start

Create the plugin folder

Create a folder named scripting test inside TheoTown/plugins. You can also download the example plugin and extract it there instead of creating the files yourself.

Define the plugin object

Create test.json in the scripting test folder:

[{
    "id": "$scriptingtest00",
    "type": "script",
    "script": "myscript.lua"
}]

The id must uniquely identify this plugin object. The type makes it a script-only object, and script names the Lua file to load. Plugins still need a JSON definition: Lua adds behavior to the plugin system rather than replacing it. You can also attach scripts to other objects, such as buildings.

Add the Lua script

Create myscript.lua in the same folder. Your files should now be arranged like this:

File structure

Put the following code in myscript.lua:

local counter = 0

function script:init()
  Debug.toast('Hello World!')
end

function script:update()
  Drawing.setColor(0, 255, 0)
  Drawing.drawText('This is frame '..counter, 30, 26)
  Drawing.setColor(255, 255, 255)
  counter = counter + 1
end

Start TheoTown with the plugin installed and open a city. The script displays a Hello World! toast after loading. In the city, it draws green text near the top-left corner and changes the counter every frame.

script:init() and script:update() are event functions, also called callbacks. You define them; TheoTown calls them at the appropriate times. You do not need to call them yourself. The Script documentation lists the other callbacks.

Architecture

Architecture

A JSON-defined plugin object is called a draft. A draft can have multiple scripts, and the same script can be attached to multiple drafts. This lets you add behavior to existing plugins that already have JSON definitions and graphics.

Scripts can coexist with fun-based actions, although using one approach consistently within a plugin is generally easier to follow. TheoTown's Lua libraries, such as Drawing and Debug, are available by their global names: you do not need to write require statements for them.

Lifecycle

The diagram shows the main states a script passes through:

Lifecycle

When the game changes state—for example, when it finishes loading or enters a city—it may call one of your script's event functions. Other callbacks run for specific game events or on every frame. Define only the callbacks your script needs. See the Script documentation for the full list and their arguments.

Debugging

The Debug library helps you inspect values while your script runs:

local x = 42

function script:init()
  Debug.toast('The value of x is', x)
end

function script:update()
  Debug.info('The value of x is still', x)
end

Debug.toast() shows a brief message. On Android this is a system toast; on iOS and desktop the game draws the message itself. Toasts appear one after another, so use them for occasional events rather than every frame.

Debug.info() writes to the in-game debug overlay and is better for values you want to watch continuously. Enable debug mode in the settings, then turn on the debug overlay from the game menu. Both debug functions accept multiple values and convert them to text for display.

generated by LDoc 1.4.3 Last updated 2026-11-20 13:32:29