Introduction
In this section, you will find details on all events/classes/functions specific to Tabletop Simulator's Lua scripting. For more general information on how the scripting language of Lua works and what it does on its own, you can review the Official Lua Documentation.
Using the API Documentation¶
Left Column¶
This is the top-level list of classes and other information needed when scripting with Lua in Tabletop Simulator. Event, Base and Object are the three pages you will use the most, with the rest referring to niche information you can access as you go. It is a good idea to familiarize yourself with the contents of those three pages in order to have a good high-level understanding of what scripting is capable of doing.
Right Column¶
The Table of Contents will lay out the contents of the page you are on. It always starts with high-level summary information first and, if needed, detailed information towards the bottom. The next to a summary element will take you directly down to the relevant detailed explanation below.
Improving the Documentation¶
This documentation is predominantly written in Markdown and is available on Github.
If you encounter a mistake, and it's something you're able to fix yourself, then pull requests are welcome. However, if you've identified a problem, but don't know how to fix it, please let us know by opening an issue.
Tabletop Simulator Terminology¶
Object¶
An in-game physical Object that currently exists in the scene. If an Object is placed inside of a bag/deck/etc, it stops existing and is no longer in the scene until it is pulled back out.
Player¶
A person in the game. Each Player is assigned a color, with spectators being "Grey". If you are attempting to identify a Player, you would use the color of the seat they are in to do so.
Global Script¶
Each game/save has a Global script, which is not attached to any particular Object.
There is only one Global script, and it is always present.
Object Scripts¶
Every in-game Object may also have a script attached to it.
By default, newly created Objects do not have a script attached. However, you can choose to create/edit an Object's script from the Object's context menu (typically opened by right-clicking on the Object).
GUID¶
In Tabletop Simulator, a GUID is a unique 6-character string which can be used to identify in-game Objects. GUIDs are automatically assigned when objects exist within the scene.
If an object is duplicated, it will sometimes have the same GUID for 1 frame before the engine assigns a new GUID to the newer Object. Objects in containers (bags/decks/etc) do not automatically get new GUIDs assigned to them in this way. Only once their contents are moved out into the scene.
Custom Deck Card GUIDs
When you first create a custom deck, all cards within the deck share the same GUID. If you need to reference individual GUIDs of cards, then the way to solve this is to lay out all cards from the deck at the same time to allow new GUIDs to be assigned by the game. This tool can be used to simplify the process.
Deprecated APIs¶
Through-out this documentation you may come across Lua APIs that are labelled as . It is advised that you no longer use deprecated APIs. Typically, this is because newer/improved APIs have been introduced that better serve the same purpose.
Deprecated APIs will not be removed or stop working.
Existing mods may continue to use deprecated functionality without issue. It is however strongly recommended, that for the best experience you avoid use of deprecated APIs in new code.