API

The API is consistent for Global or Object Scripts, but Object Scripts have access to self which is the Object the script is attached to. An introduction can be found here.

Classes
Clock
Counter
Object
RPGFigurine
TextTool

Static Classes
JSON
Player
Timer

Default Events

Return Value Function Name Description
none onCollisionEnter( Table collision_info ) This function is called, if it exists in your script, when this Object collides with another Object.The Global Script does not have an onCollisionEnter() event since it does not have a physical representation that can collide.

Collision Info Table:

collision_info.collision_object = Object collision_object
collision_info.contact_points = Table contact_points This is an array (Table) of Tables. Each contact point is a Table {float x, float y, float z}.
collision_info.relative_velocity = Table relative_velocity{float x, float y, float z}
none onCollisionExit( Table collision_info ) This function is called, if it exists in your script, when this Object stops touching another Object.The Global Script does not have an onCollisionEnter() event since it does not have a physical representation that can collide.

Collision Info Table:

collision_info.collision_object = Object collision_object
collision_info.contact_points = Table contact_points This is an array (Table) of Tables. Each contact point is a Table {float x, float y, float z}.
collision_info.relative_velocity = Table relative_velocity{float x, float y, float z}
none onCollisionStay( Table collision_info ) This function is called, if it exists in your script, every frame when this Object is touching another Object until it is resting.The Global Script does not have an onCollisionEnter() event since it does not have a physical representation that can collide.

Collision Info Table:

collision_info.collision_object = Object collision_object
collision_info.contact_points = Table contact_points This is an array (Table) of Tables. Each contact point is a Table {float x, float y, float z}.
collision_info.relative_velocity = Table relative_velocity{float x, float y, float z}
none onDestroy() The onDestroy() function is called, if it exists in your script, when an Object 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 onObjectDestroyed() but their lifetime is the same final frame. The Global Script does not have an onDestroy() event since it never dies.
none onDropped( string player_color ) This function is called, if it exists in your script, when this Object is dropped. The parameter player_color is the color of the Player that dropped the Object. The Global Script does not have an onDropped() event since it does not have a physical representation that can be dropped.
none onLoad( string save_state ) The onLoad() function is called, if it exists in your script, when a game save is finished loading every Object. This is where most setup code will go. The parameter save_state will include the JSON string of the previously saved Lua code state. If there was no previously saved Lua code, this parameter will be an empty string. It is recommended to use an if statement in onLoad() to check wether this parameter is empty or not to use different code paths for loading a game – clean start of a game vs loading a game with existing Lua states. This applies to Rewind and Fast Forward too as they will call the onLoad() function.
none onObjectDestroyed( Object dying_object ) This function is called, if it exists in your script, whenever an 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.
none onObjectDropped( string player_color, Object dropped_object ) This function is called, if it exists in your script, when an Object is dropped. The parameter player_color is the color of the Player that dropped the Object.
none onObjectEnterScriptingZone( Object zone, Object enter_object ) This function is called, if it exists in your script, whenever an Object enters any Scripting Zone that exists in your game.
none onObjectLeaveScriptingZone( Object zone, Object leave_object ) This function is called, if it exists in your script, whenever an Object leaves any Scripting Zone that exists in your game.
none onObjectPickedUp( string player_color, Object picked_up_object ) This function is called, if it exists in your script, when an Object is picked up. The parameter player_color is the color of the Player that picked up the Object.
none onPickedUp( string player_color ) This function is called, if it exists in your script, when this Object is picked up. The parameter player_color is the color of the Player that picked up the Object. The Global Script does not have an onPickedUp() event since it does not have a physical representation that can be picked up.
none onPlayerChangedColor( string player_color ) This function is called, if it exists in your script, whenever a player changes color. You can use this function to run logic when a player joins the game (chooses a color) or leaves the game (will return Grey for spectator – even if they disconnect).
none onPlayerTurnEnd( string player_color_end, string player_color_next ) This function is called, if it exists in your script, at the end of a player’s turn when using the in-game turn system.
none onPlayerTurnStart( string player_color_start, string player_color_previous ) This function is called, if it exists in your script, at the start of a player’s turn when using the in-game turn system.
none onSave() This function is called, if it exists in your script, whenever the game is saved (including auto-saves for Rewinding). Use this function to provide persistence for Lua scripts between saved games. Intended usage: create a Lua Table with all the variables that you want to save, use the JSON class to serialize the Table into a string, and then return the string.
none update() The update() function is called, if it exists in your script, once every frame. Typically you don’t want to add too much code in this function because it can impact game performance. It’s probably best to avoid using this function if possible.

Global Management Functions

Return Value Function Name Description
int addNotebookTab( Table parameters ) Adds a new Tab to the Notebook and returns the index of the newly added Tab. Returns -1 on failure.

Parameters Table:

local params = {}
params.title = string title–Title text for this Tab.
params.body = string body –Optional. Body text for this Tab. BBCode is allowed for styling.
params.color = string color –Optional. Color for this Tab. Defaults to Grey. List of Player Colors.
bool broadcastToAll( string message, {float r, float g, float b} ) Prints a message to the screen and chat window on all connected clients. The last parameter (Table) provides the color of the text to appear in the Game tab chat window. Color values are 0-1.
bool broadcastToColor( string message, string player_color, {float r, float g, float b} ) Prints a private message to the screen and chat window to the player matching the player color. The last parameter (Table) provides the color of the text to appear in the Game tab chat window. Color values are 0-1.
bool clearPixelPaint() Clears all pixel paint.
bool clearVectorPaint() Clears all vector paint.
bool copy( Table objects ) Copies a list of Objects.
bool destroyObject( Object obj ) Destroys/Deletes the given Object.
bool editNotebookTab( Table parameters ) Edits an existing Tab on the Notebook.

Parameters Table:

local params = {}
params.index = int index Index for this Tab.
params.title = string title –Optional. Title text for this Tab.
params.body = string body –Optional. Body text for this Tab. BBCode is allowed for styling.
params.color = string color –Optional. Color for this Tab. List of Player Colors.
bool flipTable() Flip the table in a fit of rage.
Table getAllObjects() Returns a Table of all the spawned Objects in the game.
Table getNotebookTabs() Returns a Table of Tables of all of the Tabs in the Notebook.

Tab Table:

table.index = int index Index for this Tab.
table.title = string title Title text for this Tab.
table.body = string body Body text for this Tab. BBCode is allowed for styling.
table.color = string color Color for this Tab. List of Player Colors.
string getNotes() Returns the current on-screen notes as a string.
Object getObjectFromGUID( string guid ) Gets a reference to an Object from a GUID. Will return nil if the Object doesn’t exist.
Table getSeatedPlayers() Returns an indexed Lua Table of all the players that are currently seated at the table. This will not return spectators (Grey) or the Black player.
Table paste( Table parameters ) Pastes copied Objects and returns a Table as a list of references to the newly spawned Objects

Parameters Table:

local params = {}
params.position = {float x, float y, float z} –Optional. Where to spawn the first pasted Object in the list. Defaults to {0, 3, 0}.
params.snap_to_grid = boolean snap_to_grid –Optional. Should the spawned Objects snap to the grid if the grid is turned on? Defaults to false.
none print( string message ) Prints a message to the chat window only on the host. This should be used for debugging scripts, not for the host cheating in games.
bool printToAll( string message, {float r, float g, float b} ) Prints a message to the chat window on all connected clients. The last parameter (Table) provides the color of the text to appear in the Game tab chat window. Color values are 0-1.
bool printToColor( string message, string player_color, {float r, float g, float b} ) Prints a private message to the chat window to the player matching the player color. The last parameter (Table) provides the color of the text to appear in the Game tab chat window. Color values are 0-1.
bool removeNotebookTab( int index ) Removes a Tab from the Notebook at a given index.
bool setNotes( string notes ) Sets the current on-screen notes. BBCode is allowed for styling.
Object spawnObject( Table parameters ) Spawns an Object at the given position and returns a reference to it. Some operations on the Object will need to wait a frame before you can access them. If you need to immediately use this Object in your script, chances are you will need to put this function call inside a coroutine so you can yield (“wait”) a frame or more for the Object to be fully initialized. Alternatively, you can provide an optional callback function be automatically called when the Object is finished initializing. For a list of valid types of objects that can be spawned, see List of Spawnable Objects.

Parameters Table:

local params = {}
params.type = string type
params.position = {float x, float y, float z} –Optional. Defaults to {0, 3, 0}.
params.rotation = {float x, float y, float z} –Optional. Defaults to {0, 0, 0}.
params.scale = {float x, float y, float z} –Optional. Defaults to {1, 1, 1}.
params.callback = string callback_function_name –Optional.
params.callback_owner = Object callback_owner –Optional. Defaults to the Global Script.
params.snap_to_grid = boolean snap_to_grid –Optional. Should the spawned Objects snap to the grid if the grid is turned on? Defaults to false.
params.params = Table callback_parameters –Optional.
bool startLuaCoroutine( Object function_owner, string function_name ) Starts a Lua function owned by function_owner as a coroutine. Make sure that the Lua function called by ‘startLuaCoroutine’ returns 1 when it’s finished, otherwise you will encounter error messages.
Table stringColorToRGB( string player_color ) Converts a color string (player colors) to their RGB values. The returned Table is keyed as Table[‘r’], Table[‘g’], and Table[‘b’]. Color values are between 0 and 1. Returns nil if an invalid/nonexistant color parameter is provided.