Lua events
Lua events notify resources about authoritative gameplay, world, networking, and client UI changes. The catalog below lists event names and argument lists verified against the current runtime.
Handling an event
addEventHandler("onPlayerJoin", root, function(playerId)
outputChatBox("Welcome!", playerId, 225, 195, 110)
end)
Use root for global runtime events and resourceRoot for events owned by the current resource. Each event page specifies its execution side, exact callback signature, parameters, and delivery rules.
The current reference documents 92 Lua events. Red badges identify the update in which an event became available or received a materially improved compatibility contract.
Resource events
| Event |
Side |
Description
|
| onClientResourceStart |
client-side |
Triggered after the current client resource has started and its client scripts are ready.
|
| onClientResourceStop |
client-side |
Triggered immediately before the current client resource is stopped.
|
| onResourceStart |
server-side |
Triggered after the current server resource has started and its scripts are ready.
|
| onResourceStop |
server-side |
Triggered immediately before the current server resource is stopped.
|
| onServerShutdown |
server-side |
Triggered while the multiplayer server is beginning an orderly shutdown.
|
Player events
| Event |
Side |
Description
|
| onPlayerBodyChange |
server-side |
Triggered after the legacy authoritative body/face profile has changed.
|
| onPlayerFaceChange |
server-side |
Triggered after a validated authoritative GTO face profile has changed.
|
| onPlayerHeadChange |
server-side |
Triggered after a validated independent Nameless Hero head option has changed.
|
| onPlayerJoin (improved since 0.1.2) |
server-side |
Triggered after a client is authenticated and has received its authoritative player ID.
|
| onPlayerNameChange |
server-side |
Triggered after an authoritative player name change has been accepted.
|
| onPlayerNameplateChange |
server-side |
Triggered after a player's authoritative overhead nameplate text or visibility changes.
|
| onPlayerQuit (improved since 0.1.2) |
server-side |
Triggered synchronously while an authenticated player's disconnect is being finalized.
|
| onPlayerSkinChange |
server-side |
Triggered after a validated authoritative player appearance preset has changed.
|
| onPlayerSpawn |
server-side |
Triggered after the server authoritatively spawns a player in the game world.
|
| onPlayerTeleport |
server-side |
Triggered after the server authoritatively teleports an existing player.
|
Voice events
| Event |
Side |
Description
|
| onPlayerStartTalking |
server-side |
Triggered when the server accepts the start of a player's voice transmission.
|
| onPlayerStopTalking |
server-side |
Triggered when an active player voice transmission ends or times out.
|
| onPlayerVoiceStart |
server-side |
Compatibility alias triggered when the server accepts the start of a player's voice transmission.
|
| onPlayerVoiceStateChange |
server-side |
Triggered after a player's authoritative voice-routing or capture policy changes.
|
| onPlayerVoiceStop |
server-side |
Compatibility alias triggered when a player's active voice transmission ends.
|
Chat events
| Event |
Side |
Description
|
| onPlayerChat |
server-side |
Triggered when a player submits a normal chat message.
|
| onPlayerChatReady |
server-side |
Triggered by the bundled chat resource when a player's client chat UI reports that it is ready.
|
| onPlayerCommand |
server-side |
Triggered when a player submits a slash command that was not consumed before event dispatch.
|
Combat events
| Event |
Side |
Description
|
| onPlayerHit |
server-side |
Triggered after the server validates that one player hit another player.
|
Life State events
| Event |
Side |
Description
|
| onPlayerDamage |
server-side |
Triggered after authoritative damage changes a player's health.
|
| onPlayerDead |
server-side |
Compatibility alias triggered together with onPlayerDeath when health reaches zero.
|
| onPlayerDeath |
server-side |
Triggered when a player's authoritative health reaches zero.
|
| onPlayerDowned |
server-side |
Triggered after a player enters the authoritative downed state.
|
| onPlayerLifeStateChange |
server-side |
Triggered whenever the authoritative life state changes between alive, downed, and dead.
|
| onPlayerRevived |
server-side |
Triggered after a downed or dead player is authoritatively returned to the alive state.
|
Magic events
| Event |
Side |
Description
|
| onPlayerConsumableCommitRequested (available since 0.1.3) |
server-side |
Triggered after an authoritative consumable use passes validation and reserves one item, requesting durable stage-one inventory persistence.
|
| onPlayerConsumableDetachedSnapshot (available since 0.1.3) |
server-side |
Triggered during disconnect when a consumable operation is still awaiting its durable inventory result, providing both rollback and success snapshots for detached recovery.
|
| onPlayerConsumableDurablySettled (available since 0.1.3) |
server-side |
Triggered for a connected player after the consumable inventory removal and final authoritative progression snapshot are both durably committed.
|
| onPlayerConsumableEffectTick (available since 0.1.3) |
server-side |
Triggered after a periodic consumable tick successfully changes authoritative health or mana.
|
| onPlayerConsumableFinalizeRequested (available since 0.1.3) |
server-side |
Triggered after the inventory removal is durable and the server has applied the authoritative instant effect, requesting persistence of the final settlement snapshot.
|
| onPlayerSpellCastCancel |
server-side |
Triggered when an active spell cast is cancelled.
|
| onPlayerSpellCastComplete |
server-side |
Triggered when an authoritative spell cast completes.
|
| onPlayerSpellCastRejected |
server-side |
Triggered when the server rejects a requested spell-cast transition.
|
| onPlayerSpellCastStart |
server-side |
Triggered when the server accepts the start of a spell cast.
|
| onPlayerSpellCastState |
server-side |
Triggered for every authoritative spell-cast phase transition.
|
| onPlayerSpellEquip |
server-side |
Triggered when the authoritative equipped or in-hand state of a spell changes.
|
| onPlayerSpellImpact |
server-side |
Triggered when an authoritative spell projectile impacts a player or the world.
|
| onPlayerSpellProjectileCreate |
server-side |
Triggered when the server creates an authoritative spell projectile.
|
| onPlayerSpellProjectileDestroy |
server-side |
Triggered when an authoritative spell projectile is removed.
|
| onPlayerSpellRelease |
server-side |
Triggered when the casting player releases an accepted spell.
|
Ranged events
| Event |
Side |
Description
|
| onPlayerRangedImpact |
server-side |
Triggered when an authoritative arrow or bolt impacts a player or the world.
|
| onPlayerRangedProjectileDestroy |
server-side |
Triggered when an authoritative arrow or bolt projectile is removed.
|
| onPlayerRangedShot |
server-side |
Triggered when the server creates an authoritative arrow or bolt projectile.
|
| onPlayerRangedState |
server-side |
Triggered when the authoritative bow or crossbow action state changes.
|
Interaction events
World events
| Event |
Side |
Description
|
| onMinuteDurationChange |
server-side |
Triggered after the server changes how long one in-game minute lasts.
|
| onTimeChange |
server-side |
Triggered after the server changes the authoritative world clock.
|
| onWeatherChange |
server-side |
Triggered after the server accepts an authoritative weather transition.
|
| onWorldItemDrop (available since 0.1.2) |
server-side |
Triggered for public server resources after a player-initiated world-item drop is durably committed and published.
|
| onWorldItemPickup (improved since 0.1.2) |
server-side |
Triggered after the server accepts a synchronized world-item pickup and applies its authoritative inventory grant.
|
| onWorldItemSpawn (improved since 0.1.2) |
server-side |
Triggered after spawnItem or spawnTestItem creates and publishes a synchronized world item.
|
| onWorldObjectStateChange |
server-side |
Triggered when a synchronized usable world object changes state.
|
Monster events
| Event |
Side |
Description
|
| onMonsterAttack |
server-side |
Triggered when server-owned monster AI begins an authoritative attack against a player.
|
| onMonsterDamage |
server-side |
Triggered after authoritative damage changes a monster's health.
|
| onMonsterDeath |
server-side |
Triggered when a synchronized monster's authoritative health reaches zero.
|
| onMonsterDestroy |
server-side |
Triggered after a synchronized monster is removed from the server world.
|
| onMonsterIdVisibilityChange (available since 0.1.2) |
server-side |
Triggered after a resource shows or hides the numeric identifier in a monster's nameplate.
|
| onMonsterMoveBlocked (available since 0.1.2) |
server-side |
Triggered once when a resource-owned monster's direct scripted movement becomes blocked.
|
| onMonsterMoveComplete (available since 0.1.2) |
server-side |
Triggered once when a resource-owned monster reaches its direct scripted movement goal.
|
| onMonsterNameChange (available since 0.1.2) |
server-side |
Triggered after a resource changes a monster's validated overhead display name.
|
| onMonsterSpawn |
server-side |
Triggered after the server creates a synchronized monster.
|
| onMonsterTargetChange |
server-side |
Triggered when server-owned monster AI changes its player target.
|
NPC events
| Event |
Side |
Description
|
| onNpcAppearanceChange |
server-side |
Triggered after a scripted NPC's skin or armor changes.
|
| onNpcDestroy |
server-side |
Triggered after a resource-owned scripted NPC is removed.
|
| onNpcEquipmentChange |
server-side |
Triggered after a scripted NPC's equipped weapon changes.
|
| onNpcIdVisibilityChange (available since 0.1.2) |
server-side |
Triggered after a resource shows or hides the numeric identifier in a scripted NPC's nameplate.
|
| onNpcMoveBlocked (available since 0.1.2) |
server-side |
Triggered once when a resource-owned NPC's direct scripted movement becomes blocked.
|
| onNpcMoveComplete (available since 0.1.2) |
server-side |
Triggered once when a resource-owned NPC reaches its direct scripted movement goal.
|
| onNpcNameChange |
server-side |
Triggered after a resource changes a scripted NPC's validated display name.
|
| onNpcRouteComplete |
server-side |
Triggered when a non-looping scripted NPC route finishes.
|
| onNpcRoutePoint |
server-side |
Triggered when a scripted NPC reaches a route point.
|
| onNpcRouteStart |
server-side |
Triggered after a complete scripted NPC route has been validated and started.
|
| onNpcSpawn |
server-side |
Triggered after a resource creates a synchronized scripted human NPC.
|
GUI events
| Event |
Side |
Description
|
| onClientChatClose |
client-side |
Triggered when the built-in client chat input is closed.
|
| onClientChatOpen |
client-side |
Triggered when the built-in client chat input becomes active.
|
| onClientGuiChange |
client-side |
Triggered when a supported RmlUi input value changes.
|
| onClientGuiClick |
client-side |
Triggered when a clickable element in a resource-owned RmlUi document is activated.
|
| onClientGuiEscape |
client-side |
Triggered when Escape is pressed while a resource-owned RmlUi document owns UI input.
|
| onClientGuiSubmit |
client-side |
Triggered when a resource-owned RmlUi form or input is submitted.
|