Lua events: Difference between revisions
Jump to navigation
Jump to search
List the NPC ID visibility event planned for G1R:MP update 0.1.2 |
Document scripted camera API and events available from G1R:MP 0.1.3 |
||
| (2 intermediate revisions by the same user not shown) | |||
| Line 12: | Line 12: | ||
Use <code>root</code> for global runtime events and <code>resourceRoot</code> for events owned by the current resource. Each event page specifies its execution side, exact callback signature, parameters, and delivery rules. | Use <code>root</code> for global runtime events and <code>resourceRoot</code> 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 ''' | The current reference documents '''94 Lua events'''. Red badges identify the update in which an event became available or received a materially improved compatibility contract. | ||
== Resource events == | == Resource events == | ||
| Line 39: | Line 39: | ||
| [[onPlayerHeadChange]] || server-side || Triggered after a validated independent Nameless Hero head option has changed. | | [[onPlayerHeadChange]] || server-side || Triggered after a validated independent Nameless Hero head option has changed. | ||
|- | |- | ||
| [[onPlayerJoin]] || server-side || Triggered after a client has | | [[onPlayerJoin]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(improved since 0.1.2)</span> || 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. | | [[onPlayerNameChange]] || server-side || Triggered after an authoritative player name change has been accepted. | ||
| Line 45: | Line 45: | ||
| [[onPlayerNameplateChange]] || server-side || Triggered after a player's authoritative overhead nameplate text or visibility changes. | | [[onPlayerNameplateChange]] || server-side || Triggered after a player's authoritative overhead nameplate text or visibility changes. | ||
|- | |- | ||
| [[onPlayerQuit]] || server-side || Triggered | | [[onPlayerQuit]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(improved since 0.1.2)</span> || 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. | | [[onPlayerSkinChange]] || server-side || Triggered after a validated authoritative player appearance preset has changed. | ||
| Line 108: | Line 108: | ||
! Event !! Side !! Description | ! Event !! Side !! Description | ||
|- | |- | ||
| [[ | | [[onPlayerConsumableCommitRequested]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.3)</span> || server-side || Triggered after an authoritative consumable use passes validation and reserves one item, requesting durable stage-one inventory persistence. | ||
|- | |||
| [[onPlayerConsumableDetachedSnapshot]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.3)</span> || 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]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.3)</span> || server-side || Triggered for a connected player after the consumable inventory removal and final authoritative progression snapshot are both durably committed. | |||
|- | |||
| [[onPlayerConsumableEffectTick]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.3)</span> || server-side || Triggered after a periodic consumable tick successfully changes authoritative health or mana. | |||
|- | |||
| [[onPlayerConsumableFinalizeRequested]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.3)</span> || 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. | | [[onPlayerSpellCastCancel]] || server-side || Triggered when an active spell cast is cancelled. | ||
| Line 177: | Line 185: | ||
| [[onWeatherChange]] || server-side || Triggered after the server accepts an authoritative weather transition. | | [[onWeatherChange]] || server-side || Triggered after the server accepts an authoritative weather transition. | ||
|- | |- | ||
| [[ | | [[onWorldItemDrop]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.2)</span> || server-side || Triggered for public server resources after a player-initiated world-item drop is durably committed and published. | ||
|- | |- | ||
| [[ | | [[onWorldItemPickup]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(improved since 0.1.2)</span> || server-side || Triggered after the server accepts a synchronized world-item pickup and applies its authoritative inventory grant. | ||
|- | |||
| [[onWorldItemSpawn]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(improved since 0.1.2)</span> || server-side || Triggered after <code>spawnItem</code> or <code>spawnTestItem</code> creates and publishes a synchronized world item. | |||
|- | |- | ||
| [[onWorldObjectStateChange]] || server-side || Triggered when a synchronized usable world object changes state. | | [[onWorldObjectStateChange]] || server-side || Triggered when a synchronized usable world object changes state. | ||
| Line 195: | Line 205: | ||
|- | |- | ||
| [[onMonsterDestroy]] || server-side || Triggered after a synchronized monster is removed from the server world. | | [[onMonsterDestroy]] || server-side || Triggered after a synchronized monster is removed from the server world. | ||
|- | |||
| [[onMonsterIdVisibilityChange]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.2)</span> || server-side || Triggered after a resource shows or hides the numeric identifier in a monster's nameplate. | |||
|- | |||
| [[onMonsterMoveBlocked]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.2)</span> || server-side || Triggered once when a resource-owned monster's direct scripted movement becomes blocked. | |||
|- | |||
| [[onMonsterMoveComplete]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.2)</span> || server-side || Triggered once when a resource-owned monster reaches its direct scripted movement goal. | |||
|- | |||
| [[onMonsterNameChange]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.2)</span> || 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. | | [[onMonsterSpawn]] || server-side || Triggered after the server creates a synchronized monster. | ||
| Line 211: | Line 229: | ||
| [[onNpcEquipmentChange]] || server-side || Triggered after a scripted NPC's equipped weapon changes. | | [[onNpcEquipmentChange]] || server-side || Triggered after a scripted NPC's equipped weapon changes. | ||
|- | |- | ||
| [[onNpcIdVisibilityChange]] <span style="color:#c62828; font-weight:bold;">( | | [[onNpcIdVisibilityChange]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.2)</span> || server-side || Triggered after a resource shows or hides the numeric identifier in a scripted NPC's nameplate. | ||
|- | |||
| [[onNpcMoveBlocked]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.2)</span> || server-side || Triggered once when a resource-owned NPC's direct scripted movement becomes blocked. | |||
|- | |||
| [[onNpcMoveComplete]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.2)</span> || 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. | | [[onNpcNameChange]] || server-side || Triggered after a resource changes a scripted NPC's validated display name. | ||
| Line 240: | Line 262: | ||
| [[onClientGuiSubmit]] || client-side || Triggered when a resource-owned RmlUi form or input is submitted. | | [[onClientGuiSubmit]] || client-side || Triggered when a resource-owned RmlUi form or input is submitted. | ||
|} | |} | ||
== Camera events == | |||
{| class="wikitable" style="width:100%;" | |||
! Event !! Side !! Description | |||
|- | |||
| [[onClientCameraCommandResult]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.3)</span> || client-side || Reports a matching camera request's progress, completion, state, reset, error or cancellation to the owning resource. | |||
|- | |||
| [[onClientCameraReset]] <span style="color:#000; background:#ffcdd2; border:1px solid #c62828; font-weight:bold; padding:0.08em 0.35em; border-radius:0.2em;">(available since 0.1.3)</span> || client-side || Reports forced camera ownership/cache invalidation; discard pending cinematic work and wait for world readiness. | |||
|} | |||
See [[Scripted camera]] for request IDs, cache timing and lifecycle-safe login backgrounds. | |||
[[Category:Lua Events]] | [[Category:Lua Events]] | ||
Latest revision as of 23:51, 8 September 2026
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 94 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
| Event | Side | Description |
|---|---|---|
| onPlayerInteractionStart | server-side | Triggered when a replicated general interaction begins. |
| onPlayerInteractionState | server-side | Triggered for every replicated general interaction-state update. |
| onPlayerInteractionStop | server-side | Triggered when a replicated general interaction ends. |
| onPlayerMiningStart | server-side | Triggered when synchronized ore mining begins. |
| onPlayerMiningState | server-side | Triggered for every replicated mining-state update. |
| onPlayerMiningStop | server-side | Triggered when synchronized ore mining ends. |
| onPlayerSittingStart | server-side | Triggered when synchronized sitting begins. |
| onPlayerSittingState | server-side | Triggered for every replicated sitting-state update. |
| onPlayerSittingStop | server-side | Triggered when synchronized sitting ends. |
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. |
Camera events
| Event | Side | Description |
|---|---|---|
| onClientCameraCommandResult (available since 0.1.3) | client-side | Reports a matching camera request's progress, completion, state, reset, error or cancellation to the owning resource. |
| onClientCameraReset (available since 0.1.3) | client-side | Reports forced camera ownership/cache invalidation; discard pending cinematic work and wait for world readiness. |
See Scripted camera for request IDs, cache timing and lifecycle-safe login backgrounds.