Skip to content

Object

The Object class represents any entity within tabletop simulator. Once you have a reference to an object in you're script you can call functions on it directly. Example: obj.getPosition(...). You can get a reference to an object multiple ways;

  • Using the self property if your script is on an Object and referring to that Object.
  • Using getObjectFromGUID(...) with the object's GUID (found by right clicking it with the pointer).
  • Getting it as a return from another function, like with spawnObject(...).

Member Variable Summary

Member Variables

These are variables that objects share. They allow for direct access to an Object's property information without a helping function. Some are read-only.

Read Example = isResting = self.resting Write Example = self.resting = true

Variable Description Type
angular_drag Angular drag. Unity rigidbody property.
auto_raise If an object should be lifted above other objects to avoid collision when held by a player.
bounciness Bounciness, value of 0-1. Unity physics material.
drag_selectable If this is set, object will never be drag-selected.
drag Drag. Unity rigidbody property.
dynamic_friction Dynamic friction, value of 0-1. Unity physics material.
grid_projection If grid lines can appear on the Object if visible grids are turned on.
guid The 6 character unique Object identifier within Tabletop Simulator. It is assigned correctly once the spawning member variable becomes false.
held_by_color The Color of the Player that is holding the object.
hide_when_face_down Hide the Object when face-down as if it were in a hand zone. The face is the "top" of the Object, the direction of its positive Y coordinate. Cards/decks default to true.
ignore_fog_of_war Makes the object not be hidden by Fog of War.
interactable If an object can be interacted with by Players. Other object will still be able to interact with it.
is_face_down If an Object is roughly face-down (like with cards). The face is the "top" of the Object, the direction of its positive Y coordinate. Read only.
loading_custom If the Object's custom elements (images/models/etc) are loading. Read only.
mass Mass. Unity rigidbody property.
name Internal resource name for this Object. Read only, and only useful for spawnObjectJSON(). Generally, you want getName().
resting If an Object is at rest. Unity rigidbody property.
script_code The Lua Script on the Object.
script_state The saved data on the object. See onSave().
spawning If the Object is finished spawning. Read only.
static_friction Static friction, value of 0-1. Unity physics material.
sticky If other Objects on top of this one are also picked up when this Object is.
tag This object's type. Read only.
tooltip If the tooltip opens when a pointer hovers over the object. Tooltips display name and description.
use_gravity If gravity affects this object.
use_grid If snapping to grid is enabled or not.
use_hands If this object can be held in a hand zone.
use_rotation_value_flip Switches the axis an Object rotates around when flipped.
use_snap_points If snap points are used or ignored.
value_flags A bit field, objects with overlapping value_flag bits are counted together when selected.
value The value of the object for summing up selected objects. Only works if the apropriate bits are set in obj.value_flags

Bug

The drag_selectable, value_flags and value member variables do not persist when the object is reloaded (such as loading a save and entering/exiting containers).

These member variables are classes of their own, and have their own member variables. Each one is for a special type of Object.

Variable Name Description
AssetBundle An AssetBundle, which is a type of custom object made in Unity.
Book A Book, which is the in-game Custom PDF object.
Browser A Browser, which is the in-game Tablet object.
Clock A Clock, which is the in-game digital clock.
Counter A Counter, which is the in-game digital counter.
RPGFigurine An RPGFigurine, which is an in-game animated figurine.
TextTool A TextTool, which is an in-game text display system.

Function Summary

Transform Functions

These functions handle the physical attributes of an Object: Position, Rotation, Scale, Bounds, Velocity. In other words, moving objects around as well as getting information on how they are moving.

Function Name Description Return  
addForce( vector,  force_type) Adds force to an object in a directional Vector.
addTorque( vector,  force_type) Adds torque to an object in a rotational Vector.
getAngularVelocity() Returns a Vector of the current angular velocity.
getBounds() Returns a Vector describing the size of an object in Global terms.
getBoundsNormalized() Returns a Vector describing the size of an object in Global terms, as if it was rotated to {0,0,0}.
getPosition() Returns a Vector of the current world position.
getRotation() Returns a Vector of the current rotation.
getScale() Returns a Vector of the current scale.
getTransformForward() Returns a Vector of the forward direction of this object.
getTransformRight() Returns a Vector of the right direction of this object.
getTransformUp() Returns a Vector of the up direction of this object.
getVelocity() Returns a Vector of the current velocity.
isSmoothMoving() Indicates if an object is traveling as part of a Smooth move. Smooth moving is performed by setPositionSmooth and setRotationSmooth.
positionToLocal( vector) Returns a Vector after converting a world Vector to a local Vector.
positionToWorld( vector) Returns a Vector after converting a local Vector to a world Vector.
rotate( vector) Rotates Object smoothly in the direction of the given Vector.
scale( vector or ) Scales Object by a multiple.
setAngularVelocity( vector) Sets a Vector as the current angular velocity.
setPosition( vector) Instantly moves an Object to the given Vector.
setPositionSmooth( vector,  collide,  fast) Moves the Object smoothly to the given Vector.
setRotation( vector) Instantly rotates an Object to the given Vector.
setRotationSmooth( vector,  collide,  fast) Rotates the Object smoothly to the given Vector.
setScale( vector) Sets a Vector as the current scale.
setVelocity( vector) Sets a Vector as the current velocity.
translate( vector) Smoothly moves Object by the given Vector offset.

UI Functions

A new UI system was added to Tabletop Simulator which allows for more flexibility in the creation of UI elements on Objects. The old system (Classic UI) and new system (Custom UI) both work, and each has its own strengths.

Classic UI

These functions allow for the creation/editing/removal of functional buttons and text inputs which themselves trigger code within your scripts. These buttons/inputs are attached to the object they are created on.

Function Name Description Return  
clearButtons() Removes all scripted buttons.
clearInputs() Removes all scripted inputs.
createButton( parameters) Creates a scripted button attached to the Object.
createInput( parameters) Creates a scripted input attached to the Object.
editButton( parameters) Modify an existing button.
editInput( parameters) Modify an existing input.
getButtons() Returns a Table of all buttons on this Object.
getInputs() Returns a Table of all inputs on this Object.
removeButton( index) Removes a specific button.
removeInput( index) Removes a specific button.

Custom UI

Custom UI gives you a wide variety of element types, not just buttons and inputs, to place onto an Object. It is an extension of the UI class, and details on its use can be found on the UI page.

Get Functions

These functions obtain information from an object.

Function Name Description Return  
getAttachments() Returns a table in the same format as getObjects() for containers.
getColorTint() Color tint.
getCustomObject() Returns a Table with the Custom Object information of a Custom Object.
getDescription() Description, also shows as part of Object's tooltip.
getFogOfWarReveal() Settings impacting Fog of War being revealed.
getGUID() String of the Object's unique identifier.
getJSON() Returns a serialization of the JSON string which represents this item. Works with spawnObjectJSON().
getJoints() Returns information on any joints attached to this object.
getLock() If the Object is locked.
getName() Name, also shows as part of Object's tooltip.
getObjects() Returns a Table of Objects in the script zone/bag/deck.
getQuantity() How many objects are in the stack. Returns -1 if the Object is not a stack.
getRotationValue() Returns the current rotationValue. Rotation values are used to give value to different rotations (like dice).
getRotationValues() Returns a Table of rotation values. Rotation values are used to give value to different rotations (like dice).
getSelectingPlayers() Returns a table of the player colors currently selecting the object.
getStateId() Current state ID (index) an object is in. Returns -1 if there are no other states. State ids (indexes) start at 1.
getStates() Returns a Table of information on the states of an Object.
getValue() Object value. What the value represents depends on what type of Object this function is used on.

Set Functions

These functions apply action to an object. They take some property in order to work.

Function Name Description Return  
setColorTint( Color) Sets the Color tint.
setCustomObject( parameters) Sets a custom Object's properties.
setDescription( description) Sets a description for an Object. Shows in tooltip after delay.
setFogOfWarReveal( fog_settings) Establish the settings and enable/disable an Object's revealing of Fog of War.
setLock( lock) Sets if an object is locked in place.
setName( name) Sets a name for an Object. Shows in tooltip.
setRotationValues( rotation_values) Sets rotation values of an object. Rotation values are used to give value to different rotations (like dice).
setState( state_id) Sets state of an Object. State ids (indexes) start at 1.
setValue( value) Sets an Int as the value. What the value represents depends on what type of Object it is.

Action Function

These functions perform general actions on objects.

Function Name Description Return  
addAttachment( Object) The Object supplied as param is destroyed and becomes a dummy Object child.
removeAttachment( index) Removes a child with the given index. Use getAttachments() to find out the index property.
removeAttachments() Detaches the children of this Object. Returns a table of object references
destroyAttachment( index) Destroys an attachment with the given index.
destroyAttachments() Destroys all attachments.
addToPlayerSelection( player_color) Adds object to player's selection.
removeFromPlayerSelection( player_color) Removes object from player's selection.
flip() Flips Object over.
clone( parameters) Copy/Paste this Object, returning a reference to the new Object.
cut( count) Cuts (splits) a deck at the given card count.
deal( number,  player_color,  index) Deals Objects. Will deal from decks/bags/stacks/individual items.
dealToColorWithOffset( offset,  flip,  player_color) Deals from a deck to a position relative to the hand zone.
destruct() Destroys Object. Allows for self.destruct().
drop() Forces an Object, if held by a player, to be dropped.
highlightOn( color,  duration) Creates a highlight around an Object.
highlightOff( color) Removes a highlight from around an Object.
jointTo( object,  parameters) Joints objects together, in the same way the Joint tool does.
putObject( put_object) Places an object into a container (chip stacks/bags/decks).
randomize( color) Shuffles deck/bag, rolls dice/coin, lifts other objects into the air. Same as pressing R by default. If the optional parameter color is used, this function will trigger onObjectRandomized(), passing that player color.
registerCollisions( stay) Registers this object for Global collision events.
reload() Returns Object reference of itself after it respawns itself.
reset() Resets this Object. Resetting a Deck brings all the Cards back into it. Resetting a Bag clears its contents (works for both Loot and Infinite Bags).
roll() Rolls dice/coins.
shuffle() Shuffles/shakes up contents of a deck or bag.
shuffleStates() Returns an Object reference to a new state after randomly selecting and changing to one.
split( piles) Splits a deck, as evenly as possible, into a number of piles.
takeObject( parameters) Returns an Object reference of Object taken from a container (bag/deck/chip stack) and placed into the world.
unregisterCollisions() Unregisters this object for Global collision events.

Hide Functions

These functions can hide Objects, similar to how hand zones or hidden zones do.

Function Name Description Return  
setHiddenFrom( players) Hides the Object from the specified players, as if it were in a hand zone.
setInvisibleTo( players) Hides the Object from the specified players, as if it were in a hidden zone.
attachHider( id,  hidden,  players) A more advanced version of setHiddenFrom(...).
attachInvisibleHider( id,  hidden,  players) A more advanced version of setInvisibleTo(...).

Global Function

The functions can be used on Objects, but can also be used on the game world using Global.

Examples of Using Global and Object

  • self.getSnapPoints() gets snap points attached to that Object.
  • Global.getSnapPoints() gets snap points not attached to any specific Object but instead are attached to the game world.
Function Name Description Return  
addDecal( parameters) Add a Decal onto an object or the game world.
call( func_name,  func_params) Used to call a Lua function on another entity.
getDecals() Returns information on all decals attached to this object or the world.
getLuaScript() Get a Lua script as a string from the entity.
getSnapPoints() Returns a table of sub-tables, each sub-table representing one snap point.
getTable( table_name) Data value of a variable in another Object's script. Can only return a table.
getVar( var_name) Data value of a variable in another entity's script. Cannot return a table.
getVectorLines() Returns Table of data representing the current Vector Lines on this entity. See setVectorLines for table format.
setDecals( parameters) Sets which decals are on an object. This removes other decals already present, and can remove all decals as well.
setLuaScript( script) Input a string as an entity's Lua script. Generally only used after spawning a new Object.
setSnapPoints( parameters) Spawns snap points from a list of parameters.
setTable( func_name,  data) Creates/updates a variable in another entity's script. Only used for tables.
setVar( func_name,  data) Creates/updates a variable in another entity's script. Cannot set a table.
setVectorLines( parameters) Spawns Vector Lines from a list of parameters on this entity.

Function Details

Transform Function Details

addForce(...)

 Adds force to an object in a directional Vector.

addForce(vector, force_type)

  • Vector: A Vector of the direction and magnitude of force.
  • force_type: An Int representing the force type to apply. Options below.
    • Optional, defaults to 3.
    • 1: Continuous force, uses mass. (Force)
    • 2: Continuous acceleration, ignores mass. (Acceleration)
    • 3: Instant force impulse, uses mass. (Impulse)
    • 4: Instant velocity change, ignores mass. (Velocity Change)

addTorque(...)

 Adds torque to an object in a rotational Vector.

addTorque(vector, force_type)

  • Vector: A Vector of the direction and magnitude of rotational force.
  • Force Type: An Int representing the force type to apply. Options below.
    • Optional, defaults to 3.
    • 1: Continuous force, uses mass. (Force)
    • 2: Continuous acceleration, ignores mass. (Acceleration)
    • 3: Instant force impulse, uses mass. (Impulse)
    • 4: Instant velocity change, ignores mass. (Velocity Change)

getBounds()

 Returns a Table of Vector information describing the size of an object in Global terms. Bounds are part of Unity, and represent an imaginary square box that can be drawn around an object. Unlike scale, it can help indicate the size of an object in in-game units, not just relative model size.

Return Table

  • center: The Vector of the center of the bounding box.
  • size: The Vector of the size of the bounding box.
  • offset: The Vector of the offset of the center of the bounding box from the middle of the Object model.
-- Example returned Table
{
    center = {x=0, y=3, z=0, 0, 3, 0},
    size = {x=5, y=5, z=5}, 5, 5, 5},
    offset = {x=0, y=-1, z=0, 0, -1, 0}
}

getBoundsNormalized()

 Returns a Table of Vector information describing the size of an object in Global terms, as if it was rotated to {0,0,0}. Bounds are part of Unity, and represent an imaginary square box that can be drawn around an object. Unlike scale, it can help indicate the size of an object in in-game units, not just relative model size.

Return Table

  • center: The Vector of the center of the bounding box.
  • size: The Vector of the size of the bounding box.
  • offset: The Vector of the offset of the center of the bounding box from the middle of the Object model.
-- Example returned Table
{
    center = {x=0, y=3, z=0, 0, 3, 0},
    size = {x=5, y=5, z=5}, 5, 5, 5},
    offset = {x=0, y=-1, z=0, 0, -1, 0}
}

getScale()

 Returns a Vector of the current scale. Scale is not an absolute measurement, it is a multiple of the Object's default model size. So {x=2, y=2, z=2} would be a model twice its default size, not 2 units large.

getTransformForward()

 Returns a Vector of the forward direction of this Object. The direction is relative to how the object is facing.

-- Example of moving forward 5 units
function onLoad()
    distance = 5
    pos_target = self.getTransformForward()
    pos_current = self.getPosition()
    pos = {
        x = pos_current.x + pos_target.x * distance,
        y = pos_current.y + pos_target.y * distance,
        z = pos_current.z + pos_target.z * distance,
    }
    self.setPositionSmooth(pos)
end

getTransformRight()

 Returns a Vector of the forward direction of this object. The direction is relative to how the object is facing.

-- Example of moving right 5 units
function onLoad()
    distance = 5
    pos_target = self.getTransformRight()
    pos_current = self.getPosition()
    pos = {
        x = pos_current.x + pos_target.x * distance,
        y = pos_current.y + pos_target.y * distance,
        z = pos_current.z + pos_target.z * distance,
    }
    self.setPositionSmooth(pos)
end

getTransformUp()

 Returns a Vector of the up direction of this Object. The direction is relative to how the object is facing.

-- Example of moving up 5 units
function onLoad()
    distance = 5
    pos_target = self.getTransformUp()
    pos_current = self.getPosition()
    pos = {
        x = pos_current.x + pos_target.x * distance,
        y = pos_current.y + pos_target.y * distance,
        z = pos_current.z + pos_target.z * distance,
    }
    self.setPositionSmooth(pos)
end

positionToLocal(...)

 Returns a Vector after converting a world vector to a local Vector. A world Vector is a positional Vector using the world's coordinate system. A Local Vector is a positional Vector that is relative to the position of the given object.

Object Scale

This function takes the Object's scale into account, as the Object is the key relative point.

positionToLocal(vector)

  • vector: The world position to convert into a local position.

positionToWorld(...)

 Returns a Vector after converting a local Vector to a world Vector. A world Vector is a positional Vector using the world's coordinate system. A Local Vector is a positional Vector that is relative to the position of the given object.

Object Scale

This function takes the Object's scale into account, as the Object is the key relative point.

positionToLocal(vector)

  • vector: The local position to convert into a world position.

rotate(...)

 Rotates Object smoothly in the direction of the given Vector. This does not set the Object to face a specific rotation, it rotates the Object around by the number of degrees given for x/y/z.

rotate(vector)

  • vector: The amount of x/y/z to rotate by.
--Rotates object 90 degrees around its Y axis
self.rotate({x=0, y=90, z=0})

scale(...)

 Scales Object by a multiple. This does not set the Object to a specific scale, it scales the Object by the given multiple.

scale(scale)

  • scale: Multiplier for scale.
    • {x=1, y=1, z=1} would not change the scale.

scale(scale)

  • scale: Multiplier for scale which is applied to the X/Y/Z.
    • 1 would not change the scale.
-- Both examples work to scale an object to be twice its current scale
self.scale({x=2, y=2, z=2})
self.scale(2)

setPositionSmooth(...)

 Moves the Object smoothly to the given Vector.

setPositionSmooth(vector, collide, fast)

  • Vector: A positional Vector.
  • collide: If the Object will collide with other Objects while moving.
  • fast: If the Object is moved quickly.

setRotationSmooth(...)

 Rotates the Object smoothly to the given Vector.

setRotationSmooth(vector, collide, fast)

  • Vector: A rotational Vector.
  • collide: If the Object will collide with other Objects while rotating.
  • fast: If the Object is rotated quickly.

UI Function Details

createButton(...)

 Creates a scripted button attached to the Object. Scripted buttons are buttons that can be clicked while in-game that trigger a function in a script.

Button Tips
  • Buttons can not be clicked from their back side.
  • Buttons can not be clicked if there is another object between the pointer and the button. This does not include the Object the button is attached to.
  • Buttons are placed relative to the Object they are attached to.
  • The maximum font size is capped at 1000.
  • The minimum width/height is 60. Any lower number (besides 0) will appear to be 60. This prevents visual glitches involving the corner rounding.
  • A button width/height of 0 will cause the button not to be drawn, but its label will be. This can be a way to attach text to an Object.
  • You cannot assign an index to a button. It is given one automatically.

createButton(parameters)

  • parameters: A Table containing the information used to spawn the button.
    • parameters.click_function: A String of the function's name that will be run when button is clicked.
    • parameters.function_owner: The Object which contains the click_function function.
      • Optional, Defaults to Global.
    • parameters.label: Text that appears on the button.
      • Optional, defaults to an empty string.
    • parameters.position: Where the button appears, relative to the Object's center.
      • Optional, defaults to {x=0, y=0, z=0}.
    • parameters.rotation: How the button is rotated, relative to the Object's rotation.
      • Optional, defaults to {x=0, y=0, z=0}.
    • parameters.scale: Scale of the button, relative to the Object's scale.
      • Optional, defaults to {x=1, y=1, z=1}.
    • parameters.width: How wide the button will be, relative to the Object.
      • Optional, defaults to 100.
    • parameters.height: How tall the button will be, relative to the Object.
      • Optional, defaults to 100.
    • parameters.font_size: Size the label font will be, relative to the Object.
      • Optional, defaults to 100.
    • parameters.color: A Color for the clickable button.
      • Optional, defaults to {r=1, g=1, b=1}.
    • parameters.font_color: A Color for the label text.
      • Optional, defaults to {r=0, g=0, b=0}.
    • parameters.hover_color: A Color for the background during mouse-over.
      • Optional.
    • parameters.press_color: A Color for the background when clicked.
      • Optional.
    • parameters.tooltip: Popup of text, similar to how an Object's name is displayed on mouseover.
      • Optional, defaults to an empty string.

click_function(obj, player_clicker_color, alt_click)

The click function which is activated by clicking this button has its own parameters it is passed automatically.

  • obj: The Object the button is attached to.
  • player_clicker_color: Player Color of the player that pressed the button.
  • alt_click: True if a button other than left-click was used to click the button.
function onLoad()
    params = {
        click_function = "click_func",
        function_owner = self,
        label          = "Test",
        position       = {0, 1, 0},
        rotation       = {0, 180, 0},
        width          = 800,
        height         = 400,
        font_size      = 340,
        color          = {0.5, 0.5, 0.5},
        font_color     = {1, 1, 1},
        tooltip        = "This text appears on mouseover.",
    }
    self.createButton(params)
end

function click_func(obj, color, alt_click)
    print(obj)
    print(color)
    print(alt_click)
end

Bug

Button scale currently distorts button height and width if the button is rotated at anything besides {0,0,0}.

createInput(...)

 Creates a scripted input attached to the Object. Scripted inputs are boxes you can click inside of in-game to input/edit text. Every letter typed triggers the function. The bool that is returned as part of the input_function allows you to determine when a player has finished editing the input.

Input Tips
  • Inputs can not be clicked from their back side.
  • Inputs can not be clicked if there is another object between the pointer and the inputs. This does not include the Object the input is attached to.
  • Inputs are placed relative to the Object they are attached to.
  • The maximum font size is capped at 1000.
  • The minimum width/height is 60. Any lower number (besides 0) will appear to be 60. This prevents visual glitches involving the corner rounding.
  • Font that does not fit in the input window's width/height does NOT display. To know how much height you need for each line, the formula is (font_size * # of lines) + 23. In other words, multiply how many lines of text you want to display by your font_size and add 23. That is your height value.
  • You cannot assign an index to an input. It is given one automatically.

createInput(parameters)

  • parameters: A Table containing the information used to spawn the input.
    • parameters.input_function: A String of the function's name that will be run when a key is used or when it is deselected.
    • parameters.function_owner: The Object which contains the input_function function.
      • Optional, Defaults to Global.
    • parameters.label: Text that appears as greyed out text when there is no value in the input.
      • Optional, defaults to an empty string.
    • parameters.position: Where the input appears, relative to the Object's center.
      • Optional, defaults to {x=0, y=0, z=0}.
    • parameters.rotation: How the input is rotated, relative to the Object's rotation.
      • Optional, defaults to {x=0, y=0, z=0}.
    • parameters.scale: Scale of the input, relative to the Object's scale.
      • Optional, defaults to {x=1, y=1, z=1}.
    • parameters.width: How wide the input will be, relative to the Object.
      • Optional, defaults to 100.
    • parameters.height: How tall the input will be, relative to the Object.
      • Optional, defaults to 100.
    • parameters.font_size: Size the label/value font will be, relative to the Object.
      • Optional, defaults to 100.
    • parameters.color: A Color for the input's background.
      • Optional, defaults to {r=1, g=1, b=1}.
    • parameters.font_color: A Color for the value text.
      • Optional, defaults to {r=0, g=0, b=0}.
    • parameters.tooltip: A popup of text, similar to how an Object's name is displayed on mouseover.
      • Optional, defaults to an empty string.
    • parameters.alignment: How text is aligned in the input box.
      • Optional, defaults to 1.
      • 1: Automatic
      • 2: Left
      • 3: Center
      • 4: Right
      • 5: Justified
    • parameters.value: Text entered into the input.
      • Optional, defaults to an empty string.
    • parameters.validation: What characters can be input into the input value field.
      • Optional, defaults to 1.
      • 1: None
      • 2: Integer
      • 3: Float
      • 4: Alphanumeric
      • 5: Username
      • 6: Name
    • parameters.tab: How the pressing of "tab" is handled when inputting.
      • Optional, defaults to 1.
      • 1: None
      • 2: Select Next Input
      • 3: Indent

input_function(obj, player_clicker_color, input_value, selected)

The click function which is activated by editing the text in this input has its own parameters it is passed automatically.

  • obj: The Object the input is attached to.
  • player_clicker_color: Player Color of the player that has selected/edited the input.
  • input_value: Text currently in the input.
  • selected: If the value box is still being edited or not.
function onLoad()
    self.createInput({
        input_function = "input_func",
        function_owner = self,
        label          = "Gold",
        alignment      = 4,
        position       = {x=0, y=1, z=0},
        width          = 800,
        height         = 300,
        font_size      = 323,
        validation     = 2,
    })
end

function input_func(obj, color, input, stillEditing)
    print(input)
    if not stillEditing then
        print("Finished editing.")
    end
end

editButton(...)

 Modify an existing button. The only parameter that is required is the index. The rest are optional, and not using them will cause the edited button's element to remain. Indexes start at 0. The first button on any given Object has an index of 0, the next button on it has an index of 1, etc. Each Object has its own indexes.

editButton(parameters)

  • parameters: A Table containing the information used to spawn the button.
    • parameters.index: Index of the button you want to edit.
    • parameters.click_function: Function's name that will be run when button is clicked.
    • parameters.function_owner: The Object which contains the click_function function.
    • parameters.label: Text that appears on the button.
    • parameters.position: Where the button appears, relative to the Object's center.
    • parameters.rotation: How the button is rotated, relative to the Object's rotation.
    • parameters.scale: Scale of the button, relative to the Object's scale.
    • parameters.width: How wide the button will be, relative to the Object.
    • parameters.height: How tall the button will be, relative to the Object.
    • parameters.font_size: Size the label font will be, relative to the Object.
    • parameters.color: A Color for the clickable button.
    • parameters.font_color: A Color for the label text.
    • parameters.hover_color: A Color for the background during mouse-over.
    • parameters.press_color: A Color for the background when clicked.
    • parameters.tooltip: Text of a popup of text, similar to how an Object's name is displayed on mouseover.
self.editButton({index=0, label="New Label"})

editInput(...)

 Modify an existing input. The only parameter that is required is the index. The rest are optional, and not using them will cause the edited input's element to remain. Indexes start at 0. The first input on any given Object has an index of 0, the next input on it has an index of 1, etc. Each Object has its own indexes.

editInput(parameters)

All fields besides index are optional. If not used, the element will default to the element's current setting.

  • parameters: A Table containing the information used to spawn the input.
    • parameters.index: Index of the input you want to edit.
    • parameters.input_function: The function's name that will be run when the input is selected.
    • parameters.function_owner: The Object which contains the input_function function.
    • parameters.label: Text that appears as greyed out text when there is no value in the input.
    • parameters.position: Where the input appears, relative to the Object's center.
    • parameters.rotation: How the input is rotated, relative to the Object's rotation.
    • parameters.scale: Scale of the input, relative to the Object's scale.
    • parameters.width: How wide the input will be, relative to the Object.
    • parameters.height: How tall the input will be, relative to the Object.
    • parameters.font_size: Size the label/value font will be, relative to the Object.
    • parameters.color: A Color for the input's background.
    •  parameters.font_color: A Color for the value text.
    • parameters.tooltip: A popup of text, similar to how an Object's name is displayed on mouseover.
    • parameters.alignment: How text is aligned in the input box.
      • 1: Automatic
      • 2: Left
      • 3: Center
      • 4: Right
      • 5: Justified
    • parameters.value: A String of the text entered into the input.
    • parameters.validation: An Int which determines what characters can be input into the value.
      • 1: None
      • 2: Integer
      • 3: Float
      • 4: Alphanumeric
      • 5: Username
      • 6: Name
    • parameters.tab: An Int which determines how pressing tab is handled when inputting.
      • 1: None
      • 2: Select Next Input
      • 3: Indent
self.editInput({index=0, value="New Value"})

getButtons()

 Returns a Table of all buttons on this Object. The Table contains parameters tables with the same keys as seen in the createButton section, except each Table of parameters also contains an index entry. This is used to identify each button, used by editButton and removeButton.

Indexes start at 0.

getInputs()

 Returns a Table of all inputs on this Object. The Table contains parameters tables with the same keys as seen in the createInput section, except each Table of parameters also contains an index entry. This is used to identify each input, used by editInput and removeInput.

Indexes start at 0.

removeButton(...)

 Removes a specific button. Indexes start at 0. The first button on any given Object has an index of 0, the next button on it has an index of 1, etc. Each Object has its own indexes.

Removing an index instantly causes all other higher indexes to shift down 1.

removeButton(index)

  • index: Button index to remove.

removeInput(...)

 Removes a specific input. Indexes start at 0. The first input on any given Object has an index of 0, the next input on it has an index of 1, etc. Each Object has its own indexes.

Removing an index instantly causes all other higher indexes to shift down 1.

removeInput(index)

  • index: Input index to remove.

Get Function Details

getCustomObject()

 Returns a Table with the Custom Object information of a Custom Object. See the Custom Game Objects page for the kind of information returned.

-- Example returned Table for a custom token
{
    image = "SOME URL HERE",
    thickness = 0.2,
    merge_distance = 15,
    stackable = false,
}

Jigsaw Puzzles

If you use getCustomObject() on a puzzle piece, it will also return desired_position, which is its position if the puzzle is "solved". You can use this to determine where to put the piece.

getFogOfWarReveal()

 Settings impacting Fog of War being revealed. In the example returned table, these are the default values of any object.

Color Selection

"Black" and "All" are synonymous for Fog of War. Either means that all players can see the revealed area when reveal = true.

-- Example returned Table for a custom token
{
    reveal = false,
    color = 'All',
    range = 5
}

getJoints()

 Returns information on any joints attached to this object. This information included the GUID of the other objects attached via the joints.

This function returns a table of sub-tables, each sub-table representing one joint.

Example of a return table of an object with 2 joints: 

{
    {
        type              = "Spring",
        joint_object_guid = "555555",
        collision         = false,
        break_force       = 1000,
        break_torgue      = 1000,
        axis              = {0,0,0},
        anchor            = {0,0,0},
        connector_anchor  = {0,0,0},
        motor_force       = 0,
        motor_velocity    = 0,
        motor_free_spin   = false,
        spring            = 50,
        damper            = 0.1
        max_distance      = 10
        min_distance      = 0
    },
    {
        type              = "Spring",
        joint_object_guid = "888888",
        collision         = false,
        break_force       = 1000,
        break_torgue      = 1000,
        axis              = {0,0,0},
        anchor            = {0,0,0},
        connector_anchor  = {0,0,0},
        motor_force       = 0,
        motor_velocity    = 0,
        motor_free_spin   = false,
        spring            = 50,
        damper            = 0.1
        max_distance      = 10
        min_distance      = 0
    },
}

Example of printing the first sub-table's information: 

local jointsInfo = self.getJoints()
for k, v in pairs(jointsInfo[1]) do
    print(k, ":  ", v)
end

getObjects()

 Returns a Table of objects in the script zone/bag/deck. What it returns varies depending on the type of Object it is used on.

If an Object is inside of a container, it does not exist in-game. As a result, you only get data on each Object, not an Object reference.

Return Table by Object Type

Scripting Zone

Returns a Table of Object references to every object in the scripting zone.

{
    object_1,
    object_2,
}

Bag or Deck

Returns a Table of sub-Tables, each sub-Table containing data on 1 bagged item. Indexes start at 0.

  • index: Index of the item, represents the item's order in the container.
  • name: Name of the item.
  • description: Description of the item.
  • guid: GUID of the item.
  • gm_notes: GM Notes on the item.
  • lua_script: Any Lua scripting saved on the item.
  • lua_script_state: Any JSON save data on this item.
  • nickname: A duplicate of the "name" field.
    • This is for backwards compatibility purposes only.
{
    {
        name             = "Object Name",
        description      = "Object Description",
        guid             = "AAA111",
        index            = 0,
        lua_script       = "Any Lua Script On This Object",
        lua_script_state = "Any JSON Save Data On This Object"
    },
}

This function is often used with takeObject(...) to remove objects from containers.

getRotationValue()

 Returns the current rotationValue. Rotation values are used to give value to different rotations (like dice) and are set using scripting or the Gizmo tool. The value returned is for the rotation that is closest to being pointed "up".

The returned value will either be a number or a string, depending on the value that was given to that rotation.

local value = self.getRotationValue()
print(value)

getRotationValues()

 Returns a Table of rotation values. Rotation values are used to give value to different rotations (like dice) based on which side is pointed "up". It works by checking all of the rotation values assigned to an object and determining which one of them is closest to pointing up, and then displaying the value associated with that rotation.

You can manually assign rotation values to objects using the Rotation Value Gizmo tool (in the left side Gizmo menu) or using setRotationValues(...).

Return Table

The returned Table contains sub-Tables, each sub-Table containing these 2 key/value pairs.

  • value: What value is associated with a given rotation. Often a String or Int.
    • Starting a value with a # will cause it not to show in the Object's tooltip.
  • rotation: Rotation of the Object that best represents the given value pointing up.
-- Example returned Table for a coin
{
    {value="Heads", rotation={x=0, y=0, z=0}},
    {value="Tails", rotation={x=180, y=0, z=0}},
}

getStates()

 Returns a Table of information on the states of an Object. Stated Objects have ids (indexes) starting with 1.

The returned table will NOT include data on the current state.

Return Table

Returns a table of sub-tables. Each sub-table represents one other state.

  • name: Name of the item.
  • description: Description of the item.
  • guid: GUID of the item.
  • id: Index of the item, represents the item's order in the states.
  • lua_script: Any Lua scripting saved on the item.
  • lua_script_state: Any JSON save data on this item.
  • nickname: A duplicate of the "name" field.
    • This is for backwards compatibility purposes only.
-- Example returned Table
{
    {
        name             = "First State",
        description      = "",
        guid             = "AAA111",
        id               = 1,
        lua_script       = "",
        lua_script_state = "",
    },
    {
        name             = "Second State",
        description      = "",
        guid             = "BBB222",
        id               = 2,
        lua_script       = "",
        lua_script_state = "",
    },
}

getValue()

 Gets a value. What the value represents depends on what type of Object this function is used on.

Object Value
Clock Returns Int of stopwatch/timer current time (in seconds).
Counter Returns Int of counter value.
Rotation Value Returns Int of the face-up value. For objects with rotation values set using setRotationValues this is an index into the table of rotation values.
Hidden Zone Returns String of the Player Color of the zone.
Poker Chip Returns Int of the face value. Does not work on custom chips.
Tablet Returns String of the current URL.

Set Function Details

setCustomObject(...)

 Sets a custom Object's properties. It can be used after spawnObject or on an already existing custom Object. If used on an already existing custom Object, you must use reload on the object after setCustomObject for the changes to be displayed.

setCustomObject(parameters)

The Table of parameters varies, depending on which type of custom Object it is. See the Custom Game Objects page for the parameters needed.

-- Example of a custom token
params = {
    image = "SOME URL HERE",
    thickness = 0.2,
    merge_distance = 15,
    stackable = false,
}
obj.setCustomObject(params)

setFogOfWarReveal(...)

 Establish the settings and enable/disable an Object's revealing of Fog of War.

setFogOfWarReveal(fog_setting)

  •  fog_setting: A Table containing information on if/how this Object should reveal Fog of War.
    •  reveal: Can the Object currently
      • If this is not used, the current setting for this Object is kept.
    •  color: The rotation Vector of the Object that best represents the given value pointing up.
      • If this is not used, the current setting for this Object is kept.
      • "Black" means "visible to all players."
      • "All" means "visible to all players."
    •  range: How far from the Object the reveal effect reaches (radius, inches).
      • If this is not used, the current setting for this Object is kept.
-- Example of enabling reveal for all players at 3 units of radius.
params = {
    reveal = true,
    color  = "Black",
    range  = 3,
}
self.setFogOfWarReveal(params)

setRotationValues(...)

 Sets rotation values of an object. Rotation values are used to give value to different rotations (like dice). It works by checking all of the rotation values assigned to an object and determining which one of them is closest to pointing up, and then displaying the value associated with that rotation.

setRotationValues(rotation_values)

  •  rotation_values: A Table containing Tables with the following values. 1 sub-Table per "face".
    •  rotation_values.value: What value is associated with a given rotation. Often a String or Int.
      • Starting a value with a # will cause it not to show in the Object's tooltip.
    •  rotation_values.rotation: The rotation Vector of the Object that best represents the given value pointing up.
-- Example setting of rotation values for a coin
rotation_values = {
    {value="Heads", rotation={x=0, y=0, z=0}},
    {value="Tails", rotation={x=180, y=0, z=0}},
}
self.setRotationValues(rotation_values)

setValue(...)

 Sets a value on an Object. What the value represents depends on what type of Object it is.

Object Value
Clock Set Int for stopwatch/timer current time (in seconds).
Counter Set Int for counter value.
Rotation Value Set Int for the face-up value. For objects with rotation values set with setRotationValues this is an index into the table of rotation values.
Hidden Zone Set String for the Player Color of the zone.
Tablet Set String for the current URL.

Action Function Details

clone(...)

 Copy/Paste this Object.

clone(parameters)

  • parameters: A Table with information used when pasting.
    • parameters.position: Where the Object is placed.
      • Optional, defaults to {x=0, y=3, z=0}.
    • parameters.snap_to_grid: If the Object snaps to grid.
      • Optional, defaults to false.

cut(...)

 Cuts (splits) a deck down to a given card. In other words, it counts down from the top of the deck and makes a new deck of that size and puts the remaining cards in the other pile.

After the cut, the resulting decks much each have at least 2 cards. This means the parameter used must be between 2 and totalNumberOfCards - 2.

Important

New decks take a frame to be created. This means trying to act on them immediately will not work. Use a coroutine or timer to add a delay.

cut(count)

  • count: How many cards down to cut the deck.
    • Optional, if no value is provided the deck is cut in half.

Returned table

  • The table that is returned
    • 1: The lower deck, containing the remaining cards in the deck.
    • 2: The upper deck, containing count number of cards.
newDecks = deck.cut(5)
--A delay would be required here for these next two lines to work.
--The decks haven't been fully created yet.
newDecks[1].deal(1)
newDecks[2].deal(1)

deal(...)

 Deals Objects to hand zones. Will deal from decks/bags/stacks as well as individual items. If dealing an individual item to a hand zone, it is a good idea to make sure that its Member Variable for use_hands is true.

deal(number, player_color, index)

  • number: How many to deal.
  • player_color: The Player Color to deal to.
    • Optional, defaults to an empty string. If not supplied, it will attempt to deal to all seated players.
  • index: Index of hand zone to deal to.
    • Optional, defaults to the first created hand zone.

dealToColorWithOffset(...)

 Deals from a deck to a position relative to the hand zone.

dealToColorWithOffset(offset, flip, player_color)

  • offset: The x/y/z offset to deal to around the given hand zone.
  • flip: If the card is flipped over when dealt.
  • player_color: Hand zone Player Color to offset dealing to.
-- Example of dealing 2 cards in front of the White player, face up.
self.dealToColorWithOffset({-2,0,5}, true, "White")
self.dealToColorWithOffset({ 2,0,5}, true, "White")

jointTo(...)

 Joints objects together, in the same way the Joint tool does.

Using obj.jointTo(), with no object or parameter used as arguments, will remove all joints from that Object.

jointTo(object, parameters)

  • object: The Object that the selected object will be jointed to.
  • parameters: A table of parameters. Which parameters depends on the joint type. See below for more.
  • All parameters have defaults, the same as the Joint Tool.

Example of Fixed: 

self.jointTo(obj, {
    ["type"]        = "Fixed",
    ["collision"]   = true,
    ["break_force"]  = 1000.0,
    ["break_torgue"] = 1000.0,
})

Example of Spring: 

self.jointTo(obj, {
    ["type"]        = "Spring",
    ["collision"]   = false,
    ["break_force"]  = 1000.0,
    ["break_torgue"] = 1000.0,
    ["spring"]      = 50,
    ["damper"]      = 0.1,
    ["max_distance"] = 10,
    ["min_distance"] = 1
})

Example of Hinge: 

self.jointTo(obj, {
    ["type"]        = "Hinge",
    ["collision"]   = true,
    ["axis"]        = {1,1,1},
    ["anchor"]      = {1,1,1},
    ["break_force"]  = 1000.0,
    ["break_torgue"] = 1000.0,
    ["motor_force"]  = 100.0,
    ["motor_velocity"] = 10.0,
    ["motor_free_spin"] = true
})

putObject(...)

 Places an object into a container (chip stacks/bags/decks). If neither Object is a container, but they are able to be combined (like with 2 cards), then they form a deck/stack.

putObject(put_object)

  • put_object: An Object to place into the container.

Returned Object

The container is returned as the Object reference. Either this is the container/deck/stack the other Object was placed into, or the deck/stack that was formed by the putObject action.

Putting Cards into Decks

When you call this putObject() to put a card into a deck, the card goes into the end of the deck which is closest to it in Y elevation. So, if both the card and the deck are resting on the table, the card will be put at the bottom of the deck. if the card is hovering above the deck, it will be put at the top."

-- Example of a script on a bag that places Object into itself
local obj = getObjectFromGUID("AAA111")
self.putObject(obj)

registerCollisions(...)

 Registers this object for Global collision events, such as onObjectCollisionEnter. Always returns true.

registerCollision(stay)

  • stay: Whether we should register for onObjectCollisionStay. Stay events may negatively impact performance, only set this to true if absolutely necessary.
    • Optional, defaults to `false`.

reload()

 Returns Object reference of itself after it respawns itself. This function causes the Object to be deleted and respawned instantly to refresh it, so its old Object reference will no longer be valid.

Most often this is used after using setCustomObject(...) to modify a custom object.

split(...)

 Splits a deck, as evenly as possible, into a number of piles.

Important

New decks take a frame to be created. This means trying to act on them immediately will not work. Use a coroutine or timer to add a delay.

split(piles)

  • piles: How many piles to split the deck into.
    • Optional, if no value is provided, it is split into two piles.
    • Minimum Value: 2
    • Maximum Value: Number-Of-Cards-In-Deck / 2

Returned table

The number of Objects in the table is equal to the number of decks created by the split. They are ordered so any larger decks come first.

  • The table that is returned
    • 1: The first deck created
    • 2: The second deck created
    • 3: The third deck created (etc)
newDecks = deck.split(4)
--A delay would be required here for these next four lines to work.
--The decks haven't been fully created yet.
newDecks[1].deal(1)
newDecks[2].deal(1)
newDecks[3].deal(1)
newDecks[4].deal(1)

takeObject(...)

 Takes an object from a container (bag/deck/chip stack) and places it in the world.

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. It is also possible to add a delay using a Wait function instead.

takeObject(parameters)

  • parameters: A Table of parameters used to determine how takeObject will act.
    • parameters.position: A Vector of the position to place Object.
      • Optional, defaults to container's position + 2 on the x axis.
    • parameters.rotation: A Vector of the rotation of the Object.
      • Optional, defaults to the container's rotation.
    • parameters.flip: If the Object is flipped over.
      • Optional, defaults to false. Only used with decks, not bags/stacks.
      • If rotation is used, flip's Bool will be ignored.
    • parameters.guid: GUID of the Object to take.
      • Optional, no default. Only use index or guid, never both.
    • parameters.index: Index of the Object to take.
      • Optional, no default. Only use index or guid, never both.
    • parameters.top: If an object is taken from the top (vs bottom).
      • Optional, defaults to true.
    • parameters.smooth: If the taken Object moves smoothly or instantly.
      • Optional, defaults to true.
    • parameters.callback_function: Function to activate once the taken Object fully "exists".
      • 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 = "Taken from container!"
    takeParams = {
        position = {x=0, y=3, z=5},
        callback_function = function(obj) take_callback(obj, futureName) end,
    }
    self.takeObject(takeParams)
end

function take_callback(object_spawned, name)
    object_spawned.setName(name)
end
Tip for using GUID to pull Object

When getting the GUIDs of objects in a container, it is possible items can have the same GUID while in a container. This is because only once two items try to exist at the same time is one of them given a new GUID, and Objects in a container do not currently exist. Removing all Objects from the container at once will force all of them to be given unique GUIDs.

Tip for using index to pull Object

When you take an Object from the container, all higher indexes are reduced by 1 instantly. If you pull more than once Object at once by their index, you must account for this index changing.

unregisterCollisions(...)

 Unregisters this object for Global collision events. Returns true if the object was previously registered, false otherwise.

unregisterCollision()

Hide Function Details

setHiddenFrom(...)

 Hides the Object from the specified players, as if it were in a hand zone.

Using an empty table will cause the Object to remove the hiding effect.

setHiddenFrom(players)

  • players: A table containing colors to hide the Object from.
    • (color_name): Strings of the color name of each player.
function onLoad()
    self.setHiddenFrom({"Blue", "White"})
end

Tip

Just like Objects in a hand zone, the player/s the object is hidden from can still interact/move the hidden Object. It still exists to them, but is shown as a question mark or as a hidden card.

setInvisibleTo(...)

 Hides the Object from the specified players, as if it were in a hidden zone.

Using an empty table will cause the Object to remove the hiding effect.

setInvisibleTo(players)

  • players: A table containing colors to hide the Object from.
    • (color_name): Strings of the color name of each player.
function onLoad()
    self.setInvisibleTo({"Blue", "White"})
end

Tip

Just like Objects in a hidden zone, the player/s the object is hidden from can still interact/move the hidden Object. It still exists to them, just invisibly so.

attachHider(...)

 A more advanced version of setHiddenFrom(...), this function is also used to hide objects as if they were in a hand zone. It allows you to identify multiple sources of "hiding" by an ID and toggle the effect on/off easily.

This function is slightly more complicated to use for basic hiding, but allows for much easier hiding in complex situations.

attachHider(id, hidden, players)

  • id: The unique name for this hiding effect.
    • Tip: You can use descriptive tag names like "fog" or "blindness"
  • hidden: If the hiding effect is enabled or not.
  • players: A table containing colors to hide the Object from.
    • Optional, an empty table (or no table) hides for everyone.
    • (color_name): Strings of the color name of each player.
function onLoad()
    --Enable hide
    self.attachHider("hide", true, {"Blue", "White"})
    --Disable hide
    --self.attachHider("hide", false, {"Blue", "White"})
end

Tip

Just like Objects in a hand zone, the player/s the object is hidden from can still interact/move the hidden Object. It still exists to them, but is shown as a question mark or as a hidden card.

attachInvisibleHider(...)

 A more advanced version of setInvisibleTo(...), this function is also used to hide objects as if they were in a hidden zone. It allows you to identify multiple sources of "hiding" by an ID and toggle the effect on/off easily.

This function is slightly more complicated to use for basic hiding, but allows for much easier hiding in complex situations.

attachInvisibleHider(id, hidden, players)

  • id: The unique name for this hiding effect.
    • Tip: You can use descriptive tag names like "fog" or "blindness"
  • hidden: If the hiding effect is enabled or not.
  • players: A table containing colors to hide the Object from.
    • Optional, an empty table (or no table) hides for everyone.
    • (color_name): Strings of the color name of each player.
function onLoad()
    --Enable hide
    self.attachInvisibleHider("hide", true, {"Blue", "White"})
    --Disable hide
    --self.attachInvisibleHider("hide", false, {"Blue", "White"})
end

Tip

Just like Objects in a hidden zone, the player/s the object is hidden from can still interact/move the hidden Object. It still exists to them, just invisibly so.

Global Function Details

addDecal(...)

 Add a Decal onto an object or the game world.

Relative Vectors

When using this function, the vector parameters (position, rotation) are relative to what the decal is being placed on. For example, if you put a decal at {0,0,0} on Global, it will attach to the center of the game room. If you do the same to an object, it will place the decal on the origin point of the object.

addDecal(parameters)

  • parameters: A Table of parameters used to determine how the function will act.
    • parameters.name: The name of the decal being placed.
    • parameters.url: The file path or URL for the image to be displayed.
    • parameters.position: Position to place Object.
    • parameters.rotation: Rotation of the Object.
    • parameters.scale: How the image is scaled.
      • 1 is normal scale, 0.5 would be half sized, 2 would be twice as large, etc.
function onLoad()
    local params = {
        name     = "API Icon",
        url      = "https://api.tabletopsimulator.com/img/TSIcon.png",
        position = {0, 5, 0},
        rotation = {90, 0, 0},
        scale    = {1, 1, 1},
    }
    Global.addDecal(params)
end

call(...)

 Used to call a Lua function on another entity.

Var is only returned if the function called has a return. Otherwise return is nil. See example.

This function can also be used directly on the game world using Global.

call(func_name, func_params)

  • func_name: Function name you want to activate.
  • func_params: A Table containing any data you want to pass to that function.
    • Optional, will not be sent by default.

-- Call, used from an entity's script
params = {
    msg   = "Hello world!",
    color = {r=0.2, g=1, b=0.2},
}
-- Success would be set to true by the return value in the function
success = Global.call("testFunc", params)

-- Function in Global
function testFunc(params)
    broadcastToAll(params.msg, params.color)
    return true
end

getDecals()

 Returns a table of sub-tables, each sub-table representing one decal.

Sub-table elements

  • parameters.name: The name of the decal being placed.
  • parameters.url: The file path or URL for the image to be displayed.
  • parameters.position: Position to place Object.
  • parameters.rotation: Rotation of the Object.
  • parameters.scale: How the image is scaled.
    • 1 is normal scale, 0.5 would be half sized, 2 would be twice as large, etc.

Example returned table: 

-- If this object had 2 of the same decal on it
decalTable = self.getDecals()

--[[ This is what the table would look like
{
    {
        name     = "API Icon",
        url      = "https://api.tabletopsimulator.com/img/TSIcon.png",
        position = {0, 5, 0},
        rotation = {90, 0, 0},
        scale    = {5, 5, 5}
    },
    {
        name     = "API Icon",
        url      = "https://api.tabletopsimulator.com/img/TSIcon.png",
        position = {0, 5, 0},
        rotation = {90, 0, 0},
        scale    = {5, 5, 5}
    },
}
]]--

-- Accessing the name of of the second entry would look like this
print(decalTable[2].name)

getSnapPoints()

 Returns a table of sub-tables, each sub-table representing one snap point.

This function can also be used directly on the game world using Global.

Sub-table contents

  • position: Position of the snap point. The position is relative to the entity's center (a local position).
    • Optional, defaults to {0,0,0}.
  • rotation: Rotation of the snap point. The rotation is relative to the entity's rotation (a local rotation).
    • Optional, defaults to {0,0,0}.
  • rotation_snap: If the snap point is a "rotation" snap point.
    • Optional, defaults to false.

Example: 

function onLoad()
    snapPointList = Global.getSnapPoints()
    log(snapPointsList)
end

Returned table: 

{
    {
        position = {2,2,2},
        rotation = {0,90,0},
        rotation_snap = false
    },
    {
        position = {5,2,5},
        rotation = {0,0,0},
        rotation_snap = true
    },
}

setDecals(...)

 Sets which decals are on an object. This removes other decals already present, and can remove all decals as well.

Removing decals

Using this function with an empty table will remove all decals from Global or the object it is used on. Global.setDecals({})

setDecals(parameters)

  • parameters: The main table, which will contain all of the sub-tables.
    • subtable: The sub-table containing each individual decal's information. The sub-tables are unnamed.
      • parameters.subtable.name: The name of the decal being placed.
      • parameters.subtable.url: The file path or URL for the image to be displayed.
      • parameters.subtable.position: A Vector of the position to place Object.
      • parameters.subtable.rotation: A Vector of the rotation of the Object.
      • parameters.subtable.scale: How the image is scaled.
        • 1 is normal scale, 0.5 would be half sized, 2 would be twice as large, etc.
function onLoad()
    local parameters = {
        {
            name     = "API Icon",
            url      = "https://api.tabletopsimulator.com/img/TSIcon.png",
            position = {-2, 5, 0},
            rotation = {90, 0, 0},
            scale    = 5,
        },
        {
            name     = "API Icon",
            url      = "https://api.tabletopsimulator.com/img/TSIcon.png",
            position = {2, 5, 0},
            rotation = {90, 0, 0},
            scale    = 5,
        },
    }

    Global.setDecals(parameters)
end

setSnapPoints(...)

 Spawns snap points from a list of parameters.

This function can also be used on the game world itself using Global.

setSnapPoints(parameters)

  • parameters: A table containing numerically indexed sub-tables.
    • sub-table:
      • position: Position of the snap point. This is relative to the entity's position (local).
        • Optional, defaults to {0,0,0}.
      • rotation: Rotation of the snap point. This is relative to the entity's rotation (local).
        • Optional, defaults to {0,0,0}.
      • rotation_snap: If the snap point is a "rotation" snap point.
        • Optional, defaults to false.
self.setSnapPoints({
    {
        position = {2,2,2},
        rotation = {0,90,0},
        rotation_snap = false
    },
    {
        position = {5,2,5},
        rotation = {0,0,0},
        rotation_snap = true
    },
})

setVectorLines(...)

 Spawns Vector Lines from a list of parameters.

This function can also be used on the game world itself using Global.

setVectorLines(parameters)

  • parameters: The table containing each "line's" data. Each contiguous line has its own sub-table.
    • points: Table containing Vector positions for each "point" on the line.
    • color: Color the line will be.
      • Optional, defaults to {1,1,1}.
    • thickness: How thick the line is (in Unity units).
      • Optional, defaults to default line size (0.1).
    • rotation: Rotation Vector for the line to be angled.
      • Optional, defaults to {0,0,0}.
function onLoad()
    --Make an X above the middle of the table
    Global.setVectorLines({
        {
            points    = { {5,1,5}, {-5,1,-5} },
            color     = {1,1,1},
            thickness = 0.5,
            rotation  = {0,0,0},
        },
        {
            points    = { {-5,1,5}, {5,1,-5} },
            color     = {0,0,0},
            thickness = 0.5,
            rotation  = {0,0,0},
        },
    })
end