Lua API

• Index

Contents

• Quick Start
• Architecture
• Lifecycle
• Debugging

Topics

• Introduction
• Lua

Modules

• Array
• Builder
• Building
• Car
• City
• DSA
• Debug
• Draft
• Drawing
• GUI
• NeighborCity
• Runtime
• Script
• TheoTown
• Tile
• Util
• Vector
• string

Introduction

The Lua integration for TheoTown plugins is quite powerful. Yet it also has a lot of complexity which yields the need for proper documentation. This introduction aims to provide you with the basic knowledge needed to get started. After that the documentation of the libraries will provide you with more information on specific topics.

Quick Start

Let's jump right into it by creating a basic plugin that uses a script. If you don't want to create and fill the needed files on your own you can download the example from here and extract it into your TheoTown/plugins folder.

To do it on your own create a folder called scripting test in the TheoTown/plugins folder. As you might already know plugins are defined by json files. This part remains the same while script functionality will be added afterwards. So create a file called test.json in the newly created scripting test folder. Fill this json file with the following content:

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

As for any object we have to provide a unique id to identify it. The type script is used for plugins that only consist of a script. I use it in this example to concentrate on the scripting part. Nontheless you can add scripts to any object. By doing so you can define object specific behavor e.g. a building that changes over time.

The script itself is provided by the name of a script file. Of course, we also have to create that file. So create a file called myscript.lua in the scripting test folder. You should now have the following file structure:

In order to "do something" let's fill the myscript.lua file with some code:

local counter = 0                  -- A counter variable

function script:init()
  Debug.toast('Hello World!')      -- A toast to indicate success during startup
end

function script:update()
  Drawing.setColor(0, 255, 0)      -- Change drawing color to green
  Drawing.drawText('This is frame '..counter, 30, 26)  -- Draw some text
  Drawing.setColor(255, 255, 255)  -- Reset color to white
  counter = counter + 1            -- Increase counter
end

This script does two things:

• Shows a toast at startup that says "Hello World!"
• While being in a city it shows a green text in the top left corner of the screen

As you can see this script does not interact with game objects at all. However, we will change that in future examples. It's noteworthy that the functions that are defined in the script above are called by the game. These are so called event functions as they are called by TheoTown upon certain events (e.g. script:init will be called on all scripts once all objects have been loaded).

Architecture

The main idea of scripts is to add functionality to the existing plugin system (namely json defined plugins). It's therefore an addition rather than a substitution so that you cannot define plugins without using json. To support that design drafts (plugin objects) can define which scripts should be appended to them. You can append multiple scripts to a single draft. It's also possible that a single script is appended to multiple drafts.

Since scripting is meant to be an addition to the existing plugin system you can create your plugins like before (json + graphics) and add scripts afterwards. It's noteworthy that scripting does not conflict with fun based actions so that you can use both at the same time for a draft. However, for clarity we recommend to only use one of the two techniques within a plugin.

In case you are already familiar with Lua note that TheoTown libraries don't require any require statements as Lua libraries usually do. You can just call them by their global name. The reason for this is simplicity as there are not many libraries and making it easier to get started with plugin scripting is definitely a good thing.

Lifecycle

This is how the lifecycle of a script basically looks like:

It basically consists of different states (like Loaded and In city). Transitions between these states can yield function calls in all scripts. These event functions are identified by their name and will be called by TheoTown automatically (if they are defined in your script). There are more event functions than that ones shown in the diagram above. You'll find all of them in the Script documentation.

Debugging

Debugging usually refers to the process of finding and fixing bugs in your code. Since the state of a Lua script is usually hidden from you the Debug library provides you with some functions to reveal the internal state of your script.

For example that may look like

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

to reveal the value of the local variable x. A toast in Android is a small message overlay that will be displayed above the app for some seconds. On iOS and desktop the game renders toasts on its own. Since toasts will be displayed one after another you should use them only for rare events (like the call of the init event function in the example). To display a continuous state of a script the Debug.info function is more appropriate. It will append the provided information to the debug overlay in the game that can be enabled in the game menu (if debug mode has previously been enabled in the settings).

Note that you can provide as many parameters as you like to the debug functions. The provided arguments will automatically be converted to strings and then concatenated together for display.