Skip to main content

Global Events

Scripts can contain special "event" functions that will be automatically called by the program. The functions for global events must be declared in the global scope (i.e. without the local keyword). You can use events to write code that will be run when specific things happen in your world (for example, when an entity is destroyed).

To use an event, you just need to declare a global function matching the name of the event. The following events are available.

onStart()

This function is called when the program starts running.

Example

function onStart()
-- Any code here will be run when the program starts.
end

onDestroy(clientId)

This function is called when the Entity running the program is destroyed.

Example

function onDestroy(clientId)
-- Any code here will be run when the entity is destroyed.
-- 'clientId' will contain the ID of the player who destroyed the entity
-- or nil, if it was not destroyed by a player.
end
caution

Since the entity has been destroyed, any code in onDestroy must finish in one frame — the program will stop running on the next frame, so no further code will run.

onPlayerJoin(player)

This function is called when a player joins the server.

Example

function onPlayerJoin(player)
-- Any code here will be run when a player joins the server.
-- 'player' will contain the player that joined the server.
end

onPlayerLeave(player)

This function is called when a player leaves the server.

Example

function onPlayerLeave(player)
-- Any code here will be run when a player leaves the server.
-- 'player' will contain the player that left the server.
end

onPlayerSpawn(player)

This function is called when a player spawns in the world.

Example

function onPlayerSpawn(player)
-- Any code here will be run when a player spawns in the world.
-- 'player' will contain the player that just spawned.
end

onPlayerDestroy(player)

This function is called when any player in the world is destroyed.

Example

function onPlayerDestroy(player)
-- Any code here will be run when a player in the world is destroyed.
-- 'player' will contain the player that was just destroyed.
end

onPlayerEnter(player)

This function is called when a player enters a sensor on the Entity running the program.

Example

function onPlayerEnter(player)
-- Any code here will be run when a player enters the sensor on the entity.
-- 'player' will contain the player that entered the sensor.
end

onPlayerExit(player)

This function is called when a player exits a sensor on the Entity running the program.

Example

function onPlayerExit(player)
-- Any code here will be run when a player exits the sensor on the entity.
-- 'player' will contain the player that exited the sensor.
end

onPlayerCollect(entity, player)

This function is called when a player collects a collectable Entity (e.g. a gem).

Example

function onPlayerCollect(entity, player)
-- Any code here will be run when a player collects a collectable entity.
-- 'entity' will contain the entity that was collected.
-- 'player' will contain the player that collected the entity.
end

onEntityEnter(entity)

This function is called when another Entity enters a sensor on the Entity running the program.

Example

function onEntityEnter(entity)
-- Any code here will be run when another entity enters the sensor on the entity running the program.
-- 'entity' will contain the entity that entered the sensor, or nil.
end

onEntityExit(entity)

This function is called when another Entity exits a sensor on the Entity running the program.

Example

function onEntityExit(entity)
-- Any code here will be run when another entity exits the sensor on the entity running the program.
-- 'entity' will contain the entity that exited the sensor, or nil.
end

onSensorEnter(object)

This function is called when an Entity or Player enters a sensor on the Entity running the program.

Example

function onSensorEnter(object)
-- Any code here will be run when an object enters the sensor on the entity.
-- 'object' will contain the entity/player that entered the sensor, or nil.
end

onSensorExit(object)

This function is called when an Entity or Player exits a sensor on the Entity running the program.

Example

function onSensorExit(object)
-- Any code here will be run when an object exits the sensor on the entity.
-- 'object' will contain the entity/player that exited the sensor, or nil.
end

onInteractStart(clientId)

This function is called when a Player begins an interaction with an interactable Entity (e.g. a Citizen NPC).

Example

function onInteractStart(clientId)
-- Any code here will be run when an interaction begins between a player
-- and an interactable entity.
-- 'clientId' will contain the ID of the player involved in the interaction.
end

onInteractFinish(clientId)

This function is called when an interaction ends between a Player and an interactable Entity (e.g. a Citizen NPC).

Example

function onInteractFinish(clientId)
-- Any code here will be run when an interaction ends between a player
-- and an interactable entity.
-- 'clientId' will contain the ID of the player that was involved in the interaction.
end