Welcome to Lua Scripting in Tabletop Simulator! Scripting is an advanced feature and it’s expected you already know something about it. However, for complete novices, check out this beginners scripting guide to Lua created by MrStump, to help you along the way.

A game is composed of one Global Script and zero to many Object Scripts. The Global Script is a script that lives in your game that can run background tasks and do general game management type functions. Object scripts are attached to an individual object. Objects are anything with a physical model in the game – chess piece, dice, decks, cards, bags, custom models, boards, etc. Both types of scripts can call the same functions, but Object scripts have access to a reference of the Object it is attached to with the self keyword.

Writing Lua Scripts

The Lua code is written via our in-game code editor or via our Official Plugin for the Atom Text Editor. Lua scripts are stored in the .json file of the save game as a plain text string. There is no need for an external internet host for Lua scripts, everything is self-contained in your game’s save file (Workshop uploads work the same way).

Official Atom Plugin

The preferred method of writing Lua scripts is using our Official Plugin for the Atom Text Editor. It has all of the functionality of the in-game editor plus line numbers, syntax highlighting, autocomplete, and a modern look.

TTS Lua Editor

You can access the in-game Lua Editor by clicking on Host -> Scripting or by right clicking on an object, choosing Scripting, and then selecting Lua Editor from the contextual menu. In the Lua Editor, the tabs on the left of the editor let you switch between the Global and the Object scripts. If you prefer coding in another environment, you can easily copy and paste your code into the in-game editor. To save the code, simply close the Lua Editor (save the game to commit the code to the save .json file). Once your Lua code is written, you can use the Save & Play button to commit your changes to your save file and reload for quick iteration. Save & Play will only commit your script changes, any changes made that weren’t scripting will be lost.

Example Mods


Chess Clock



Lua Standard Libraries

We include a subset of the Lua standard libraries into our interpreter to provide a safe sandbox for user scripts to run.

Basic – The basic methods. Includes assert, collectgarbage, error, print, select, type, tonumber, and tostring.
Bit32 – The bit32 package.
Coroutine – The coroutine package.
Dynamic – The dynamic package (introduced by MoonSharp).
ErrorHandling – The error handling methods: pcall and xpcall.
GlobalConsts – The global constants: _G, _VERSION, and _MOONSHARP.
Math – The math package.
Metatables – The metatable methods : setmetatable, getmetatable, rawset, rawget, rawequal, and rawlen.
OS_Time – The time methods of the os package: clock, difftime, date, and time.
String – The string package.
Table – The table package.
TableIterators – The table iterators: next, ipairs, and pairs.

For further information:
Official Lua Website

Default Events

We provide some default events that your scripts can subscribe to. See our API for a list of default events. To subscribe to a default event, just add the function to your script and it will be automagically be called if it exists. For example, the onLoad() function will be called when a game completely finishes loading.

Hello World of TTS Lua Scripting

function onLoad()
    print(‘Hello World!’)

This block of code can be added to the Global Script or any of the Object scripts. It will be called from each Script that you add it to. The print() function prints a message into the Chat window of the Host. The print() function should be used for debugging purposes.

Note: We provide access to the update() event; however, please be cautious when using this function (try to avoid using it altogether) because this function is called once per frame for every frame and can really impact performance if a computationally heavy operation happens (the frame will be delayed from rendering until this function ends). There are legitimate uses for the update() function so we provide it.

Other Scripting Articles:
Official Atom Text Editor Plugin
List of Spawnable Objects
Player Colors