Skip to content

Object

The Object class represents any entity within tabletop simulator. Once you have a reference to an object in your 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 Variables

Common Variables

These are variables that are common to all objects. Some variables are read-only, which means you can query the property, but are unable to assign a new value to it.

Example

Locking/freezing an object by assigning true to locked. 

object.locked = true

Example

Printing whether or not object is locked. 

if object.locked then
    print("Object is locked")
else
    print("Object is not locked")
end

Variable Description Type
alt_view_angle When non-zero, the Alt view will use the specified Euler angle to look at the object.
angular_drag Angular drag. Unity rigidbody property.
auto_raise If the 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.
drag_selectable

When false, the object will not be selected by regular (click and drag) selection boxes that are drawn around the object.

Players may proceed to override this behavior by holding the "Shift" modifier whilst drag selecting.
dynamic_friction Dynamic friction, value of 0-1. Unity physics material.
gizmo_selectable

When false, the object cannot be selected with the Gizmo tool.
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.
held_flip_index 0-23 value. Changes when a Player hits flip or alt + rotate.
held_position_offset Position offset from pointer.
held_reduce_force When the Object collides with something while moving this is automatically enabled and reduces the movement force.
held_rotation_offset Rotation offset from pointer.
held_spin_index 0-23 value. Changes when a Player rotates 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 the object can be interacted with by Players. Other object will still be able to interact with it.
is_face_down If the 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.
locked If the object is frozen in place (preventing physics interactions).
mass Mass. Unity rigidbody property.
max_typed_number

Determines the maximum number of digits which a user may type whilst hovering over the object.

As soon as a player types the maximum number of digits, the corresponding behavior (e.g. onObjectNumberTyped/onNumberTyped) is triggered immediately, improving responsiveness.
measure_movement Measure Tool will automatically be used when moving the Object.
memo A string where you may persist user-data associated with the object. Tabletop Simulator saves this field, but otherwise does not use it. Store whatever information you see fit.
name Internal resource name for this Object. Read only, and only useful for spawnObjectData(). Generally, you want getName().
pick_up_position The position the Object was picked up at. Read only.
pick_up_rotation The rotation the Object was picked up at. Read only.
remainder

If this object is a container that cannot exist with less than two contained objects (e.g. a deck), taking out the second last contained object will result in the container being destroyed. In its place the last remaining object in the container will be spawned.

This variable provides a reference to the remaining object when it is being spawned. Otherwise, it's nil. Read only.
resting If the 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

Use type.

This object's type. Read only.
tooltip If the tooltip opens when a pointer hovers over the object. Tooltips display name and description.
type This object's type. Read only.
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 the Object rotates around when flipped.
use_snap_points If snap points are used or ignored.
value

A numeric value associated with the object, which when non-zero, will be displayed when hovering over the object.

In the case of stacks, the value shown in the UI will be multiplied by the stack size i.e. you can use value to create custom stackable chips.

When multiple objects are selected, values will be summed together with objects sharing overlapping object tags.
value_flags

Use object tags.

A bit field. When objects with overlapping value_flags are selected and hovered over, their values will be summed together.

Behavior Variables

Some objects provide additional behavior. This functionality is accessible as Object member variables, but will be nil unless the Object includes the behavior.

Example

The "Counter" Object has a Counter member variable. We'll use it to increment and retrieve the counter's value. 

object.Counter.increment()
print("The counter value is now " .. object.Counter.getValue())

Variable Type Available On
AssetBundle AssetBundle Custom "AssetBundle" objects.
Book Book "Custom PDF" objects.
Browser Browser "Tablet" objects.
Clock Clock "Digital Clock" objects.
Counter Counter "Counter" objects.
LayoutZone LayoutZone Layout zones.
RPGFigurine RPGFigurine "RPG Kit" animated figurine objects i.e. type "rpgFigurine".
TextTool TextTool 3D Text objects e.g. text created with the in-game Text tool.

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()
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 the merged colliders on an object in Global terms, as if it was rotated to {0,0,0}.
getPosition()
getPosition()
 Returns a Vector of the current World Position.
getPositionSmooth()
getPositionSmooth()
 Returns a Vector of the current smooth move target if the object is smooth moving, otherwise returns nil.
getRotation()
getRotation()
 Returns a Vector of the current rotation.
getRotationSmooth()
getRotationSmooth()
 Returns a Vector of the current smooth rotation target if the object is smooth moving, otherwise returns nil.
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()
getVelocity()
 Returns a Vector of the current velocity.
getVisualBoundsNormalized() Returns a Vector describing the size of the merged renderers on an object in Global terms, as if it was rotated to {0,0,0}.
isSmoothMoving()
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 (World Position) to a local Vector (Local Position).
positionToWorld( vector) Returns a Vector after converting a local Vector (Local Position) to a world Vector (World Position).
rotate( vector) Rotates Object smoothly in the direction of the given Vector.
scale( vector or ) Scales Object by a multiple.
setAngularVelocity(
setAngularVelocity(...)
vector)		 Sets a Vector as the current angular velocity.
setPosition(
setPosition(...)
vector)		 Instantly moves an Object to the given Vector. The Vector is interpreted as World Position.
setPositionSmooth( vector, collide, fast) Moves the Object smoothly to the given Vector. The Vector is interpreted as World Position.
setRotation(
setRotation(...)
vector)		 Instantly rotates an Object to the given Vector.
setRotationSmooth( vector, collide, fast) Rotates the Object smoothly to the given Vector.
setScale(
setScale(...)
vector)		 Sets a Vector as the current scale.
setVelocity(
setVelocity(...)
vector)		 Sets a Vector as the current velocity.
translate(
translate(...)
vector)		 Smoothly moves Object by the given Vector offset.

Tag Functions

These functions deal with the tags associated with the object. An individual tag is a and is case-insensitive.

Function Name
Tag Function Details
 Description Return  
addTag(
addTag(...)
tag)		 Adds the specified tag to the object.
getTags()
getTags()
 Returns a table of tags () that have been added to the object.
hasAnyTag()
hasAnyTag()
 Returns whether the object has any tags.
hasMatchingTag(
hasMatchingTag(...)
other)		 Returns whether the object and the specified other object share at least one tag in common.
hasTag(
hasTag(...)
tag)		 Returns whether the object has the specified tag.
removeTag(
removeTag(...)
tag)		 Removes the specified tag from the object.
setTags(
setTags(...)
tags)		 Replaces all tags on the object with those contained in the specified table (containing ).

If you want to create your own system in which object tags govern the interactions, the canonical logic is that if the system has no tags it interacts with everything, but if it has any tags then it only interacts with objects which share one of them. i.e. (assuming the system is represented by an in-game object): 

allow_interaction = not system.hasAnyTag() or system.hasMatchingTag(object)

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()
clearButtons()
 Removes all scripted buttons.
clearInputs()
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()
getAttachments()
 Returns a table in the same format as getObjects() for containers.
getColorTint()
getColorTint()
 Color tint.
getCustomObject() Returns a Table with the Custom Object information of a Custom Object.
getData()
getData()
 Returns a table data structure representation of the object. Works with spawnObjectData(...).
getDescription()
getDescription()
 Description, also shows as part of Object's tooltip.
getFogOfWarReveal() Settings impacting Fog of War being revealed.
getGMNotes()
getGMNotes()
 Game Master Notes only visible for Player Color Black.
getGUID()
getGUID()
 String of the Object's unique identifier.
getJoints() Returns information on any joints attached to this object.
getJSON(
getJSON(...)
indented)

Returns a JSON string representation of the object. Works with spawnObjectJSON(...).

indented is optional and defaults to true.
getLock()
getLock()
 If the Object is locked.
getName()
getName()
 Name, also shows as part of Object's tooltip.
getObjects() Returns data describing the objects contained within in the zone/bag/deck.
getQuantity()
getQuantity()
 Returns the number of objects contained within (if the Object is a bag, deck or stack), otherwise -1.
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()
getSelectingPlayers()
 Returns a table of the player colors currently selecting the object.
getStateId()
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() Returns the Object's value. This represents something different depending on the Object's type.
getZones() Returns a list of zones that the object is currently occupying.
isDestroyed()
isDestroyed()
 Returns true if the Object is (or will be) destroyed.

Set Functions

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

Function Name Description Return  
setColorTint(
setColorTint(...)
Color)		 Sets the Color tint.
setCustomObject( parameters) Sets a custom Object's properties.
setDescription(
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.
setGMNotes(
setGMNotes(...)
notes)		 Sets Game Master Notes only visible for Player Color Black.
setLock(
setLock(...)
lock)		 Sets if an object is locked in place.
setName(
setName(...)
name)		 Sets a name for an Object. Shows in tooltip.
setRotationValue( rotation_value) Sets the Object's rotation value i.e. physically rotates the object.
setRotationValues( rotation_values) Sets rotation values of an object. Rotation values are used to give value to different rotations (like dice).
setState(
setState(...)
state_id)		 Sets state of an Object. State ids (indexes) start at 1.
setValue( value) Sets the Object's value. This represents something different depending on the Object's type.

Action Function

These functions perform general actions on objects.

Function Name Description Return  
addAttachment(
addAttachment(...)
Object)		 The Object supplied as param is destroyed and becomes a dummy Object child.
addContextMenuItem( label, callback, keep_open) Adds a menu item to the objects right-click context menu.
addToPlayerSelection(
addToPlayerSelection(...)
player_color)		 Adds object to player's selection.
clearContextMenu()
clearContextMenu()
 Clears all menu items added by function addContextMenuItem(...).
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.
destroyAttachment(
destroyAttachment(...)
index)		 Destroys an attachment with the given index.
destroyAttachments()
destroyAttachments()
 Destroys all attachments.
destruct()
destruct()
 Destroys Object. Allows for self.destruct().
drop()
drop()
 Forces an Object, if held by a player, to be dropped.
flip()
flip()
 Flips Object over.
highlightOff(
highlightOff(...)
color)		 Removes a highlight from around an Object.
highlightOn(
highlightOn(...)
color, duration)		 Creates a highlight around an Object. duration is optional and specified in seconds, when omitted the Object remains highlighted.
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(
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.
removeAttachment(
removeAttachment(...)
index)		 Removes a child with the given index. Use getAttachments() to find out the index property.
removeAttachments()
removeAttachments()
 Detaches the children of this Object. Returns a table of object references
removeFromPlayerSelection(
removeFromPlayerSelection(...)
player_color)		 Removes object from player's selection.
reset()
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()
roll()
 Rolls dice/coins.
shuffle()
shuffle()
 Shuffles/shakes up contents of a deck or bag.
shuffleStates()
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.
spread( distance) Uses the spread action on a deck.
takeObject( parameters) Takes an object out of a container (bag/deck/chip stack), returning a reference to the object that was taken out.
unregisterCollisions() Unregisters this object for Global collision events.

Component Functions

Component APIs are an advanced feature. An understanding of how Unity works is required to utilize them. See the Introduction to Components for more information.

Name
Component Function Details
 Return Description
getChild(
getChild(...)
name)		 GameObject Returns a child GameObject matching the specified name.
getChildren()
getChildren()
 Returns the list of children GameObjects.
getComponent(
getComponent(...)
name)		 Component Returns a Component matching the specified name from the Object's list of Components.
getComponentInChildren(
getComponentInChildren(...)
name)		 Component Returns a Component matching the specified name. Found by searching the Components of the Object and its children recursively (depth first).
getComponents(
getComponents(...)
name)		 Returns the Object's list of Components. name is optional, when specified only Components with specified name will be included.
getComponentsInChildren(
getComponentsInChildren(...)
name)		 Returns a list of Components found by searching the Object and its children recursively (depth first). name is optional, when specified only Components with specified name will be included.

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()
getLuaScript()
 Get a Lua script as a string from the entity.
getSnapPoints() Returns a table representing a list of snap points.
getTable(
getTable(...)
table_name)		 Data value of a variable in another Object's script. Can only return a table.
getVar(
getVar(...)
var_name)		 Data value of a variable in another entity's script. Cannot return a table.
getVectorLines()
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(
setLuaScript(...)
script)		 Input a string as an entity's Lua script. Generally only used after spawning a new Object.
setSnapPoints( snap_points) Replaces existing snap points with the specified list of snap points.
setTable(
setTable(...)
func_name, data)		 Creates/updates a variable in another entity's script. Only used for tables.
setVar(
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 the merged colliders on 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

getVisualBoundsNormalized()

Returns a Table of Vector information describing the size of the merged renderers on 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}
}

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 data describing the objects contained within in the zone/bag/deck.

The format of the data returned depends on the kind of object.

Containers (Bags/Decks)

Containers return a (numerically indexed) table consisting of sub-tables that each have the following properties:

Name Type Description
description Description of the contained object.
gm_notes GM Notes on the contained object.
guid GUID of the contained object.
index Index of the contained object, represents the item's order in the container.
lua_script Lua script on the contained object.
lua_script_state Lua script saved state of the contained object.
memo Memo on the contained object.
name

Name of the contained object.

Will correspond with getName(), unless it's blank, in which case it'll be the internal resource name.
nickname

Use name.

Name of the item.
tags A table of representing the tags on the contained object.

Example

Find a contained object with the name "Super Card" (within the Bag/Deck object), and use its index to take the object out of the container. 

-- Iterate through each contained object
for _, containedObject in ipairs(object.getObjects()) do
    if containedObject.name == "Super Card" then
        object.takeObject({
            index = containedObject.index
        })
        break -- Stop iterating
    end
end

Zones

Zones return a (numerically indexed) table of game Objects occupying the zone.

getObjects(ignore_tags=false)

  • ignore_tags: If true then all objects in the zone will be returned, regardless of tags.

Important

If the zone has tags, then only objects with compatible tags will occupy the zone (unless ignore_tags is true).

Example

Highlight red all cards occupying a zone (object), regardless of tag. 

-- Iterate through object occupying the zone
for _, occupyingObject in ipairs(object.getObjects(true)) do
    if occupyingObject.type == "Card" then
        occupyingObject.highlightOn('Red')
    end
end

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

Returns the Object's value. This represents something different depending on the Object's type.

Important

If the Object has rotation values, then this method will return the rotation value i.e. behave the same as getRotationValue().

See setValue(...) for more information.

getZones()

Returns a list of zones that the object is currently occupying.

Important

If the object has tags, then the object will only occupy zones with compatible tags.

Example

Print a comma separated list of GUIDs belonging to zones an object is currently occupying. 

local guids = {}

for _, zone in ipairs(object.getZones()) do
    table.insert(guids, zone.guid)
end

if #guids > 0 then
    print("Object is contained within " .. table.concat(guids, ", "))
else
    print("Object is not contained within any zones")
end

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

  • fog_settings: 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)

setRotationValue(...)

Sets the Object's rotation value i.e. physically rotates the object.

setRotationValue(rotation_value)

The Object will be elevated (smooth moved upward), smoothly rotated to the rotation corresponding with the specified rotation_value and then released to fall back into place.

Example

Rotate a die to show the value 6. 

die.setRotationValue(6)

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".
    • value: Value associated with the rotation. Should be a , or .
      • If `value` is a string starting with "#", then it will not be displayed in the Object's tooltip.
    • rotation: The rotation of the Object that corresponds with the provided value.

Example

Set the two different sides (rotations) of a coin to have the values "Heads" and "Tails". 

self.setRotationValues({
    {
        value="Heads",
        rotation={x=0, y=0, z=0}
    },
    {
        value="Tails",
        rotation={x=180, y=0, z=0}
    },
})

setValue(...)

Sets the Object's value. This represents something different depending on the Object's type.

Important

If the Object has rotation values, then this method will set the rotation value i.e. behave the same as setRotationValue(...).

setValue(value)

  • value: The value to set. Represents something different depending on the Object's type. Refer to the value type table.
Object Type Value Type Description
3D Text Replaces the 3D Text's content.
Clock Sets the remaining "Stopwatch" time (in seconds) on the Clock.
Counter (Digital Counter) Sets the counter's value.
Fog (Hidden Zone) Changes the hidden zone owner to the specified Player Color.
Hand (Hand Zone) Changes the hand owner to the specified Player Color.
Tablet Loads the specified URL in the tablet's browser.

Action Function Details

addContextMenuItem(...)

Adds a menu item to the objects right-click context menu.

addContextMenuItem(label, callback, keep_open)

  • label: Label for the menu item.
  • callback: Execute if menu item is selected. Called as callback(player_color, object_position, object)
    • player_color Player Color who selected the menu item.
    • object_position Position of object.
    • object Object in question.
  • keep_open: Keep context menu open after menu item was selected.
    • Optional, Default: keep_open = false. Close context menu after selection.
function onLoad()
    self.addContextMenuItem("doStuff", itemAction)
end

function itemAction(player_color, position, object)
    log({player_color, position, object})
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_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)

spread(...)

Spreads the cards of a deck out on the table.

Important

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

spread(distance)

  • distance: How far apart should the cards be.
    • Optional, if no value is provided, they will be 0.6 inches apart.
    • Negative values will spread to the left instead of the right.

Returned table

The number of Objects in the table is equal to the number of cards in the deck. They are returned in the order they were in the deck.

  • The table that is returned
    • 1: The first card in the deck
    • 2: The second card in the deck
    • 3: The third card in the deck (etc)

takeObject(...)

Takes an object out of a container (bag/deck/chip stack), returning a reference to the object that was taken.

Objects that are taken out of a container will take one or more frames to spawn. Certain interactions (e.g. physics) will not be able to take place until the object has finished spawning.

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: Callback which will be called when the taken object has finished spawnning.
      • Optional, no default.
      • This function takes a single parameter: the object that was taken.

Caution

Certain containers only exist whilst they have more than one object contained within them (e.g. decks). Once you remove the second last object from a container, the container will be destroyed and the remaining contained object will spawn in its place. After calling takeObject(...) you can check for a remainder.

Example

Take an object out of a container. As we take it out we'll instruct the object to smooth move (default positioning behavior) to coordinates (0, 5, 0). Additionally, we're going to add a blue highlight on the object we've taken out. 

local takenObject = container.takeObject({
    position = {x = 0, y = 5, z = 0},
})
takenObject.highlightOn('Blue')

Advanced example

Take an object out of a container, and then apply an upward force (impulse) shooting it into the air.

We can only apply an impulse to an object once its (underlying rigid body) has finished spawning Additionally, freshly spawned objects are frozen in place for a single frame. So we need to wait for the taken object to finish spawning (i.e. callback_function) then wait one more frame before applying the impulse.

container.takeObject({
    callback_function = function(spawnedObject)
        Wait.frames(function()
            -- We've just waited a frame, which has given the object time to unfreeze.
            -- However, it's also given the object time to enter another container, if
            -- it spawned on one. Thus, we must confirm the object is not destroyed.
            if not spawnedObject.isDestroyed() then
                spawnedObject.addForce({0, 30, 0})
            end
        end)
    end,
    smooth = false, -- Smooth moving objects cannot have forces applied to them.
})

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 representing a list of snap points.

Tip

This function may be called on Global in order to return a list of global snap points (i.e. snap points on the table).

Return value

The returned value is a list (numerically indexed table) of sub-tables, where each sub-table represents a snap point and has the following properties:

Name Type Description
position Vector Local Position of the snap point. When attached to an object, position is relative to the object's center.
rotation Vector Local Rotation of the snap point. When attached to an object, rotation is relative to the object's rotation.
rotation_snap Whether the snap point is a rotation snap point.
tags Table of representing the tags associated with the snap point.

Example

Log the list of global snap points: 

log(Global.getSnapPoints())

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

Replaces existing snap points with the specified list of snap points.

Tip

This function can also be called on Global in order to create snap points directly within the scene, which are not attached to any other Object.

setSnapPoints(snap_points)

  • snap_points: A list (numerically indexed table) of snap points.
Snap Points

snap_points must be provided as a list (numerically indexed table) of sub-tables, where each sub-table represents a snap point and may have the following properties:

Name Type Default Description
position {0, 0, 0} Local Position of the snap point. When attached to an object, position is relative to the object's center.
rotation {0, 0, 0} Local Rotation of the snap point. When attached to an object, rotation is relative to the object's rotation.
rotation_snap false Whether the snap point is a rotation snap point.
tags {} Table of representing the tags associated with the snap point.

All properties are optional. When a property is omitted, it will be given the corresponding default value (above).

Example

Give an object 3 snap points. A regular snap point, a rotation snap point, and a rotation snap point with a tag. 

object.setSnapPoints({
    {
        position = {5, 2, 5}
    },
    {
        position = {5, 2, 5},
        rotation = {0, 180, 0},
        rotation_snap = true
    },
    {
        position = {-3, 2, 0},
        rotation = {0, 45, 0},
        rotation_snap = true,
        tags = {"meeple"}
    }
})

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