Skip to content

Object

The Object class represents any entity within tabletop simulator. Once you have a reference to an object in youre 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 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.
interactable If an object can be interacted with by Players. Other object will still be able to interact with it.
loading_custom If the Object's custom elements (images/models/etc) are loading. Read only.
mass Mass. Unity rigidbody property.
name The Object's name. Read only, use setName("") to write to it.
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_snap_points If snap points are used or ignored.

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.
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  
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.
getGUID() String of the Object's unique identifier.
getJSON() Returns a serialization of the JSON string which represents this item. Works with spawnObjectJSON().
getLock() If the Object is locked.
getLuaScript() Get a Lua script as a string.
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).
getSnapPoints() Returns a table of sub-tables, each sub-table representing one snap point.
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.
getTable( func_name) Data value of a variable in another Object's script. Can only return a table.
getValue() Object value. What the value represents depends on what type of Object this function is used on.
getVar( func_name) Data value of a variable in another Object's script. Cannot return a table.

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.
setLock( lock) Sets if an object is locked in place.
setLuaScript( script) Input a string as an Object's Lua script. Generally only used after spawning a new Object.
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).
setSnapPoints( parameters) Spawns snap points from a list of parameters.
setState( state_id) Sets state of an Object. State ids (indexes) start at 1.
setTable( func_name,  data) Creates/updates a variable in another Object's script. Only used for tables.
setValue( value) Sets an Int as the value. What the value represents depends on what type of Object it is.
setVar( func_name,  data) Creates/updates a variable in another Object's script. Cannot set a table.

Action Function

These functions perform general actions on objects.

Function Name Description Return  
call( func_name,  func_params) Used to call a Lua function on this Object.
flip() Flip 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().
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() Shuffles deck/bag, rolls dice/coin, lifts other objects into the air. Same as pressing R by default.
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.

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 Spawnable 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,
}

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

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

  • name: Name of the Object.
  • guid: GUID of the Object.
  • index: Index of the Object, represents the Object's place in the bag.
{
    {
        name  = "Object Name",
        guid  = "AAA111",
        index = 0,
    },
}

Deck

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

  • nickname: Name of the card.
  • description: Description of the card.
  • guid: GUID of the card.
  • index: Index of the card, represents the card's order in the deck.
  • lua_script: Any Lua scripting saved on the card.
{
    {
        nickname    = "Object Name",
        description = "Object Descripotion",
        guid        = "AAA111",
        index       = 0,
        lua_script  = "Any Lua Script On This Card",
    },
}

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.
  • 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}},
}

getSnapPoints()

 Returns a table of sub-tables, each sub-table representing one snap point. You can also use this as a Global Base function. This function will only return information on snap points attached to Objects unless you use it without an Object. See an example on its entry under the Base page.

Sub-table contents

  • position: Position of the snap point. The position is relative to the Object's center (a local position).
    • Optional, defaults to {0,0,0}.
  • rotation: Rotation of the snap point. The rotation is relative to the Object'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:

snapPointList = self.getSnapPoints()
log(snapPointsList)

Returned table:

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


getStates()

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

Return Table

  •  name: Name of the Object.
  •  guid: GUID of the Object.
  •  id: ID (index) of the state.
-- Example returned Table
{
    {
        name = "First State",
        guid = "AAA111",
        id   = 1,
    },
    {
        name = "Second State",
        guid = "BBB222",
        id   = 2,
    },
}

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 Spawnable Object 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)

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

setSnapPoints(...)

 Spawns snap points from a list of parameters. You can also use this as a Global Base function. This function will only attach snap points to Objects unless you use it without an Object. See an example on its entry under the Base page.

setSnapPoints(parameters)

  • parameters: A table containing numerically indexed sub-tables.
    • sub-table:
      • position: Position of the snap point. This is relative to the Object's position (local).
        • Optional, defaults to {0,0,0}.
      • rotation: Rotation of the snap point. This is relative to the Object'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
    },
})

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

call(...)

 Used to call a Lua function on this Object. This is used to remotely call functions in other scripts, either in Global or Object scripts. Global is the "Object" to use to call a function in the Global script.

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

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 Object 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


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_freeSpin"] = 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.

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

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.