Lua API

• Index

Contents

• Functions

Modules

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

Topics

• Introduction
• Lua

Module TheoTown

TheoTown specific functions that don't fit into other libraries.

Functions

execute (cmd, receiver)	Executes a command as if it was entered into the console.
formatMoney (amount[, signed=false])	Formats a number a an amount of money and appends the Theon symbol.
formatNumber (amount[, signed=false[, abbreviate=true]])	Formats a (big) number.
getDiamonds ()	Returns the number of diamonds that the user currently has.
getFileStorage ()	Returns a game wide storage table that's backed by an actual file.
getGlobalFunVar (name[, fallbackValue])	Returns the value of the global fun variable of the given name or fallbackValue if no such variable has been defined, yet.
getPlayTime ()	Returns the play time in the game in seconds.
getStorage ()	Returns a game wide storage table.
getUserName ()	Returns the name of the current logged in user or nil if the player is not logged in.
isMultiplayer ()	Returns true iff this version of the game is capable of running multiplayer mode.
isRTL ()	Returns true if the currently selected language prefers a right to left layout.
loadCity (path[, overwrite[, private[, target]]])	Loads a city file provided by the plugin.
playSound (sound[, volume=1[, loop=false]])	Plays a sound.
registerCommand (name, action)	Registers a function that can then by called from console.
setGlobalFunVar (name, value)	Sets the value of a global fun variable called name.
spendDiamonds (amount)	Spends amount diamonds if possible.
translate (id)	Translates an id into the corressponding string.
translateInline (str)	Resolves the translation of an inline translation string.

Functions

execute (cmd, receiver)

Executes a command as if it was entered into the console.

New feature:

This is a new feature that was added in version 1.9.82

Parameters:

• cmd string The command to execute.
• receiver function A function with one parameter that will be called for any feedback.

formatMoney (amount[, signed=false])

Formats a number a an amount of money and appends the Theon symbol. Optionally prefixes a + sign for positive numbers if signed is set to true.

New feature:

This is a new feature that was added in version 1.11.04

Parameters:

• amount number The amount of money to format.
• signed boolean If set to true the plus sign may be prefixed. (default false)

Returns:

string The formatted money.

formatNumber (amount[, signed=false[, abbreviate=true]])

Formats a (big) number. Optionally prefixes a + sign for positive numbers if signed is set to true.

New feature:

This is a new feature that was added in version 1.11.04

Parameters:

• amount number The number to format.
• signed boolean If set to true the plus sign may be prefixed. (default false)
• abbreviate boolean Set this to false to not abbreviate. (default true)

Returns:

string The formatted number.

getDiamonds ()

Returns the number of diamonds that the user currently has.

Returns:

number Amount of diamonds that the user currently has.

getFileStorage ()

Returns a game wide storage table that's backed by an actual file. The file will even persist if the user deleted the game. Only a deletion of the TheoTown folder will reset this storage.

Returns:

table Persistent game wide storage table.

getGlobalFunVar (name[, fallbackValue])

Returns the value of the global fun variable of the given name or fallbackValue if no such variable has been defined, yet. fallbackValue is 0 by default. Note that fun variables can only contain numbers. Use City.getStorage() or TheoTown.getStorage() to store more fancy stuff. Global fun variables are indicated by a leading ! in their name.

Parameters:

• name string
• fallbackValue number (optional)

Returns:

number Value of the variable or the fallback value

getPlayTime ()

Returns the play time in the game in seconds.

Returns:

number Play time in seconds.

getStorage ()

Returns a game wide storage table. Use it to save data permanently across all cities.

Returns:

table Game wide storage table.

getUserName ()

Returns the name of the current logged in user or nil if the player is not logged in.

Returns:

string Name of the current user or nil if the player is not logged in.

isMultiplayer ()

Returns true iff this version of the game is capable of running multiplayer mode.

Returns:

bool Whether the game is capable of running multiplayer mode or not.

isRTL ()

Returns true if the currently selected language prefers a right to left layout.

New feature:

This is a new feature that was added in version 1.12.23

loadCity (path[, overwrite[, private[, target]]])

Loads a city file provided by the plugin. path is the file of the city file (thus it includes the .city file ending). Prior to loading the city will be copied to maps or private maps folder first (depending on private value). If a city of similar file name already exists at that directory it will be overridden if overwrite flag is set. The target file name can be changed by specifieing a target name.

New feature:

This is a new feature that was added in version 1.9.82

Parameters:

• path string
• overwrite bool (optional)
• private bool (optional)
• target string (optional)

playSound (sound[, volume=1[, loop=false]])

Plays a sound.

Parameters:

• sound draft A sound draft or id of a sound draft.
• volume number A value between 0 and 1. (default 1)
• loop boolean Whether or not to loop the sound. (default false)

Returns:

table A table that contains functions to control the sound.

registerCommand (name, action)

Registers a function that can then by called from console. Instead of a name you can provide a function that returns true for commands the second function should handle.

Parameters:

• name string or function
• action function A function that will be called when the command got entered.

Usage:

TheoTown.registerCommand('test', function(name, arg)
  return arg  -- Will be displayed as result
end)

setGlobalFunVar (name, value)

Sets the value of a global fun variable called name. Note that fun variables can only contain numbers. Use City.getStorage() or TheoTown.getStorage() to store more fancy stuff. Global fun variables are indicated by a leading ! in their name.

Parameters:

• name string
• value number

spendDiamonds (amount)

Spends amount diamonds if possible.

Parameters:

• amount number

Returns:

bool Whether spending was successful.

translate (id)

Translates an id into the corressponding string. Instead of TheoTown.translate('key') you can write Translation.key for convenience.

Parameters:

• id string The ID of a translation to translate.

Returns:

string The translation.

translateInline (str)

Resolves the translation of an inline translation string. Such a string may look like "default[de]German[fr]French...". The result will be the appropriate part based on language settings.

Parameters:

• str string A packed string to prick a translation from.

Returns:

string The picked translation.