QCherry: Document monster and interaction events

2026-08-14T04:26:38Z

Document monster and interaction events

New page

__NOTOC__
= Monster and interaction events =

These server-side Lua events expose authoritative monster state changes and
normalized player interactions. They are observations of server state; clients
do not decide monster health, damage, death, targets, or item rewards.

== Monster events ==

=== onMonsterSpawn ===

Triggered after a server-owned monster has been created.

<syntaxhighlight lang="lua">
onMonsterSpawn(string monsterId, string monsterType, number x, number y, number z, string sourceResource)
</syntaxhighlight>

<syntaxhighlight lang="lua" line>
addEventHandler("onMonsterSpawn", root, function(monsterId, monsterType, x, y, z)
outputDebugString(monsterType .. " spawned as " .. monsterId)
end)
</syntaxhighlight>

=== onMonsterDestroy ===

<syntaxhighlight lang="lua">
onMonsterDestroy(string monsterId, string sourceResource)
</syntaxhighlight>

=== onMonsterDamage ===

Triggered after authoritative damage has been accepted.

<syntaxhighlight lang="lua">
onMonsterDamage(string monsterId, number damage, number healthAfter, int sourcePlayerId, string damageKind, string sourceResource)
</syntaxhighlight>

<syntaxhighlight lang="lua" line>
addEventHandler("onMonsterDamage", root, function(monsterId, damage, healthAfter, playerId)
outputDebugString(monsterId .. " has " .. healthAfter .. " HP remaining")
end)
</syntaxhighlight>

=== onMonsterDeath ===

<syntaxhighlight lang="lua">
onMonsterDeath(string monsterId, int killerPlayerId, string sourceResource)
</syntaxhighlight>

=== onMonsterTargetChange ===

<syntaxhighlight lang="lua">
onMonsterTargetChange(string monsterId, int oldPlayerId, int newPlayerId, string sourceResource)
</syntaxhighlight>

=== onMonsterAttack ===

Triggered when the server-owned AI resolves a validated attack against a
player. The normal player damage and life-state events are emitted separately.

<syntaxhighlight lang="lua">
onMonsterAttack(string monsterId, int targetPlayerId, number damage, int actionId)
</syntaxhighlight>

== Interaction events ==

The common interaction events cover every supported kind. Current specialized
kinds are <code>mining</code> and <code>sitting</code>.

<syntaxhighlight lang="lua">
onPlayerInteractionState(int playerId, string kind, bool active, string phase, int actionId, int serverStartTimeMs)
onPlayerInteractionStart(int playerId, string kind, int actionId, int serverStartTimeMs)
onPlayerInteractionStop(int playerId, string kind, int actionId, int serverStartTimeMs)
</syntaxhighlight>

Mining and sitting also emit specialized equivalents:

<syntaxhighlight lang="lua">
onPlayerMiningState(int playerId, string kind, bool active, string phase, int actionId, int serverStartTimeMs)
onPlayerMiningStart(int playerId, string kind, int actionId, int serverStartTimeMs)
onPlayerMiningStop(int playerId, string kind, int actionId, int serverStartTimeMs)

onPlayerSittingState(int playerId, string kind, bool active, string phase, int actionId, int serverStartTimeMs)
onPlayerSittingStart(int playerId, string kind, int actionId, int serverStartTimeMs)
onPlayerSittingStop(int playerId, string kind, int actionId, int serverStartTimeMs)
</syntaxhighlight>

Use start/stop events for edge-triggered rules such as mining rewards. Use
[[GetPlayerInteraction]], [[IsPlayerInteracting]], [[IsPlayerMining]], and
[[IsPlayerSitting]] for current-state queries.

<syntaxhighlight lang="lua" line>
addEventHandler("onPlayerMiningStop", root, function(playerId)
givePlayerItem(playerId, "ore", 1)
outputChatBox("You mined one ore nugget.", playerId)
end)
</syntaxhighlight>

[[Category:Lua Events]]
[[Category:Server Events]]
[[Category:Monster Functions]]
[[Category:Interaction Functions]]

Monster and interaction events - Revision history

QCherry: Document monster and interaction events