Skip to content

Types

Type refers to the type of information being used. You do not need to declare a type in Lua, but in this API you will see them indicated. This is only so you know what kind of information is required in a given variable/parameter. This API utilizes the following types.

Common Standards

Tag Type Description Example
nil No value. nil
int Non-decimal value. 5
float Non-exact decimal value. 2.032
bool true or false value. true
string A series of characters. "Hello."
table A container with keys and values. {["key"]="value", true, 5}
vector See section Vector for more info.
color See section Color for more info.
function See section Function for more info.
object An in-game physical Object. Sometimes Global. Global or self
player An in-game Player. See Player for more info. Player["White"]
variable A combination of other types.

See below for more info.

For more information on a type, you can read below or refer to the relevant Lua documentation.


Special Standards

Some types need to be used in specific ways. For Color and Vector, they are Tables that are used often in Tabletop Simulator. They represent Vectors and Colors, and their contents must be formatted a certain way to be utilized correctly.

For Functions, they are used when a delay is required within a running script that have specific requirements.

Color

Color is a type of Table that is used to define RGB values for tinting.

You can use the Color class to manipulate colors.

Keys

The Table will contain the keys r, g, b, a and/or 1, 2, 3, 4. The letter and numeric keys are duplicates of each other, and each represents a color or transparency.

Color Letter Key Number Key
red r 1
green g 2
blue b 3
alpha a 4

As an example, an Object with a white color tint would return this table:

{
    r=1, g=1, b=1,
    1=1, 2=1, 3=1,
}

Notice it does not contain the a or 4 keys. This is because currently only scripted buttons and scripted inputs utilize the alpha channel (transparency).

Mixed Keys

Only one type of key, number or letter, is required. If both a are present in a Table, the numeric key is ignored and only the letter key is used.

--Valid Table for red
{r=1, g=0, b=0}
--Valid Table for blue
{0, 0, 1}
--This Table would be red.
{r=1, g=0, b=0, 0, 0, 1}

Value

Values are between 0 and 1 for each key. If you are using RGB color that is in 0-255, you can use simple math to convert to the proper value.

--To display a color that is r=50, b=83, g=199
self.setColorTint({50/255, 83/255, 199/255})

Strings

You are also able to use a String in place of a color table. Using a Player Color will automatically fill in that value. It works with any of the 12 color names, as they are written on the Player Color page.

Example: printToAll("Test", "Green")


Vector

Vector is a type of Object with x, y, and z coordinates that is used to define a position, rotation or direction.

You can use the Vector class to manipulate vectors.

Example: target = Vector(1, 0, 0) + Vector(0, 2, 0):normalized()

Keys

The Table will contain the keys x, y, z and/or 1, 2, 3. The letter and numeric keys are equivalent.

Letter Key Number Key
x 1
y 2
z 3

As an example, An Object at coordinate X=5, Y=2, Z=-1 would return this Vector:

{
    x=5, y=2, z=-1,
}

Mixed Keys

Before Vector was introduced, coordinate tables contained separate values under 1, 2, 3 and x, y, z keys, with letter keys taking precedence when they were different. This is no longer the case, and using letter and numerical keys is equivalent. However, when iterating over Vector components you have to use pairs and only letter keys will be read there.

Value Range

The range of values depend on the type of Vector you are using.

Type Description Range
Position A point in space. Any number within the bounds of the world.
Rotation Angle, in degrees. -180 to 180.
Direction Vector direction. -1 to 1.

Type Details

Position

X is right/left, Y is up/down, Z is forward/back. A positional Vector can be either world or local. Most of Tabletop Simulator's functions use world positional Vectors.

Type Description
World The center of the instance is {x=0, y=0, z=0}. That is usually near the tabletop's center.
Local The center of the Object's model is {x=0, y=0, z=0}. The center of an Object is determined by the model's creator.
Conversion Between World/Local

positionToWorld(...) and positionToLocal(...) can be used to convert between the two types.

Rotation

X is pitch (nodding your head), Y is yaw (shaking your head), Z is roll (tilting your head).

Direction

X is right/left, Y is up/down, Z is forward/back.


Function

A function is a section of code that can be run when triggered. In Lua, you are able to pass (use as a parameter) functions. Some elements in Tabletop Simulator can be passed functions to perform some action with, like triggering it after a delay.

Usage

To pass a function, first you must create the function. There are multiple ways to do this:

--Create it on-the-fly
function() print("Like This") end

--Create it with a variable name
anyFuncName = function() print("Like This") end

--Create it with a variable name that can also be passed parameters
function anyFuncName(printString)
    print(printString)
end

Warning

You need to pass a function, not a result of a function. So this will not work:

Wait.frames(print("Ding"), 80)
Instead, make the print the result of a function running:
Wait.frames(function() print("Ding") end, 80)


Example

As an example, here is Wait.frames(...) used 3 times. It waits a set number of frames and then activates a given function:

function onLoad()
    --Built-in functions with parameters can be called directly
    --This is done by wrapping the function within `function()` and `end`
    Wait.frames(function() print("One") end, 60)

    --You can also call custom functions you have made yourself
    --Pass them any parameters you wish
    Wait.frames(function() sayTwo("Two") end, 120)

    --If you aren't passing any parameters to the function, you can shorten it
    Wait.frames(sayThree, 180)
end

--Has its parameter passed to it
function sayTwo(s) print(s) end

--Does not have any parameters passed to it
function sayThree() print("Three") end