Skip to content

Base

These are a loose collection of functions which can be used to perform a variety of actions within Tabletop Simulator.

These functions can utilize in-game Objects, but none of them can be enacted on in-game Objects. They all deal with the game space.

Function Summary

Global Functions

General functions which work within any script.

Function Name Description Return  
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.
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.
group( objects) Groups objects together, like how the G key does for players.
paste( parameters) Pastes Objects in-game that were copied to the in-game clipboard. Works with copy(...).
setLookingForPlayers( lfp) Enables/disables looking for group. This is visible in the server browsers, indicating if you are recruiting for a game.
spawnObject( parameters) Spawns an Object. View the Build-in Object or Custom Game Objects pages 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.

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().

group(...)

 Groups objects together, like how the G key does for players. It returns a table of object references to any decks/stacks formed.

Not all objects CAN be grouped. If the G key won't work on them, neither will this function.

group(objects)

  • objects: A list of objects to be grouped together.
function onLoad()
    local objList = {
        getObjectFromGUID("b80a72"),
        getObjectFromGUID("a333b4"),
        getObjectFromGUID("c9f9d3"),
    }
    group(objList)
end

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).

spawnObject(...)

 Spawn an Object. View the Build-in Object or Custom Game Objects pages 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. You can also add a delay after spawning using a Wait function.

spawnObject(parameters)

  • parameters: A Table of parameters used to determine how spawnObject will act.
    • parameters.type: Build-in Object or Custom Game Objects 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_function: The function to activate after the Object has finished spawning into the scene.
      • Optional, defaults to not being used.
      • A reference to the object spawned is always passed to callback_function. See the example for how to access it.
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_function = function(obj) spawn_callback(obj, "Bear", "Green") end
    }
    spawnObject(spawnParams)
end

function spawn_callback(object_spawned, name, color)
    object_spawned.setName(name)
    object_spawned.setColorTint(color)
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. You can also add a delay after spawning using a Wait function.

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.callback_function: The function to activate after the Object has finished spawning into the scene.
      • Optional, defaults to not being used.
      • A reference to the object spawned is always passed to callback_function. See the example for how to access it.
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_function = function(obj) spawn_callback(obj, futureName, "Red") end
        --alternative format:
        --callback_function = |obj| spawn_callback(obj, futureName, "Red")
    }
    spawnObject(spawnParams)
end

function spawn_callback(object_spawned, name, color)
    object_spawned.setName(name)
    object_spawned.setColorTint(color)
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 in which you can also enter console commands. It is only visible to the host.

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(), "All Objects:", "table")

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})