Skip to content

Base

These are a loose collection of functions which can be used to perform a variety of actions within Tabletop Simulator. Some of them are used in almost every script.

Function Summary

Global Functions

General functions which work within any function.

Function Name Description Return  
clearPixelPaint() Remove pixel paint from the instance.
clearVectorPaint() Remove vector paint from the instance.
copy( object_list) Copy a list of Objects to the clipboard. Works with paste(...).
destroyObject( obj) Destory an Object.
flipTable() Flip the table.
getAllObjects() Returns Table of all spawned Objects in the game.
getNotes() Returns the contents of the on-screen notes section.
getObjectFromGUID( guid) Returns Object by its GUID. Will return nil if this GUID doesn't currently exist.
getSeatedPlayers() Returns Table of the Player Colors strings of seated players.
paste( parameters) Pastes Objects in-game that were copied to the in-game clipboard. Works with copy(...).
setNotes( notes) Replace the text in the notes window with the string.
spawnObject( parameters) Spawns an Object. View the Spawnable Object page for Objects that can be spawned.
spawnObjectJSON( parameters) Spawns an Object using a JSON string. Works with getJSON().
startLuaCoroutine( function_owner,  function_name) Start a coroutine.
stringColorToRGB( player_color) Converts a Player Color string into a Color Table for tinting.

Message Functions

Functions which handle sending and displaying data.

Function Name Description Return  
broadcastToAll( message,  message_tint) Print an on-screen message to all Players, as well as their in-game chat.
broadcastToColor( message,  player_color,  message_tint) Print an on-screen message to a specified Player, as well as their in-game chat.
log( element,  label,  tag) Print information to the log tab. (Shortcut: ~)
logStyle( tag,  tint,  prefix,  postfix) Set style options for the specified tag type for the log.
print( message) Prints a string into chat that only the host is able to see. Used for debugging scripts.
printToAll( message,  message_tint) Print a message into the chat of all connected players.
printToColor( message,  player_color,  message_tint) Print a message to a specific Player Color.
sendExternalMessage( data) Send a table to your external script editor, most likely Atom. This is for custom editor functionality.

Notebook Functions

Functions that interact with the in-game notebook tabs.

Function Name Description Return  
addNotebookTab( parameters) Adds a notebook tab, returning its index.
editNotebookTab( parameters) Edit an existing Tab in the notebook.
getNotebookTabs() Returns Table containing data on all tabs in the notebook.
removeNotebookTab( index) Remove a notebook tab.

Function Details

Global Function details

copy(...)

 Copying a list of Objects the clipboard. Works with paste(...).

copy(object_list)

  • object_list: A Table of in-game objects to be copied.
    • This is similar to highlighting the objects in-game and copying them.
object_list = {
    getObjectFromGUID("######"),
    getObjectFromGUID("######"),
}
copy(object_list)

destroyObject(...)

 Destroy an Object.

destroyObject(obj)

  • obj: The Object you wish to delete from the instance.

getObjectFromGUID(...)

 Returns Object by its GUID. Will return nil if this GUID doesn't currently exist.

getObjectFromGUID(guid)

  • guid: GUID of the Object to get a reference of.
    • GUID can be obtained by right clicking an object and going to Scripting.
    • In a script, it can be obtained from any Object by using .getGUID().

paste(...)

 Pastes Objects in-game that were copied to the in-game clipboard. Works with copy(...).

paste(parameters)

  • parameters: A Table containing instructions of where to spawn the Objects.
    • parameters.position: Position of the first object to paste.
      • Optional, defaults to {0, 3, 0}.
    • parameters.snap_to_grid: If snap-to-grid is active on the spawned item/s.
      • Optional, defaults to false (off).

setNotes(...)

 Replace the text in the notes window with the string. The notes is an area which displays text in the lower-left corner of the screen.

setNotes(notes)

  • notes: What to place into the notes area.
setNotes("This appears in the notes section")

spawnObject(...)

 Spawn an Object. View the Spawnable Objects page for Objects that can be spawned.

If you are spawning a custom Object, you should call setCustomObject immediately after spawnObject to set its custom properties.

Tip

Spawned Objects take a moment to be physically spawned into the game. The purpose of the callback functionality is to allow you to run additional actions after the Object has been initiated fully into the instance.

spawnObject(parameters)

  • parameters: A Table of parameters used to determine how spawnObject will act.
    • parameters.type: Spawnable Object type.
    • parameters.position: Position to place Object.
      • Optional, defaults to {x=0, y=3, z=0}.
    • parameters.rotation: Rotation of the Object.
      • Optional, defaults to {x=0, y=0, z=0}
    • parameters.scale: Scale of the Object.
      • Optional, defaults to {x=1, y=1, z=1}
    • parameters.sound: If the spawned Object noise is played.
      • Optional, defaults to true.
    • parameters.snap_to_grid: If snap-to-grid is active on the Object.
      • Optional, defaults to false.
    • parameters.callback: Name of the function you want activated once the Object is initiated.
      • Optional, no callback is triggered without it.
      • A callback function has 2 parameters, the Object spawned and, if used, the Table of params.
    • parameters.callback_owner: Which Object has the callback function on it. Global is a valid target as well.
      • Optional, defaults to Global. Serves no purpose if callback is not also used.
    • parameters.params: A Table of data to send to the callback to use as parameters. See example.
      • Optional, default is to not be used.
function onLoad()
    futureName = "Spawned By Script!"
    spawnParams = {
        type = "rpg_BEAR",
        position       = {x=0, y=3, z=-5},
        rotation       = {x=0, y=90, z=0},
        scale          = {x=2, y=2, z=2},
        sound          = false,
        snap_to_grid   = true,
        callback       = "spawn_callback",
        callback_owner = Global,
        params         = {name = futureName}
    }
    spawnObject(spawnParams)
end

function spawn_callback(object_spawned, params)
    object_spawned.setName(params.name)
    object_spawned.setColorTint({r=0,g=1,b=0})
end

spawnObjectJSON(...)

Spawns an Object using a JSON string. Works with getJSON(). It works just like spawnObject, but instead of a type, you supply a json string. The other parameters will overwrite those in the JSON.

Tip

Spawned Objects take a moment to be physically spawned into the game. The purpose of the callback functionality is to allow you to run additional actions after the Object has been initiated fully into the instance.

spawnObjectJSON(parameters)

  • parameters: A Table of parameters used to determine how spawnObjectJSON will act.
    • parameters.json: getJSON() string.
    • parameters.position: Position to place Object.
      • Optional, defaults to JSON's value.
    • parameters.rotation: Rotation of the Object.
      • Optional, defaults to JSON's value.
    • parameters.scale: Scale of the Object.
      • Optional, defaults to JSON's value.
    • parameters.sound: If the spawned Object noise is played.
      • Optional, defaults to JSON's value.
    • parameters.snap_to_grid: If snap-to-grid is active on the Object.
      • Optional, defaults to JSON's value.
    • parameters.callback: Name of the function you want activated once the Object is initiated.
      • Optional, no callback is triggered without it.
      • A callback function has 2 parameters, the Object spawned and, if used, the Table of params.
    • parameters.callback_owner: Which Object has the callback function on it. Global is a valid target as well.
      • Optional, defaults to Global. Serves no purpose if callback is not also used.
    • parameters.params: A Table of data to send to the callback to use as parameters. See example.
      • Optional, default is to not be used.
function onLoad()
    futureName = "Spawned By Script!"
    spawnParams = {
        json = self.getJSON(),
        position       = {x=0, y=3, z=-5},
        rotation       = {x=0, y=90, z=0},
        scale          = {x=2, y=2, z=2},
        sound          = false,
        snap_to_grid   = true,
        callback       = "spawn_callback",
        callback_owner = Global,
        params         = {name = futureName}
    }
    spawnObject(spawnParams)
end

function spawn_callback(object_spawned, params)
    object_spawned.setName(params.name)
    object_spawned.setColorTint({r=0,g=1,b=0})
end

startLuaCoroutine(...)

 Start a coroutine. A coroutine is similar to a function, but has the unique ability to have its run paused until the next frame of the game using coroutine.yield(0).

Attention

You MUST return a 1 at the end of any coroutine or it will throw an error.

startLuaCoroutine(function_owner, function_name)

  • function_owner: The Object that the function being called is on. Global is a valid target.
  • function_name: Name of the function being called as a coroutine.
function onLoad()
    startLuaCoroutine(Global, "print_coroutine")
end

-- Prints a message, waits 250 frames, prints another message
function print_coroutine()
    print("Routine has Started")
    count = 0
    while count < 250 do
        count = count + 1
        coroutine.yield(0)
    end

    print("Routine has Finished")

    return 1
end

stringColorToRGB(...)

 Converts a Player Color string into a Color Table for tinting.

stringColorToRGB(player_color)

printToAll("Blue message", stringColorToRGB("Blue"))

Message Function Details

broadcastToAll(...)

 Print an on-screen message to all Players.

broadcastToAll(message, message_tint)

  • message: Message to display on-screen.
  • message_tint: A Table containing the RGB color tint for the text.
msg = "Hello all."
rgb = {r=1, g=0, b=0}
broadcastToAll(msg, rgb)

broadcastToColor(...)

 Print an on-screen message to a specified Player and their in-game chat.

broadcastToColor(message, player_color, message_tint)

  • message: Message to display on-screen.
  • player_color: Player Color to receive the message.
  • message_tint: RGB color tint for the text.
msg = "Hello White."
color = "White"
rgb = {r=1, g=0, b=0}
broadcastToColor(msg, color, rgb)

log(...)

 Print information to the log. The log is a separate chat window which is visible to all players in the instance.

If a table is used for "element", the log will automatically display the key/value contents of it.

log(element, label, tag)

  • element: The information you want placed into the log.
  • label: Text to be placed before the Var element is printed to the log.
    • Optional, defaults to an empty String. Empty Strings are not displayed.
  • tag: Name that is usable to categorize log entries. (See: logStyle)
    • Optional, defaults to an empty String. Empty Strings are not displayed.
log(getAllObjects(), "table", "All Objects:")

logStyle(...)

 Set style options for the specified tag type for the log. This can also be set in the system console with the "log_style_tag" command.

logStyle(tag, tint, prefix, postfix)

  • tag: A String of the log's tag.
  • tint: RGB value to tint the log entry's text.
    • String color will also work. Example: "Red"
  • prefix: Text to place before this type of log entry.
    • Optional, defaults to an empty String. Empty Strings are not displayed.
  • postfix: Text to place after this type of log entry.
    • Optional, defaults to an empty String. Empty Strings are not displayed.
function onLoad()
    logStyle("players", {0.5,0.5,0.5}, "", "End List")
    log(getSeatedPlayers(), "players")
end

print(...)

 Print a string into chat that only the host is able to see. Used for debugging scripts.

print(message)

  • message: Text to print into the chat log.

printToAll(...)

 Print a message into the in-game chat of all connected players.

printToAll(message, message_tint)

  • message: Message to place into players' in-game chats.
  • message_tint: RGB values for the text's color tint.
printToAll("Hello World!", {r=1,g=0,b=0})

printToColor(...)

 Print a message to the in-game chat of a specific player.

printToColor(message, player_color, message_tint)

  • message: Message to place into the player's in-game chat.
  • player_color: Player Color of the player that will receive the message.
  • message_tint: RGB values for the text's color tint.
printToColor("Hello Red.", "Red", {r=1,g=0,b=0})

Notebook Function Details

addNotebookTab(...)

 Add a new notebook tab. If it failed to create a new tab, a -1 is returned instead. Indexes for notebook tabs begin at 0.

addNotebookTab(parameters)

  • parameters: A Table containing spawning parameters.
    • parameters.title: Title for the new tab.
    • parameters.body: Text to place into the body of the new tab.
      • Optional, defaults to an empty string
    • parameters.color: Player Color for the new tab's color.
      • Optional, defaults to "Grey"
parameters = {
    title = "New Tab",
    body = "Body text example.",
    color = "Grey"
}
addNotebookTab(parameters)

editNotebookTab(...)

 Edit an existing Tab in the notebook. Indexes for notebook tabs begin at 0.

editNotebookTab(parameters)

  • parameters: A Table containing instructions for the notebook edit.
    • parameters.index: Index number for the tab.
    • parameters.title: Title for the tab.
      • Optional, defaults to the current title of the tab begin edited.
    • parameters.body: Text for the body for the tab.
      • Optional, defaults to the current body of the tab begin edited.
    • parameters.color: Player Color for who the tab belongs to.
      • Optional, defaults to the current color of the tab begin edited.
params = {
    index = 5,
    title = "Edited Title",
    body = "This tab was edited via script.",
    color = "Grey"
}
editNotebookTab(params)

getNotebookTabs()

 Returns a Table containing data on all tabs in the notebook. Indexes for notebook tabs begin at 0.

--Example Usage
tabInfo = getNotebookTabs()
--Example Returned Table
{
    {index=0, title="", body="", color="Grey"},
    {index=1, title="", body="", color="Grey"},
    {index=2, title="", body="", color="Grey"},
}


removeNotebookTab(...)

 Remove a notebook tab. Notebook tab indexes begin at 0.

removeNotebookTab(index)

  • index: Index for the tab to remove.
removeNotebookTab(0)