voxelcore/doc/en/scripting/events.md

Engine events

Block events

Callbacks specified in block script.

Warning

events such as on_block_tick, on_block_present, and on_block_removed can cause performance issues if used carelessly or excessively.

function on_placed(x, y, z, playerid)

Called on block placed by player

function on_broken(x, y, z, playerid)

Called on block broken by player

function on_replaced(x, y, z, playerid)

Called on block replaced with other by player

function on_interact(x, y, z, playerid) -> bool

Called on block RMB click interaction. Prevents block placing if true returned.

function on_update(x, y, z)

Called on block update (near block changed)

function on_random_update(x, y, z)

Called on random block update (grass growth)

function on_blocks_tick(tps: int)

Called tps (20 / tick-interval) times per second. Use 1/tps instead of time.delta().

function on_block_tick(x, y, z, tps: number)

Called tps (20 / tick-interval) times per second for a block. Use 1/tps instead of time.delta().

function on_block_present(x, y, z)

Called for a specific block when it appears in the world (generated/loaded/placed). The call occurs within a time period that may depend on the event queue load. Under light load, it occurs during the first tick interval of the block. on_block_tick is not called until the event is called.

function on_block_removed(x, y, z)

Called when chunk containing the block unloads.

function on_player_tick(playerid: int, tps: int)

Called tps (20) times per second. Use 1/tps instead of time.delta().

Item events

Callbacks specified in item script.

function on_use(playerid: int)

Called on RMB click out of a block.

function on_use_on_block(x: int, y: int, z: int, playerid: int, normal: vec3)

Called on block RMB click. Prevents block placing-block placing if returns true

function on_block_break_by(x: int, y: int, z: int, playerid: int)

Called on block LMB click (unbreakable blocks included). Prevents block destruction if returns true.

World events

Callbacks specified in world.lua script.

function on_world_open()

Called on world open.

function on_world_save()

Called before world save.

function on_world_tick()

Called 20 times per second

function on_world_quit()

Called on world close (after saving)

function on_block_placed(blockid, x, y, z, playerid)

Called on block placed by player

function on_block_replaced(blockid, x, y, z, playerid)

Called on block replaced with other by player

function on_block_broken(blockid, x, y, z, playerid)

Called on block broken by player

function on_block_interact(blockid, x, y, z, playerid) -> bool

Called on block RMB click interaction. Prevents block placing if true returned.

Chunk Events (world.lua)

function on_chunk_present(x: int, z: int, loaded: bool)

Called after a chunk is generated/loaded. If a previously saved chunk is loaded, loaded will be true.

function on_chunk_remove(x: int, z: int)

Called when a chunk is unloaded from the world.

Inventory Events (world.lua)

function on_inventory_open(invid: int, playerid: int)

Called when the inventory is opened. If the inventory was not opened directly by the player, playerid will be -1.

function on_inventory_closed(invid: int, playerid: int)

Called when the inventory is closed.

Layout events

Script layouts/layout_name.xml.lua events.

function on_open(invid: int, x: int, y: int, z: int)

Called on element added to the screen. invid=0 if no inventory bound x,y,z=0 if no block bound

function on_close(invid: int)

Called on element removed from the screen.

HUD events

Callbacks specified in hud.lua script.

function on_hud_open(playerid: int)

Called after world open.

function on_hud_render()

Called every frame. Used for client-side tasks such as animation and camera control.

function on_hud_close(playerid: int)

Called on world close (before saving)

function on_inventory_interact(invid: int, slot: int, mode: int, action: int)

Triggered when a player interacts with inventory slots.

ACTION / MODE	(0) PRIMARY	(1) SECONDARY
(0) PUT	Places all items; if occupied, swaps them.	Places a single item from the cursor into the slot.
(1) TAKE	Picks up all items from the slot.	Picks up half of the items from the slot (rounded up).
(2) SHARE	Triggers the share event for the inventory layout.	Undefined

events library

events.on(code: str, handler: function)

Adds an event handler by its code, not limited to the standard ones.

events.reset(code: str, [optional] handler: function)

Removes the event, adding a handler if specified.

events.emit(code: str, args...) -> bool

Emits an event by code. If the event does not exist, nothing will happen. The existence of an event is determined by the presence of handlers.

events.remove_by_prefix(packid: str)

Removes all events with the prefix packid:. When you exit the world, events from all packs are unloaded, including core:.