Tabletop Simulator Lua Scripting API

The Tabletop Simulator API provides several XML elements for grouping and positioning UI components. These elements allow for uniform padding, easy movement of groups, and organized visual structures.

Layout Elements

• <Panel>: A container window for confining elements.
• <HorizontalLayout>: Arranges elements in a horizontal row.
• <VerticalLayout>: Arranges elements in a vertical column.
• <GridLayout>: Arranges elements in a grid.
• <TableLayout>: An HTML-table-like layout using <Row> and <Cell> for specific positioning.

Scroll View Elements

• <HorizontalScrollView>: A scrollable horizontal row.
• <VerticalScrollView>: A scrollable vertical column. Note that these are considered input elements.

The official plugin provides several developer-focused features:

• Syntax Highlighting: Full support for standard Lua syntax.
• Code Autocompletion: Provides autocompletion for the entire Tabletop Simulator Lua Scripting API (excluding the Player class). It includes member variables, functions, parameters, return types, and descriptions. It also links to the official Lua documentation for standard library classes like math, coroutine, or os.
• Direct Integration: Syncing scripts via Get Lua Scripts and Save & Play commands.

Attributes are modifiers applied to individual elements or groups of elements to control their behavior and appearance. Every attribute consists of two parts: a tag and a value.

Crucial Rule: The value must always be enclosed in quotation marks.

The Turns static global class manages the in-game turns system. It provides functionality to control turn order, rotation direction, and player interaction restrictions, mirroring the behavior of the in-game Turns menu.

To manipulate the turn system, you can modify its member variables or call its methods. For example, to reverse the direction of turn rotation, set Turns.reverse_order = true.

-- Example: Reverse the turn rotation direction
Turns.reverse_order = true

The Vector class represents 3D positions and directions. It is one of the first classes defined in pure Lua, which imposes a critical requirement: you must use the colon operator (:) to call member functions (e.g., pos:angle()) instead of the dot operator (.). Using the dot operator for member functions will result in cryptic errors.

Key usage notes:

• Implicit Instances: Any function returning a coordinate table (like obj.getPosition()) already returns a Vector instance; you do not need to wrap it in Vector().
• Constructor Shorthand: You can omit .new when creating vectors (e.g., Vector(1, 2, 3) is equivalent to Vector.new(1, 2, 3)).
• Chaining: Many methods return the Vector instance itself, allowing you to chain operations like vec:setAt('y', 0):scale(0.5).

#!lua target = Vector(1, 0, 0) + Vector(0, 2, 0):normalized()

To script effectively in Tabletop Simulator, you must understand its core abstractions:

• Object: A physical in-game entity currently in the scene. Note that objects inside containers (bags, decks, etc.) do not exist in the scene and cannot be interacted with until they are pulled out.
• Player: Represented by the color of the seat they occupy. Spectators are identified as Grey.
• Global Script: The single, persistent script that exists for every game/save and is not attached to any specific object.
• Object Scripts: Scripts attached to specific Object instances. You can create or edit these via an object's context menu (right-click).
• GUID: A unique 6-character string used to identify Object instances. GUIDs are assigned when objects enter the scene.

The Time class is a static global class used to access Unity's time information. It should not be confused with the deprecated Timer class. Use Time for high-accuracy timing and frame-based calculations within your scripts.

Time.time

The Timer is a static global class used to execute functions after a specific delay or repeatedly.

Important Constraints:

• Unique Identifiers: Every timer requires a unique identifier string. These identifiers are shared across the Global script and all Object scripts. If two timers share a name, they will conflict.
• Collision Prevention: A recommended way to ensure uniqueness for timers attached to specific objects is to use the object's GUID as the identifier.
• Lifecycle: Timers automatically destroy themselves once they have completed their specified number of repetitions.

The Backgrounds global allows you to inspect and modify the current background in Tabletop Simulator. You can retrieve the current background's name or URL, and switch to a different background using either a built-in name or a custom image URL.

#!lua Backgrounds.getBackground()

To use custom content in Tabletop Simulator, you can first spawn a generic custom object and then provide its specific content (like images or meshes) by calling setCustomObject().

If you need to update an existing custom object with new content, you can use setCustomObject() in conjunction with reload() to apply the changes.