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

This function is called when the program starts running.

Example​

function onStart(initialData)
  -- Any code here will be run when the program starts.
  -- 'initialData' is passed to onStart through World.assignScript([scriptName], [initialData])
  -- the data can be any variable
end

onDestroy(clientId)​

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

info

This global event can only be used in Entity scripts.

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
danger

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.

info

This global event can only be used in Entity scripts.

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.

info

This global event can only be used in Entity scripts.

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.

info

This global event can only be used in Entity scripts.

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, instigator)​

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

info

This global event can only be used in Entity scripts.

Example​

function onPlayerDestroy(player, instigator)
  -- Any code here will be run when a player in the world is destroyed.
  -- 'player' will contain the player that was just destroyed.
  -- 'instigator' will contain the ${{Entity}} or ${{Player}} that destroyed the 'player'.
end

onPlayerDamage(player, amount, instigator)​

This function is called when any player in the world takes damage.

info

This global event can only be used in Entity scripts.

Example​

function onPlayerDamage(player, amount, instigator)
  -- Any code here will be run when a player in the world is damaged.
  -- 'player' will contain the player that was just damaged.
  -- 'amount' will contain the amount of damage taken.
  -- 'instigator' will contain the ${{Entity}} or ${{Player}} that damaged the 'player'.
end

onPlayerEnter(player)​

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

info

This global event can only be used in Entity scripts.

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.

info

This global event can only be used in Entity scripts.

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

info

This global event can only be used in Entity scripts.

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

onPlayerOutOfBounds(clientId)​

This function is called when a player falls into water, or off the map.

info

This global event can only be used in Entity scripts.

Example​

function onPlayerOutOfBounds(clientId)
  -- Any code here will be run when a player starts touching the water or out of bounds.
  -- 'clientId' will contain the id of the player that entered the water.
end

onEntityEnter(entity)​

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

info

This global event can only be used in Entity scripts.

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.

info

This global event can only be used in Entity scripts.

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.

info

This global event can only be used in Entity scripts.

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.

info

This global event can only be used in Entity scripts.

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

info

This global event can only be used in Entity scripts.

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

info

This global event can only be used in Entity scripts.

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

onMouseDown(data)​

This function is called when a player presses a button on their mouse.

info

This global event can only be used in Hud scripts.

Example​

function onMouseDown(data)
  -- Any code here will be run when the user presses a button on their mouse.
  -- 'data' will contain properties about the event, for example:
  -- 'data.mouseButton' will contain the index of the mouse button.
  -- 'data.position' will contain a Vector2 representing the position of the mouse cursor
  -- 'data.delta' will contain a Vector2 representing the change in position of the mouse cursor since the last tick
  if data.mouseButton == MouseButton.Left then
    print("Left mouse button pressed at position: " .. tostring(data.position))
  end
end

onMouseUp(data)​

This function is called when a player releases a button on their mouse.

info

This global event can only be used in Hud scripts.

Example​

function onMouseUp(data)
  -- Any code here will be run when the user releases a button on their mouse.
  -- 'data' will contain properties about the event, for example:
  -- 'data.mouseButton' will contain the index of the mouse button.
  -- 'data.position' will contain a Vector2 representing the position of the mouse cursor
  -- 'data.delta' will contain a Vector2 representing the change in position of the mouse cursor since the last tick
  if data.mouseButton == MouseButton.Left then
    print("Left mouse button released at position: " .. tostring(data.position))
  end
end

onMouseClick(data)​

This function is called when a player clicks a button on their mouse.

info

This global event can only be used in Hud scripts.

Example​

function onMouseClick(data)
  -- Any code here will be run when the user clicks a button on their mouse.
  -- 'data' will contain properties about the event, for example:
  -- 'data.mouseButton' will contain the index of the mouse button.
  -- 'data.position' will contain a Vector2 representing the position of the mouse cursor
  -- 'data.delta' will contain a Vector2 representing the change in position of the mouse cursor since the last tick
  if data.mouseButton == MouseButton.Left then
    print("Left mouse button clicked at position: " .. tostring(data.position))
  end
end

onMouseEnter(position)​

Called when a player moves their mouse cursor over a Hud Item.

info

This global event can only be used in Hud scripts.

Example​

function onMouseEnter(position)
-- 'position' is a Vector2 of the cursor's screen position
  if data.mouseButton == MouseButton.Left then
    print("Mouse entered at " .. tostring(position))
  end
end

onMouseExit(position)​

Called when a player's mouse cursor leaves a Hud Item's area.

info

This global event can only be used in Hud scripts.

Example​

function onMouseExit(position)
-- 'position' is a Vector2 of the cursor's screen position
  if data.mouseButton == MouseButton.Left then
    print("Mouse exited at " .. tostring(position))
  end
end

onKeyDown(keyCode)​

This function is called when a player presses a key on their keyboard.

info

This global event can only be used in Hud scripts.

Example​

function onKeyDown(keyCode)
  -- Any code here will be run when the user presses a key on their keyboard.
  -- 'keyCode' will contain the key that was pressed.
end

onKeyUp(keyCode)​

This function is called when a player releases a key on their keyboard.

info

This global event can only be used in Hud scripts.

Example​

function onKeyUp(keyCode)
  -- Any code here will be run when the user releases a key on their keyboard.
  -- 'keyCode' will contain the key that was released.
end

onVisibilityChange(visible)​

This function is called when the visibility of the HudItem changes.

info

This global event can only be used in Hud scripts.

Example​

function onVisibilityChange(visible)
  -- Any code here will be run when the visibility of the HudItem changes.
  -- 'visible' will contain a boolean indicating whether the HudItem is visible or not.
end

onMouseDown(mouseData)​

This function is called when a player presses a button on their mouse with the pointer over an Entity or StaticEntity.

info

This global event can only be used in Entity scripts.

Example​

function onMouseDown(mouseData)
  -- Any code here will be run when the user clicks on the entity this script is assigned to.
  local player = Players.getPlayer(mouseData.invokerId)
  print("Clicked by: " .. player.name)
end

onEntityMouseDown(entity, mouseData)​

This function is called when a player presses a button on their mouse with the pointer over an Entity or StaticEntity.

info

This global event can only be used in Entity scripts.

Example​

function onEntityMouseDown(entity, mouseData)
  -- Any code here will be run when the user clicks on any entity.
  local player = Players.getPlayer(mouseData.invokerId)
  print(entity.name .. " was clicked by: " .. player.name)
end

onPlayerMouseDown(player, mouseData)​

This function is called when a player presses a button on their mouse with the pointer over a Player.

info

This global event can only be used in Entity scripts.

Example​

function onPlayerMouseDown(player, mouseData)
  -- Any code here will be run when the user clicks on any player.
  local clickingPlayer = Players.getPlayer(mouseData.invokerId)
  print(player.name .. " was clicked by: " .. clickingPlayer.name)
end

onMouseUp(mouseData)​

This function is called when a player releases a button on their mouse with the pointer over an Entity or StaticEntity.

info

This global event can only be used in Entity scripts.

Example​

function onMouseUp(mouseData)
  -- Any code here will be run when the user releases the mouse button on the entity
  -- this script is assigned to.
  local player = Players.getPlayer(mouseData.invokerId)
  print("Mouse released by: " .. player.name)
end

onEntityMouseUp(entity, mouseData)​

This function is called when a player releases a button on their mouse with the pointer over an Entity or StaticEntity.

info

This global event can only be used in Entity scripts.

Example​

function onEntityMouseUp(entity, mouseData)
  -- Any code here will be run when the user releases the mouse button on any entity.
  local player = Players.getPlayer(mouseData.invokerId)
  print("Mouse released on: " .. entity.name .. " by: " .. player.name)
end

onPlayerMouseUp(player, mouseData)​

This function is called when a player releases a button on their mouse with the pointer over a Player.

info

This global event can only be used in Entity scripts.

Example​

function onPlayerMouseUp(player, mouseData)
  -- Any code here will be run when the user releases the mouse button on any player.
  local clickingPlayer = Players.getPlayer(mouseData.invokerId)
  print("Mouse released on " .. player.name .. " by: " .. clickingPlayer.name)
end