

Event

Events are functions which are activated by Tabletop Simulator when something takes place in-game. It is possible to use all of them within scripts on Objects, and most will also work in Global scripts.

Many contain parameters which can be used to utilize additional information related to the event.

Function Summary

Default Events (Global & Object)

These are functions which are triggered by an event taking place in-game. They work when within the script of an Object or the Global script.

Function Name	Description
filterObjectEnterContainer( container,  enter_object)	Called when an object attempts to enter any container. The object is prevented from entering unless "true" is returned.
onChat( message,  sender)	Called when a chat message is sent in game chat.
onExternalMessage( data)	Called when an external script editor (like Atom) sends a message back to the game. Used for custom editor functionality.
onFixedUpdate()	Called every physics tick (90 times a second). This is a frame independent onUpdate().
onLoad( save_state)	Called when a game save is finished loading every Object. It is where most setup code will go.
onObjectCollisionEnter( registered_object,  collision_info)	Called when an Object starts colliding with a collision registered Object.
onObjectCollisionExit( registered_object,  collision_info)	Called when an Object stops colliding with a collision registered Object.
onObjectCollisionStay( registered_object,  collision_info)	Called every frame that an Object is colliding with a collision registered Object.
onObjectDestroy( dying_object)	Called whenever any object is destroyed.
onObjectDrop( player_color,  dropped_object)	Called whenever any object is dropped by a player.
onObjectEnterScriptingZone( zone,  enter_object)	Called when any object enters any scripting zone.
onObjectEnterContainer( container,  enter_object)	Called when any object enters any container. Includes decks
onObjectLeaveScriptingZone( zone,  enter_object)	Called when any object leaves any scripting zone.
onObjectLeaveContainer( container,  leave_object)	Called when any object leaves any container.
onObjectLoopingEffect( loop_object,  index)	Called whenever the looping effect of an AssetBundle is activated.
onObjectPageChange( object)	Called when a Custom PDF object changes page.
onObjectPeek( object,  player)	Called when a player using peek to look under an Object.
onObjectPickUp( player_color,  picked_up_object)	Called whenever a Player picks up an Object.
onObjectRandomize( randomize_object,  player_color)	Called when an Object is randomized. Like when shuffling a deck or shaking dice.
onObjectSearchEnd( obj,  player_color)	Called when a search is finished on any container.
onObjectSearchStart( obj,  player_color)	Called when a search is started on any container.
onObjectSpawn( spawn_object)	Called when any Object is spawned/created.
onObjectTriggerEffect( trigger_object,  index)	Called whenever the trigger effect of an AssetBundle is activated.
onPlayerChangeColor( player_color)	Called when a player changes color or selects it for the first time. It also returns "Grey" if they disconnect.
onPlayerConnect( person)	Called when a Player connects to a game.
onPlayerDisconnect( person)	Called when a Player disconnects from a game.
onPlayerTurn( player_color)	Called at the start of a player's turn when using the in-game turn system.
onSave()	Called whenever your game is saved.
onScriptingButtonDown( index,  player_color)	Called when a scripting button (numpad by default) is pressed. The index range that is returned is 1-10.
onScriptingButtonUp( index,  player_color)	Called when a scripting button (numpad by default) is released. The index range that is returned is 1-10.
onUpdate()	Called every frame.

Default Events (Object Only)

These are functions which are triggered by an event taking place in-game. They only work within scripts that are on Objects, never in Global.

Function Name	Description
filterObjectEnter( obj)	Called when an object attempts to enter this object. The object is prevented from entering unless "true" is returned.
onCollisionEnter( collision_info)	Called when an Object starts colliding with the Object the function is on.
onCollisionExit( collision_info)	Called when an Object stops colliding with the Object the function is on.
onCollisionStay( collision_info)	Called every frame that an Object is colliding with the Object this function is on.
onDestroy()	Called when an Object it is on is destroyed.
onDrop( player_color)	Called when a player releases an Object after picking it up.
onPageChange()	Called when a Custom PDF page is changed.
onPeek( player)	Called when a player using peek to look under this Object.
onPickUp( player_color)	Called when a player picks up an Object.
onRandomize( player_color)	Called when this Object is randomized. Like when shuffling a deck or shaking dice.
onSearchEnd( player_color)	Called when a player finishes searches this Object.
onSearchStart( player_color)	Called when a player starts searching this Object.

---

Function Details (Global & Object)

filterObjectEnterContainer(...)

Called when an object attempts to enter a container. The object is prevented from entering unless "true" is returned.

filterObjectEnter(container, enter_object)

•  container: The container the Object is trying to enter.
•  enter_object: The Object entering the container.

function filterObjectEnterContainer(container, enter_object)
    print(enter_object.getName()) -- Print entering object's name
    return true -- Allows object to enter.
end

---

onChat(...)

This function is called when a message is sent through the in-game chat. It does not trigger when global chat messages are sent. Using return false inside of this function prevents the chat message which triggered it to be suppressed.

onChat(message, sender)

•  message: Chat message which triggered the function.
•  sender: Player which sent the chat message.

function onChat(message, player)
    print(message)
    print(player.color)
end

---

onExternalMessage(...)

This function is called when an external script editor (like Atom) sends a message back to the game. Used for custom editor functionality.

onExternalMessage(data)

•  data: The data returned by the external editor into the game.

function onExternalMessage(data)
    print("External message received")
end

---

onFixedUpdate()

Called every physics tick (90 times a second). This is a frame independent onUpdate().

Warning

This is a very expensive function and can easily slow/crash your game if misused. Use with caution.

function onFixedUpdate()
    self.addTorque({0,100,0}, 1)
end

onLoad(...)

This function is called when a game save is finished loading every Object. This is where most setup code will go. The fast-forward and rewind feature will also cause this function to activate. If this function is in an Object's script and that Object is spawned, like by removing it from a container, it too will trigger onLoad().

onLoad(save_state)

•  save_state: The encoded string containing any save_state (saved) data.
  • If there is no data saved, this returns an empty String.

function onLoad()
    print("Loading complete")
end

Example of onLoad and onSave being used to save/load data

-- Runs whenever game is saved/autosaved
function onSave()
    local data_to_save = {someData=50}
    saved_data = JSON.encode(data_to_save)
    --saved_data = "" --Remove -- at start & save to clear save data
    return saved_data
end

-- Runs when game is loaded
function onLoad(saved_data)
    -- Loads the tracking for if the game has started yet
    if saved_data ~= "" then
        local loaded_data = JSON.decode(saved_data)
        someData = loaded_data.someData
    else
        someData = 50
    end
end

---

onObjectCollisionEnter(...)

This function is called when an Object starts colliding with a collision registered Object.

onObjectCollisionEnter(registered_object, collision_info)

•  registered_object: The object registered to receive collision events.
•  collision_info: A table containing data about the collision.
  •  collision_info.collision_object: Object coming into contact with registered_object.
  •  collision_info.contact_points: Table/array full of contact points, where each 3D point is represented by a (number indexed) table, not a Vector.
  • collision_info.relative_velocity: Table (number indexed) representation of a 3D vector (but not a Vector) indicating the direction and magnitude of the collision.

-- Example Usage
function onObjectCollisionEnter(registered_object, info)
    print(tostring(info.collision_object) .. " collided with " .. tostring(object))
end

-- Example collision_info table
{
    collision_object = objectReference,
    contact_points = {
        {5, 0, -2}
    },
    relative_velocity = {0, 20, 0}
}

---

onObjectCollisionExit(...)

This function is called when an Object stops colliding with a collision registered Object.

onObjectCollisionExit(registered_object, collision_info)

•  registered_object: The object registered to receive collision events.
•  collision_info: A table containing data about the collision.
  •  collision_info.collision_object: Object leaving contact with registered_object.
  •  collision_info.contact_points: Table/array full of contact points, where each 3D point is represented by a (number indexed) table, not a Vector.
  • collision_info.relative_velocity: Table (number indexed) representation of a 3D vector (but not a Vector) indicating the velocity of the object that has moved out of contact.

-- Example Usage
function onObjectCollisionExit(registered_object, info)
    print(tostring(info.collision_object) .. " stopped colliding with " .. tostring(object))
end

-- Example collision_info table
{
    collision_object = objectReference,
    contact_points = {
        {5, 0, -2}
    },
    relative_velocity = {0, 20, 0}
}

---

onObjectCollisionStay(...)

This function is called every frame that an Object is colliding with a collision registered Object.

Warning

This is a very expensive function and can easily slow/crash your game if misused. Use with caution.

onObjectCollisionStay(registered_object, collision_info)

•  registered_object: The object registered to receive collision events.
•  collision_info: A table containing data about the collision.
  •  collision_info.collision_object: Object coming into contact with registered_object.
  •  collision_info.contact_points: Table/array full of contact points, where each 3D point is represented by a (number indexed) table, not a Vector.
  • collision_info.relative_velocity: Table (number indexed) representation of a 3D vector (but not a Vector) indicating the direction and magnitude of the collision.

-- Example Usage
function onObjectCollisionStay(registered_object, info)
    print(tostring(info.collision_object) .. " still colliding with " .. tostring(object))
end

-- Example collision_info table
{
    collision_object = objectReference,
    contact_points = {
        {5, 0, -2}
    },
    relative_velocity = {0, 20, 0}
}

---

onObjectDestroy(...)

Called whenever any object is destroyed. The dying Object has 1 frame left to live. This event fires immediately before the dying Object’s onDestroy() but their lifetime is the same final frame.

onObjectDestroy(dying_object)

•  dying_object: The object that was destroyed.

function onObjectDestroy(destroyedObj)
    print(destroyedObj.getName())
end

---

onObjectDrop(...)

Called whenever any object is dropped by a player.

onObjectDrop(player_color, dropped_object)

•  dropped_object: The Object in game which was dropped.
•  player_color: Player Color of the Player who dropped the Object.

function onObjectDrop(colorName, obj)
    print(colorName .. " dropped " .. obj.getName())
end

---

onObjectEnterScriptingZone(...)

Called when any object enters any scripting zone.

onObjectEnterScriptingZone(zone, enter_object)

•  zone: The Object of the scripting zone.
•  enter_object: The Object triggering the function.

function onObjectEnterScriptingZone(zone, obj)
    print(obj.getGUID())
end

---

onObjectEnterContainer(...)

Called when any object enters any container. Includes Objects entering decks.

onObjectEnterContainer(container, enter_object)

•  container: Container the Object entered.
•  enter_object: Object that entered the container.

function onObjectEnterContainer(bag, obj)
    print(bag)
    print(obj)
end

---

onObjectLeaveScriptingZone(...)

Called when any object leaves any scripting zone.

onObjectLeaveScriptingZone(zone, enter_object)

•  zone: The Object of the scripting zone.
•  enter_object: The Object triggering the function.

function onObjectLeaveScriptingZone(zone, obj)
    print(obj.getGUID())
end

---

onObjectLeaveContainer(...)

Called when any object leaves any container.

onObjectLeaveContainer(container, leave_object)

•  container: Container the object left.
•  leave_object: Object that left the container.

function onObjectLeaveContainer(bag, obj)
    print(bag)
    print(obj)
end

---

onObjectLoopingEffect(...)

Called whenever the looping effect of an AssetBundle is activated.

onObjectLoopingEffect(loop_object, index)

•  loop_object: AssetBundle which had its loop activated.
•  index: Index number for the loop activated.

function onObjectLoopingEffect(obj, index)
    print("Loop " .. index .. " activated.")
end

---

onObjectPageChange(...)

Called when an object's Custom PDF page is changed.

function onObjectPageChange(obj)
    print(obj.getName() .. "changed page to " .. obj.Book.getPage()) -- Print new page.
end

---

onObjectPeek(...)

Called when a player using peek to look under an Object.

onObjectPeek(object, player)

•  object: A reference to the Object which was peeked at.
•  player: Name of the Player Color that peeked.

function onObjectPeek(object, color)
    printToAll(color .. " peeked at an Object.", {1,0,0})
end

---

onObjectPickUp(...)

Called whenever a Player picks up an Object.

onObjectPickUp(player_color, picked_up_object)

•  player_color: Player Color of the Player who picked up the object.
•  picked_up_object: The Object in game which was picked up.

function onObjectPickUp(colorName, obj)
    print(colorName .. " picked up " .. obj.getName())
end

---

onObjectRandomize(...)

Called when an Object is randomized. Like when shuffling a deck or shaking dice.

onObjectRandomize(randomize_object, player_color)

•  spawn_object: The Object which triggered this function.
•  player_color: Player Color of the player who triggered the function.

function onObjectRandomize(obj, color)
    print(obj.getName() .. " was randomized by " .. color)
end

---

onObjectSearchEnd(...)

Called when a search is finished on any container.

onObjectSearchEnd(obj, player_color)

•  obj: The Object which was searched.
•  player_color: Player Color of the player who triggered the function.

---

onObjectSearchStart(...)

Called when a search is started on any container.

onObjectSearchStart(obj, player_color)

•  obj: The Object which was searched.
•  player_color: Player Color of the player who triggered the function.

---

onObjectSpawn(...)

Called when any Object is spawned/created.

onObjectSpawn(spawn_object)

•  spawn_object: The Object which triggered this function.

function onObjectSpawn(obj)
    print(obj)
end

---

onObjectTriggerEffect(...)

Called whenever the trigger effect of an AssetBundle is activated.

onObjectTriggerEffect(loop_object, index)

•  loop_object: AssetBundle which had its trigger activated.
•  index: Index number for the trigger activated.

function onObjectTriggerEffect(obj, index)
    print("Loop " .. index .. " activated.")
end

---

onPlayerChangeColor(...)

Called when a player changes color or selects it for the first time. It also returns "Grey" if they disconnect.

onPlayerChangeColor(player_color)

•  player_color: Player Color of the player who triggered the function.

function onPlayerChangeColor(color)
    print(color)
end

---

onPlayerConnect(...)

Called when a Player connects to a game.

onPlayerConnect(person)"

•  person: Player reference to who connected.

---

onPlayerDisconnect(...)

Called when a Player disconnects from a game.

onPlayerDisconnect(person)"

•  person: Player reference to who disconnected.

---

onPlayerTurn(...)

Called at the start of a player's turn when using the in-game turn system.

onPlayerTurn(player_color)

•  player_color: Player Color of the player who's turn is starting.

function onPlayerTurn(color)
    print(color .. "'s turn starts now.")
end

---

onSave()

This is called whenever the game saves, either manually or by auto-save. This will work in both a Global script, and an Object script. It is used to allow information to persist through saving/loading, for example, to let your script remember its data previously after hitting the Undo or Redo button. By placing script information into a Lua table, then encoding that data into JSON, you are able to save information about the script's current state onto the script's parent, in the form of a string. You can also return a string value in this function to stash it.

Important

When using onSave(), information is saved into the save file you are using. Using Save & Apply does NOT cause it to record data, only overwriting your save will update what information onSave() is trying to record.

Warning

You can save almost any data in a table using this function, but Object references DO NOT persist. If you need to record an Object using onSave(), record its GUID instead.

data_table = {answer=42}

function onSave()
    saved_data = JSON.encode(data_table)
    return saved_data
end

Check the onLoad() section for how to load that stored JSON information into your script.

---

onScriptingButtonDown(...)

Called when a scripting button (numpad by default) is pressed. The index range that is returned is 1-10.

onScriptingButtonDown(index, player_color)

•  index: Index number, representing which key was pressed.
•  player_color: Player Color of the player who triggered the function.

function onScriptingButtonDown(index, color)
    print(index)
end

---

onScriptingButtonUp(...)

Called when a scripting button (numpad by default) is released. The index range that is returned is 1-10.

onScriptingButtonUp(index, player_color)

•  index: Index number, representing which key was released.
•  player_color: Player Color of the player who triggered the function.

function onScriptingButtonUp(index, color)
    print(index)
end

---

onUpdate()

Called every frame.

Warning

This is a very expensive function and can easily slow/crash your game if misused. Use with caution.

function onUpdate()
    print("This will probably slow your game down.")
end

---

---

Function Details (Object only)

onCollisionEnter(...)

This function is called when an Object starts colliding with the Object the function is on. Does not work in Global.

onCollisionEnter(collision_info)

•  collision_info: A table containing data about the collision.
  •  collision_info.collision_object: Object coming into contact with self.
  •  collision_info.contact_points: Table/array full of contact points, where each 3D point is represented by a (number indexed) table, not a Vector.
  • collision_info.relative_velocity: Table (number indexed) representation of a 3D vector (but not a Vector) indicating the direction and magnitude of the collision.

-- Example Usage
function onCollisionEnter(info)
    print(tostring(info.collision_object) .. " collided with " .. tostring(self))
end

-- Example collision_info table
{
    collision_object = objectReference,
    contact_points = {
        {5, 0, -2}
    },
    relative_velocity = {0, 20, 0}
}

---

onCollisionExit(...)

This function is called when an Object stops colliding with the Object the function is on. Does not work in Global.

onCollisionExit(collision_info)

•  collision_info: A table containing data about the collision.
  •  collision_info.collision_object: Object leaving contact with self.
  •  collision_info.contact_points: Table/array full of contact points, where each 3D point is represented by a (number indexed) table, not a Vector.
  • collision_info.relative_velocity: Table (number indexed) representation of a 3D vector (but not a Vector) indicating the velocity of the object that has moved out of contact.

-- Example Usage
function onCollisionExit(info)
    print(tostring(info.collision_object) .. " stopped colliding with " .. tostring(self))
end

-- Example collision_info table
{
    collision_object = objectReference,
    contact_points = {
        {5, 0, -2}
    },
    relative_velocity = {0, 20, 0}
}

---

onCollisionStay(...)

This function is called every frame that an Object is colliding with the Object this function is on. Does not work in Global.

Warning

This is a very expensive function and can easily slow/crash your game if misused. Use with caution.

onCollisionStay(collision_info)

•  collision_info: A table containing data about the collision.
  •  collision_info.collision_object: Object coming into contact with self.
  •  collision_info.contact_points: Table/array full of contact points, where each 3D point is represented by a (number indexed) table, not a Vector.
  • collision_info.relative_velocity: Table (number indexed) representation of a 3D vector (but not a Vector) indicating the direction and magnitude of the collision.

-- Example Usage
function onCollisionStay(info)
    print(tostring(info.collision_object) .. " still colliding with " .. tostring(self))
end

-- Example collision_info table
{
    collision_object = objectReference,
    contact_points = {
        {5, 0, -2}
    },
    relative_velocity = {0, 20, 0}
}

---

onDestroy()

This function is called when an Object it is on is destroyed. When onDestroy() is called, the Object has one frame left to live but its recommended to avoid using it as a reference here. This event fires immediately after onObjectDestroy() but their lifetime is the same final frame. Does not work in Global.

function onDestroy()
    print("This object was destroyed!")
end

---

onDrop(...)

This function is called when this Object is dropped. Does not work in Global.

onDrop(player_color)

•  player_color: Player Color of the Player.

function onDrop(color)
    print(color)
end

---

onPageChange()

Called when this object's Custom PDF page is changed.

function onPageChange()
    print(self.getName() .. "changed page to " .. self.Book.getPage()) -- Print new page.
end

---

filterObjectEnter(...)

Called when an object attempts to enter this object. The object is prevented from entering unless "true" is returned.

filterObjectEnter(obj)

•  obj: The object that has tried to enter the object this script is attached to.

function filterObjectEnter(obj)
    print(obj.getName()) -- Print entering object's name
    return true -- Allows object to enter.
end

---

onPeek(...)

Called when a player using peek to look under an Object.

onPeek(player)

•  player: Name of the Player Color that peeked.

function onPeek(color)
    printToAll(color .. " peeked at an Object.", {1,0,0})
end

---

onPickUp(...)

Called when a player picks up an Object.

onPickUp(player_color)

•  player_color: Player Color of the Player.

function onPickUp(color)
    print(color)
end

---

onRandomize(...)

Called when an Object is randomized. Like when shuffling a deck or shaking dice.

onRandomize(player_color)

•  player_color: Player Color of the player who triggered the function.

function onRandomize(color)
    print(self.getName() .. " was randomized by " .. color)
end

---

onSearchEnd(...)

Called when a player first searches this Object.

onSearchEnd( player_color)

•  player_color: Player Color of the Player.

---

onSearchStart(...)

Called when a player finishes searching this Object.

onSearchStart( player_color)

•  player_color: Player Color of the Player.

---