Skip to content

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

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

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)

  •  player_color: Player Color of the Player who dropped the Object.
  •  dropped_object: The Object in game which was dropped.
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

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

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

Called whenever your game is saved, either manually or by auto-save. It is used to allow information to persist through saving/loading. It allows you to place information into a table that is written into the save file. It works on Global information and can also be used to save information onto an Object.

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)
    self.script_state = saved_data
end

Check the onLoad() section for how to load the information you record into your save file.


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 on colliding object.
    •  collision_info.collision_object: Object coming into contact with self.
    •  collision_info.contact_points: Sub-table full of the Vectors where contact took place.
    • collision_info.relative_velocity: Direction and magnitude at the time of collision.

-- Example Usage
function onCollisionEnter(info)
    print(info.collision_object)
end
-- Example returned table
{
    collision_object = objectReference
    contact_points = {
        {x=5, y=0, z=-2, 5, 0, -2},
    }
    relative_velocity = {x=0, y=20, z=0, 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 on colliding object.
    •  collision_info.collision_object: Object leaving contact with self.
    •  collision_info.contact_points: Sub-table full of the Vectors where contact last broke off.
    • collision_info.relative_velocity: Direction and magnitude of the departing Object.

-- Example Usage
function onCollisionExit(info)
    print(info.collision_object)
end
-- Example returned table
{
    collision_object = objectReference
    contact_points = {
        {x=5, y=0, z=-2, 5, 0, -2},
    }
    relative_velocity = {x=0, y=20, z=0, 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.

onCollisionExit(collision_info)

  •  collision_info: A Table containing data on colliding object.
    •  collision_info.collision_object: Object coming into contact with self.
    •  collision_info.contact_points: Sub-table full of the Vectors where contact is taking place.
    • collision_info.relative_velocity: Direction and magnitude of the Object, currently.

-- Example Usage
function onCollisionStay(info)
    print(info.collision_object)
end
-- Example returned table
{
    collision_object = objectReference
    contact_points = {
        {x=5, y=0, z=-2, 5, 0, -2},
    }
    relative_velocity = {x=0, y=20, z=0, 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)

function onDrop(color)
    print(color)
end

onPeek(...)

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

onPeek(player)

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)

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)


onSearchStart(...)

Called when a player finishes searching this Object.

onSearchStart( player_color)