Typescript Declarations for Tabletop Simulator

Hello! These types are intended to be used with Typescript to Lua. With that compiler you can transpile .ts files into .lua files. This package is the safety net for the Tabletop Simulator functions and objects. Let your editor have some nice autocompletion!.

Usage

1. Install these packages and make a src directory:

npm i tts-types typescript typescript-to-lua
mkdir src

2. Create tsconfig.json:

{
  "compilerOptions": {
    "rootDir": ".",
    "outDir": "build",

    "target": "ESNext",
    "lib": ["ESNext"],
    
    "moduleResolution": "nodenext",
    "module": "NodeNext",

    "declaration": false,
    "declarationMap": false,

    "strict": true,
    "types": ["tts-types"],
  },
  "tstl": {
    "luaTarget": "5.2",
    "noImplicitSelf": true,
    "tstlVerbose": true,
    "luaBundle": "bundle.lua",
    "luaBundleEntry": "src/index.ts",
  },
}

note: we use "luaTarget": "5.2" to be compatible with the LUA version Tabletop Simulator uses.

3. Create src/index.ts

// The onLoad function. This is called after everything in the game save finishes loading.
// Most of your script code goes here.
(globalThis as any).onLoad = (saveData: string) => {

  // Lock color-UI cube
  const cube = getObjectFromGUID("c1a0d1");
  if (cube) {
    cube.interactable = false;
    cube.setLock(true);
  }
};

Global event functions

Tabletop Simulator finds event functions such as onLoad, onUpdate and onObjectEnterContainer by looking them up on the Lua global table. TypeScriptToLua emits a top level function onLoad() {} as local function onLoad(), which the game never sees, so nothing runs. Assign event functions to globalThis instead, as above. TypeScriptToLua turns globalThis into _G, which is exactly where the game looks. The cast to any is needed because these types do not declare the event functions, and getObjectFromGUID can return undefined, so check the result under strict.

4. Your project is ready! run npx tstl to compile it into Lua

npx tstl

You will have some output like this:

Loaded 0 plugins
Parsing project settings
Transforming C:/Source/tts-test/src/index.ts
Printing C:/Source/tts-test/src/index.ts
Constructing emit plan
Resolving dependencies for C:/Source/tts-test/src/index.ts
Emitting output
Emitting C:/Source/tts-test/build/bundle.lua
Emit finished!

Your .lua file now exists at build/bundle.lua:

--[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]

local ____modules = {}
local ____moduleCache = {}
local ____originalRequire = require
local function require(file, ...)
    if ____moduleCache[file] then
        return ____moduleCache[file].value
    end
    if ____modules[file] then
        local module = ____modules[file]
        local value = nil
        if (select("#", ...) > 0) then value = module(...) else value = module(file) end
        ____moduleCache[file] = { value = value }
        return value
    else
        if ____originalRequire then
            return ____originalRequire(file)
        else
            error("module '" .. file .. "' not found")
        end
    end
end
____modules = {
["src.index"] = function(...) 
--[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]
local ____exports = {}
_G.onLoad = function(saveData)
    local cube = getObjectFromGUID("c1a0d1")
    if cube then
        cube.interactable = false
        cube.setLock(true)
    end
end
return ____exports
 end,
}
local ____entry = require("src.index", ...)
return ____entry

I use this to copy it in automatically (package.json):

"scripts": {
    "compile": "tstl && npm run deploy",
    "deploy": "copy \"build\\bundle.lua\" \"%LOCALAPPDATA%\\Temp\\TabletopSimulator\\Tabletop Simulator Lua\\Global.-1.lua\""
}

So I can simply use npm run compile

Contributing (TODO)

• Finish tests
• Create example projects

Development

1. Clone
2. npm install
3. npm run build to build the project
4. npm run test to run tests