EventMap
Defined in: server/api.d.ts:7
Native events dispatched through Events.on. Each property is the exact callback argument tuple for that event.
Properties
Section titled “Properties”areaEnter
Section titled “areaEnter”Defined in: server/api.d.ts:604
Dispatched when a body comes to be inside an enabled area: it walked or rode in, or the area was created, moved, reshaped or enabled around it. The server decides this itself from the pose it already replicates, by the game’s own rule for that kind of area, so a client cannot claim it. matchingVirtualWorld is false when a script area bound to one world is crossed by a body in another; a level area is in every world.
areaExit
Section titled “areaExit”Defined in: server/api.d.ts:609
Dispatched when a body stops being inside an area: it walked out, or the area was moved, reshaped, disabled or destroyed. A body that leaves the server entirely – a player disconnecting, a horse despawned – raises nothing here; its own event already says it is gone.
cartDestroy
Section titled “cartDestroy”cartDestroy: [
Cart]
Defined in: server/api.d.ts:362
Dispatched while a cart is being despawned, after everyone in it has been let out. The handle still resolves, so its blueprint and its pose can be read one last time.
cartEnter
Section titled “cartEnter”Defined in: server/api.d.ts:372
Dispatched after a player is given a seat, named as in cart.seats; the driver seat’s client runs the cart from here on.
cartEntering
Section titled “cartEntering”Defined in: server/api.d.ts:367
Dispatched before a player is put in a seat – by their own use of the cart’s prompt, or putPlayer. Return false from a handler and the seat is refused: nothing changes, and the player’s game never climbs in. Handlers run synchronously.
cartExit
Section titled “cartExit”Defined in: server/api.d.ts:377
Dispatched after a player leaves a seat: their own climb down, removePlayer, a disconnect, or the cart being destroyed.
cartSpawn
Section titled “cartSpawn”cartSpawn: [
Cart]
Defined in: server/api.d.ts:357
Dispatched immediately after a cart is created and replicated, whether by Cart.spawn, the /cart command, or anything else.
consoleCommand
Section titled “consoleCommand”consoleCommand: [
string,string[]]
Defined in: server/api.d.ts:736
Dispatched for a line typed into the server console that no built-in command (help, ensure, refresh, …) claimed. args is the rest of the line, split on whitespace. The console is the operator’s, so this is the place for commands no player may run.
craftingCompleted
Section titled “craftingCompleted”craftingCompleted: [
Player,CraftCompletedEvent]
Defined in: server/api.d.ts:317
A result was granted, followed by craftingEnded. Raised after the playerInventoryChanged it caused.
craftingCompleting
Section titled “craftingCompleting”craftingCompleting: [
Player,CraftCompletionProposal]
Defined in: server/api.d.ts:312
A batch or workpiece finished and its result is computed. Every handler runs; one returning literal false refuses it: alchemy ends the batch as failed, what was spent stays spent, and nothing is granted; smithing fails the workpiece, spending its failure share.
craftingEnded
Section titled “craftingEnded”craftingEnded: [
Player,CraftEndedEvent]
Defined in: server/api.d.ts:322
A batch or workpiece is over. Raised after the playerInventoryChanged of any refund.
craftingRefunding
Section titled “craftingRefunding”craftingRefunding: [
Player,CraftRefundProposal, () =>void]
Defined in: server/api.d.ts:297
Synchronous decision before an unfinished craft settles, including when no native refund is due. Call refund() to request a full refund; return values are ignored. No handler or no call preserves native rules. JavaScript exceptions are logged and do not cancel a call already made. The callback expires on return; delayed calls do nothing. The cancelled, interrupted and clientError reasons are reported by the player’s own client: a modified client can send any of them, so refunding on one lets that client keep its materials. Never grants a completed craft twice. craftingEnded follows the actual inventory changes.
craftingStarted
Section titled “craftingStarted”craftingStarted: [
Player,CraftStartedEvent]
Defined in: server/api.d.ts:307
A batch is brewing, or a workpiece took its materials.
craftingStarting
Section titled “craftingStarting”craftingStarting: [
Player,CraftStartProposal]
Defined in: server/api.d.ts:302
A player asks to open an alchemy table, or to begin a smithing recipe. Every handler runs; one returning literal false refuses it. An async handler cannot refuse.
dialogueChoice
Section titled “dialogueChoice”dialogueChoice: [
number,Player,string]
Defined in: server/api.d.ts:230
Dispatched when a player picks an option. The option’s own id comes back, never its index, so a handler stays correct when the page is rebuilt with different rows. Anything the option costs is checked here, not when the page was built: enabled on the wire is a rendering hint and the server is what decides.
dialogueClosed
Section titled “dialogueClosed”dialogueClosed: [
number,Player,number]
Defined in: server/api.d.ts:235
Dispatched when a conversation ends, whoever ended it. 0 completed, 1 the player cancelled, 2 another conversation replaced it, 3 it was interrupted – a disconnect, most often.
diceMatchEnd
Section titled “diceMatchEnd”diceMatchEnd: [
number,Player|null,Player|null,number,string,number,number]
Defined in: server/api.d.ts:292
Dispatched once a match is over and both players have been told. winner is 0 when first won, 1 when second did, 255 when nobody did. reason is won (a player banked the target score), gaveUp (a player left the table), left (a player disconnected), timedOut (the player to throw did not move for three minutes), failed (a client could not play the table) or stopped (Dice.stop). A player who has gone since is null. Nothing changes hands on its own: what a match was played for is the gamemode’s to settle here.
diceMatchStart
Section titled “diceMatchStart”Defined in: server/api.d.ts:287
Dispatched once a match has started and both players have been sent to the table. Which of them throws first is drawn at random.
diceMove
Section titled “diceMove”diceMove: [
DiceProgressEvent]
Defined in: server/api.d.ts:277
The server accepted Continue or Pass. Invalid or repeated requests emit nothing.
diceRoll
Section titled “diceRoll”diceRoll: [
DiceProgressEvent]
Defined in: server/api.d.ts:272
The server dealt a roll. Includes all six face values and the mask rolled this time.
diceTurnEnd
Section titled “diceTurnEnd”diceTurnEnd: [
DiceProgressEvent]
Defined in: server/api.d.ts:282
A turn ended by banking, busting, winning, or a match ending. A round means one player’s turn.
diceTurnStart
Section titled “diceTurnStart”diceTurnStart: [
DiceProgressEvent]
Defined in: server/api.d.ts:267
A new turn begins, including turns after automatic busts.
dogDestroy
Section titled “dogDestroy”dogDestroy: [
Dog]
Defined in: server/api.d.ts:332
Dispatched while a dog is being despawned. The handle still resolves, so its owner and name can be read one last time.
dogModeChanged
Section titled “dogModeChanged”dogModeChanged: [
Dog,number]
Defined in: server/api.d.ts:342
Dispatched after a dog’s companion mode actually changes.
dogOwnerChanged
Section titled “dogOwnerChanged”Defined in: server/api.d.ts:337
Dispatched after a dog is handed to another player, or left masterless.
dogSpawn
Section titled “dogSpawn”dogSpawn: [
Dog]
Defined in: server/api.d.ts:327
Dispatched immediately after a dog is created and replicated, whether by Dog.spawn or anything else.
doorInteract
Section titled “doorInteract”doorInteract: [
Player,Door,"open"|"close"|"unlock"|"lockpick",boolean]
Defined in: server/api.d.ts:514
Dispatched when a player’s client reports working a door, before the server applies it. action is open, close, unlock or lockpick; a key turned in the same use as the push arrives as unlock and then open. keySide says whether the player stood on the side with the keyhole, which is where an unlock needs a key.
Return false to refuse it: the door is put back on every client, the player’s included, and nobody else sees it happen. Every handler runs whatever an earlier one returned, and an async handler cannot refuse. The server has already refused what the game’s own rules forbid – a player out of reach, a door the server locked, opening a locked door, picking a door with no keyhole – so this only sees what the game would allow.
entityStateChange
Section titled “entityStateChange”entityStateChange: [
Entity,string,any,any]
Defined in: server/api.d.ts:731
Dispatched when one key of an entity’s state changes: on the server when a script writes it, on a client when the write arrives. value is undefined when the key was removed and previous is undefined when it held nothing before, so a stored null stays distinguishable from an absent key. The entity is whatever the game’s WrapScriptEntity answers, and the base Entity handle by default.
gatheringHarvest
Section titled “gatheringHarvest”gatheringHarvest: [
Player,GatheringProposal]
Defined in: server/api.d.ts:502
A player picked a plant within their reach, and the server is about to give them the herb. Return false to refuse it: nothing is given and the plants stay. The proposal is frozen; every handler runs whatever an earlier one returned, and an async handler cannot refuse.
gatheringHarvested
Section titled “gatheringHarvested”gatheringHarvested: [
Player,GatheringHarvestedEvent]
Defined in: server/api.d.ts:507
A player was given a herb, after the playerInventoryChanged it caused. The plant and the same-kind plants harvested with it are picked for everyone in the virtual world until timed or scripted regrowth; nothing about them survives a restart.
groundItemDestroy
Section titled “groundItemDestroy”groundItemDestroy: [
GroundItem]
Defined in: server/api.d.ts:492
Dispatched while a stack is being taken out of the world, including the removal a completed pickup performs. The handle still resolves, so its item and its pose can be read one last time.
groundItemPickup
Section titled “groundItemPickup”groundItemPickup: [
GroundItem,Player|null]
Defined in: server/api.d.ts:497
Dispatched when a player’s pickup has been granted and the stack is about to go, so what was taken and by whom can both still be read. It reports a pickup rather than deciding one – the server has already told that client the stack is theirs by the time this is raised – and groundItemDestroy follows it.
groundItemSpawn
Section titled “groundItemSpawn”groundItemSpawn: [
GroundItem]
Defined in: server/api.d.ts:487
Dispatched immediately after a stack is laid in the world and replicated, whether by GroundItem.spawn, the /drop command, or a player dropping something from their own inventory.
horseDamage
Section titled “horseDamage”horseDamage: [
Horse,Player|null,number,"unknown"|"combat"|"gunshot"|"starvation"|"collision"|"scripted"|"disintegrate"|"fall"|"poison"|"bleeding"|"selfHarm"]
Defined in: server/api.d.ts:210
Dispatched when health comes off a horse: a blade, an arrow, a fall. The client running the horse reports it, because its copy of the animal is the one whose soul counts – a blow resolved on the attacker’s machine is handed to it first – so amount is what was really taken. attacker is the player who dealt it, or null.
horseDeath
Section titled “horseDeath”horseDeath: [
Horse,Player|null,"unknown"|"combat"|"gunshot"|"starvation"|"collision"|"scripted"|"disintegrate"|"fall"|"poison"|"bleeding"|"selfHarm"]
Defined in: server/api.d.ts:215
Dispatched once when a horse dies, whatever killed it: its body falls where it stood, and anyone in the saddle has already been taken off (with a horseDismount). killer is the player whose blow took the last of the health, or null. It follows the horseDamage of the blow that caused it: the client running the horse reports both, in that order.
horseDestroy
Section titled “horseDestroy”horseDestroy: [
Horse]
Defined in: server/api.d.ts:183
Dispatched while a horse is being despawned, including the despawn its owner’s disconnect implies. The handle still resolves, so its owner and name can be read one last time.
horseDismount
Section titled “horseDismount”Defined in: server/api.d.ts:198
Dispatched after a rider leaves a saddle, including the dismount a disconnect implies, the one a destroyed or dead horse forces, and the one a rider’s own death forces.
horseGearChanged
Section titled “horseGearChanged”Defined in: server/api.d.ts:225
Dispatched after a horse’s gear changed on every client. player is the rider who changed it, or null for a script.
horseGearChanging
Section titled “horseGearChanging”Defined in: server/api.d.ts:220
Dispatched when a player has changed a horse’s gear – in the game’s own horse inventory screen – before the server accepts it. gear is what the horse would wear. Return false from a handler and the change is refused: every copy of the horse, the player’s own included, is dressed back in what it wore before. Not dispatched while gearLocked is set, which refuses first, nor for a script’s own setGear. Handlers run synchronously.
horseIntentDone
Section titled “horseIntentDone”horseIntentDone: [
Horse,string]
Defined in: server/api.d.ts:173
A move or patrol leg reached its destination, was blocked, or failed. Intermediate path corners do not emit this event.
horseMount
Section titled “horseMount”Defined in: server/api.d.ts:193
Dispatched after a player climbs into a saddle and the horse’s authority has been handed to their client.
horseMounting
Section titled “horseMounting”Defined in: server/api.d.ts:205
Dispatched when a player has climbed into a saddle, before the server accepts it – the place to decide who may ride which horse. Return false from a handler and the ride is refused: the player’s client is told to get back off, and no horseMount follows. Handlers run synchronously, so the decision cannot wait on anything awaited.
The player’s own game has already started the mount when this runs, so a refusal plays the get-off.
horseOwnerChanged
Section titled “horseOwnerChanged”Defined in: server/api.d.ts:188
Dispatched after a horse is handed to another player, or left ownerless – by giveTo, or by its owner disconnecting while destroyWithOwner is false.
horseSpawn
Section titled “horseSpawn”horseSpawn: [
Horse]
Defined in: server/api.d.ts:178
Dispatched immediately after a horse is created and replicated, whether by Horse.spawn, the /horse command, or anything else.
markerEnter
Section titled “markerEnter”Defined in: server/api.d.ts:402
Dispatched when a player walks into a marker whose trigger is on. The client detects the crossing and the server confirms it against the position it already replicates, so a claim it does not agree with never reaches here.
markerExit
Section titled “markerExit”Defined in: server/api.d.ts:407
Dispatched when a player walks out of a marker whose trigger is on. Not raised when the marker is removed, when trigger is turned off, or when the player leaves the world – none of those is the player walking out.
markerPlace
Section titled “markerPlace”markerPlace: [
Marker]
Defined in: server/api.d.ts:392
Dispatched immediately after a ground marker is drawn, whether by Marker.place, a command, or anything else.
markerRemove
Section titled “markerRemove”markerRemove: [
Marker]
Defined in: server/api.d.ts:397
Dispatched while a ground marker is being removed. The handle still resolves, so its material and its pose can be read one last time.
npcAnimationEnd
Section titled “npcAnimationEnd”npcAnimationEnd: [
Npc,string,"finished"|"interrupted"|"refused"|"stopped"|"replaced"]
Defined in: server/api.d.ts:457
Dispatched once when the animation a playAnimation request started is over; fragment is the request’s. reason is finished, interrupted, refused, stopped or replaced, as for playerAnimationEnd. The first three come from the client simulating the NPC. One that nobody simulates plays nothing, so its one-shot ends refused as soon as it is asked for, and one cut off by a change of simulator ends interrupted: the new simulator does not replay what it did not see start.
npcDamage
Section titled “npcDamage”Defined in: server/api.d.ts:442
Dispatched after health came off the ledger. For melee, the victim’s simulator resolves the native hit and the server checks the accepted swing before changing health. amount is what was actually taken.
npcDeath
Section titled “npcDeath”Defined in: server/api.d.ts:447
Dispatched when the last of an NPC’s health goes. The body stays as a corpse and the handle keeps resolving.
npcDestroy
Section titled “npcDestroy”npcDestroy: [
Npc]
Defined in: server/api.d.ts:432
Dispatched while an NPC is being despawned. The handle still resolves, so what it was and where it stood can be read one last time.
npcHarvested
Section titled “npcHarvested”Defined in: server/api.d.ts:422
An accepted butchering completion. The prepopulated stock is now accessible and every client applies the butchered appearance. Emitted once per life; save Inventory.get(npc) here too to persist the harvested flag.
npcIntentDone
Section titled “npcIntentDone”npcIntentDone: [
Npc,string]
Defined in: server/api.d.ts:437
Dispatched once when an NPC finishes what it was told to do. status is reached when it arrived, blocked when it could not make progress, or failed when the order could not be carried out at all, or when a patrol gives up. Server-planned intermediate corners do not raise this event, and neither does a change of simulator: a finished order is not reported twice. A follow, which never finishes, raises reached the first time it catches up and again only after a change of simulator. A patrol steps on this event, so a handler that re-orders the NPC here replaces the route rather than racing it.
npcInteract
Section titled “npcInteract”Defined in: server/api.d.ts:462
Dispatched when a player presses use on an NPC whose interactable is on. The client reports the press and the server confirms the distance against the position it already replicates, so a claim it does not agree with never reaches here.
npcInventoryChanged
Section titled “npcInventoryChanged”npcInventoryChanged: [
Npc,InventoryChange]
Defined in: server/api.d.ts:427
Committed stock changes, including loot transfers. Save this stock and restore it with Inventory.set. Harvest completion is reported by npcHarvested.
npcInventoryReady
Section titled “npcInventoryReady”npcInventoryReady: [
Npc]
Defined in: server/api.d.ts:417
Its initial inventory has been established. The default stock is censused once by its elected simulator; Inventory.set establishes authored stock immediately.
npcRevive
Section titled “npcRevive”npcRevive: [
Npc]
Defined in: server/api.d.ts:452
Dispatched when a dead NPC is brought back. Every client makes a new body for it.
npcSimulatorChange
Section titled “npcSimulatorChange”Defined in: server/api.d.ts:467
Dispatched when the client running an NPC changes – somebody walked into range, out of it, or disconnected. player is null when it went dormant. Nothing about the NPC changes with it: intent, ledger and identity are the server’s, and the new simulator re-derives from them.
npcSpawn
Section titled “npcSpawn”npcSpawn: [
Npc]
Defined in: server/api.d.ts:412
Dispatched immediately after an NPC is spawned or adopted, whether by Npc.create, a command, or anything else.
patrolFinished
Section titled “patrolFinished”patrolFinished: [
Npc,PatrolState&object]
Defined in: server/api.d.ts:477
A patrol ended, failed, or was replaced. Edits to its definition do not replace its snapshot.
patrolWaypoint
Section titled “patrolWaypoint”patrolWaypoint: [
Npc,PatrolState&object]
Defined in: server/api.d.ts:472
One accepted waypoint outcome; intermediate path corners do not emit it.
playerAnimationEnd
Section titled “playerAnimationEnd”playerAnimationEnd: [
Player,string,"finished"|"interrupted"|"refused"|"stopped"|"replaced"]
Defined in: server/api.d.ts:75
Dispatched once when the animation a playAnimation request started is over. fragment is the request’s. reason says how: finished when a one-shot played to its end, interrupted when it was playing and something cut it short (a hit, a weapon drawn, a teleport), refused when the game would not start it at all, stopped for stopAnimation, replaced for another playAnimation.
The first three come from the player’s own client, sent from the moment the game’s animation system ended it, so this is the place to chain the next animation. A loop never finishes by itself and only ends stopped or replaced. A request with no fragment – one that only holds a prop or a tag – raises nothing.
playerAttack
Section titled “playerAttack”Defined in: server/api.d.ts:37
A melee swing aimed at another player was admitted by the server, including a miss. Raised once per attack generation, after presentation admission. Use it to track combat inactivity in your resource.
playerBuffAdded
Section titled “playerBuffAdded”playerBuffAdded: [
Player,string,"server"|"native"]
Defined in: server/api.d.ts:671
Dispatched when a status effect appears on a player’s body. source says whether this server added it; native means the game did – a potion they drank, an injury they took. It fires for whatever they are already carrying when their client first reports in, so a handler sees the full picture without asking for it.
playerBuffBlocked
Section titled “playerBuffBlocked”playerBuffBlocked: [
Player,string]
Defined in: server/api.d.ts:681
Dispatched when the game tried to give a player an effect of a kind this server claimed, and their client turned it down. This is the other half of Buffs.claim: the drink was still drunk and the item still consumed, so the handler decides what really happens – usually player.addBuff with the resource’s own rule applied. Nothing raises it until something is claimed, and repeats of the same effect are limited to twice a second per player.
playerBuffRemoved
Section titled “playerBuffRemoved”playerBuffRemoved: [
Player,string,"server"|"expired"]
Defined in: server/api.d.ts:676
Dispatched when a status effect leaves a player’s body. server is a removal this server asked for; expired is everything else – it ran out, or the game replaced it. Effect timers run on each player’s own machine, so the server never expires one itself.
playerCarry
Section titled “playerCarry”Defined in: server/api.d.ts:87
Dispatched once a carry is accepted: the carried body is on the carrier’s shoulder on every client, and carrier.carrying names it. It rides there until playerPutDown.
playerCarrying
Section titled “playerCarrying”Defined in: server/api.d.ts:82
Dispatched when a player has picked up another player’s body, before the server accepts it – the place to decide who may carry whom. Return false from a handler and the carry is refused: the carrier’s client is told to let go at once, and no playerCarry follows. Handlers run synchronously, so the decision cannot wait on anything awaited.
The pick-up is the game’s own “grab” prompt, which it offers only over a body that is down – dead or unconscious – so a player a script revives at once is never there to carry. The carrier’s game has already started the pick-up when this runs.
playerCarryingItem
Section titled “playerCarryingItem”playerCarryingItem: [
Player,string,GroundItem|null]
Defined in: server/api.d.ts:97
Dispatched when a player starts a carry of their own, before the server accepts it: they chose the game’s pick-up prompt over a carryable groundItem, or took an item from one of the world’s own piles (groundItem null). Return false from a handler and the carry is refused – the prop stays where it is, and a pile’s item is let go at once. Handlers run synchronously, so the decision cannot wait on anything awaited. A carry a script ordered with carryItem is not asked. item is the item’s name.
playerCarryItem
Section titled “playerCarryItem”playerCarryItem: [
Player,string,GroundItem|null]
Defined in: server/api.d.ts:102
Dispatched once an item carry is accepted: everybody sees the player pick it up and carry it, and player.carriedItem names it. groundItem is the prop it was taken up from, still readable here and gone a moment later, or null. It is carried until playerPutDownItem.
playerChat
Section titled “playerChat”playerChat: [
Player,string]
Defined in: server/api.d.ts:651
Dispatched when a player submits a plain chat line. Turn Chat.setDefaultRelay(false) off to own delivery yourself.
playerCombatCancelled
Section titled “playerCombatCancelled”Defined in: server/api.d.ts:42
A resource called cancelCombat for this pair. Raised after the cancellation was sent to both players and their observers.
playerCommand
Section titled “playerCommand”playerCommand: [
Player,string,string[]]
Defined in: server/api.d.ts:656
Dispatched when a player’s chat line begins with / and no built-in command claimed it. A / line is never relayed to anyone else.
playerConnect
Section titled “playerConnect”playerConnect: [
Player]
Defined in: server/api.d.ts:11
Dispatched once a connecting player’s body exists and can be resolved to a handle. The body has no pose yet – player.ready is false until the owner reports one.
playerConnecting
Section titled “playerConnecting”playerConnecting: [
PendingConnection]
Defined in: server/api.d.ts:741
Dispatched when a player asks to join, before the connection exists: they hold no player slot, are not counted as online, and are sent nothing – no resource list, no download, no body. The request waits until every handler has returned and every Promise a handler returned has settled, then it is let in if a player slot is free (otherwise it is refused as full). connection.reject() turns it away instead, and so does a handler that throws or rejects, or handlers that have not settled within the server’s admission timeout (30 seconds by default, restarted by every connection.update()). With no handler at all, every request is let in at once.
playerConsumed
Section titled “playerConsumed”playerConsumed: [
Player,Consumption]
Defined in: server/api.d.ts:146
Once after the owning client confirms successful use. Use for custom stat changes and buffs after suppressing native effects. Missing receipts and expired or replaced bodies never raise it. Inventory uses also raise playerItemUsed.
playerConsuming
Section titled “playerConsuming”playerConsuming: [
Player,Consumption]
Defined in: server/api.d.ts:131
Before reserving a food or potion unit or pot serving. Return false synchronously to refuse without spending stock or applying effects. Async handlers cannot veto. Do not apply replacement effects here: native use can still fail.
playerConsumptionEffects
Section titled “playerConsumptionEffects”playerConsumptionEffects: [
Player,Consumption]
Defined in: server/api.d.ts:136
After playerConsuming accepts, before reservation. Return false synchronously to consume without native nutrition, energy, alcohol, potion, spoilage or added pot poison effects. Apply custom effects in playerConsumed using player.setStat, addBuff and clearBuffs.
playerCustomItemUse
Section titled “playerCustomItemUse”playerCustomItemUse: [
Player,InventoryRow,number]
Defined in: server/api.d.ts:151
A validated custom-item action. The frozen row includes server-only data. Scripts decide what happens and explicitly consume items.
playerDamage
Section titled “playerDamage”playerDamage: [
Player,Player|Npc|null,number,"head"|"torso"|"leftArm"|"rightArm"|"leftLeg"|"rightLeg"|null,"unknown"|"combat"|"gunshot"|"starvation"|"collision"|"scripted"|"disintegrate"|"fall"|"poison"|"bleeding"|"selfHarm"]
Defined in: server/api.d.ts:32
Dispatched when something takes health off a player: a weapon, an arrow, a fall, a collision, a scripted hit. Player combat and server NPC melee are raised by the server as it rules on them, after playerHit had its say, so amount is what the ruling takes; anything else is reported by the hit player’s own client, which resolved it against its armour and its skills. It arrives ahead of the playerDied a killing blow causes.
attacker is the player or server NPC who dealt it, or null. bodyPart is where it landed, or null for damage that lands nowhere in particular. A player attacker’s weapon is available through rightHandItem or leftHandItem; an NPC’s equipped items are in wearing.
Bleeding, poison and hunger wear health down a tick at a time without raising this – bleeding, poisoning and hunger are live numbers already. The tick that kills does arrive, with its own reason, just before the playerDied it causes.
playerDied
Section titled “playerDied”playerDied: [
Player,Player|Npc|null,"unknown"|"combat"|"gunshot"|"starvation"|"collision"|"scripted"|"disintegrate"|"fall"|"poison"|"bleeding"|"selfHarm"]
Defined in: server/api.d.ts:23
Dispatched once per accepted death report. Call player.revive() to request revival; there is no automatic respawn.
killer is the player or server NPC whose blow took the last of the health, as the dying player’s own client saw it – null for a fall, a bleed-out, or anything without an identified attacker. reason is the game’s own for that last write: combat for a blade or a bow, fall, bleeding, poison and so on.
playerDisconnect
Section titled “playerDisconnect”playerDisconnect: [
Player]
Defined in: server/api.d.ts:16
Dispatched while a player is leaving, before their body is destroyed, so the handle still reads. Anything keyed on the player must be cleaned up here: a dropped connection raises no other event.
playerHit
Section titled “playerHit”Defined in: server/api.d.ts:49
Dispatched when another player’s blade or arrow, or a server NPC’s melee attack, lands on a player, before anything is taken – the place for teams, safe zones, friendly fire and damage rules. The game resolved the blow against the guard the victim really held – whether it was blocked, perfectly or not, and where it landed – and the server works out what a swing takes from there; it has checked that the swing was one it relayed and could still land, or that the arrow was one whose impact it accepted, and that the two stood within reach. Only what is ruled here comes off the victim’s health, on every client at once.
Return false from a handler to refuse the blow: no health is taken and no playerDamage follows. NPC melee uses the victim client’s native damage with priced: false; set hit.damage to change it. For priced player swings, scale hit.modifiers to change how a swing is worked out – a stronger attack, weaker armour – or set hit.damage to say outright what it takes: 0 for a blow that lands harmlessly, more for a heavier one. Either way the blow is still seen and heard: the blades met. Handlers run synchronously, so the decision cannot wait on anything awaited.
playerInjured
Section titled “playerInjured”playerInjured: [
Player,"head"|"torso"|"leftArm"|"rightArm"|"leftLeg"|"rightLeg"]
Defined in: server/api.d.ts:54
Dispatched when a limb becomes injured – usually a blow landing there, sometimes a fall on both legs. player.injuries already says so. A limb hit again while injured stays injured and raises nothing new.
playerInjuryHealed
Section titled “playerInjuryHealed”playerInjuryHealed: [
Player,"head"|"torso"|"leftArm"|"rightArm"|"leftLeg"|"rightLeg"]
Defined in: server/api.d.ts:59
Dispatched when a limb injury is gone: it healed by itself, a bandage took it, or player.heal did.
playerInventoryChanged
Section titled “playerInventoryChanged”playerInventoryChanged: [
Player,InventoryChange]
Defined in: server/api.d.ts:156
An inventory changed. Raised on the next server tick in the order the changes happened, once per inventory an operation touched: a transfer raises it for both players. A handler may change inventories; those changes arrive on a later tick. Every change of a player who disconnects is raised before playerDisconnect. Save from here to keep inventories across sessions – the server keeps nothing itself.
playerInventoryReady
Section titled “playerInventoryReady”playerInventoryReady: [
Player]
Defined in: server/api.d.ts:168
A player’s game shows their inventory for the first time this session. Their inventory exists from playerConnect; restore a saved one there with Inventory.set, and it is what they load in with.
playerItemUsed
Section titled “playerItemUsed”playerItemUsed: [
Player,string,"food"|"potion"|"ointment"|"shot",number]
Defined in: server/api.d.ts:163
The player’s game spent items: ate, drank, applied or fired them. Raised after the playerInventoryChanged that removed them. item is the class GUID.
This is the player’s own game saying so: the server checked that the units existed and were of a kind that can be spent that way, and took them, but did not see the meal or the shot. A handler that rewards a use – a heal, a buff – can be had for the price of the item.
playerLevelUp
Section titled “playerLevelUp”playerLevelUp: [
Player,string,number,number]
Defined in: server/api.d.ts:696
Dispatched when one of a player’s tracks reaches a new level. perkPoints is what that track’s tree now has unspent.
playerPerkAdded
Section titled “playerPerkAdded”playerPerkAdded: [
Player,string,"server"|"native"|"learned"]
Defined in: server/api.d.ts:706
Dispatched when a perk appeared on a player’s character: learnt on the perk screen, given by this server, or granted by the game on its own – a codex entry, a recipe, a combat move it teaches.
playerPerkLearning
Section titled “playerPerkLearning”playerPerkLearning: [
Player,string]
Defined in: server/api.d.ts:701
Dispatched when a player confirmed a perk on the perk screen and every rule of the game allows it: the tree’s level, the parent perk, the exclusive partner, a point to spend, and this server’s block list. Return false to refuse it; the point is not spent and their client raises progressionPerkRefused.
playerPerkRemoved
Section titled “playerPerkRemoved”playerPerkRemoved: [
Player,string,"server"|"native"]
Defined in: server/api.d.ts:711
Dispatched when a perk left a player’s character: taken or respecced by this server, or removed by the game.
playerPickpocketCaught
Section titled “playerPickpocketCaught”Defined in: server/api.d.ts:262
Dispatched when the victim noticed the thief, while charging or with the loot screen up. Nothing was taken, and no NPC reacts on the victim’s behalf: the gamemode decides what being caught means.
playerPickpocketed
Section titled “playerPickpocketed”playerPickpocketed: [
Player,Player,PickpocketLine[]]
Defined in: server/api.d.ts:257
Dispatched once a theft has settled: everything in items has already left the victim and reached the thief. The thief’s loot screen is only a claim – each line was taken from the victim first and only what really came out was handed over – so items can be shorter than what the thief took, or empty when they closed the screen with nothing. Nothing else happens to either player: whether this is a crime, and what it costs, is the gamemode’s.
playerPickpocketStart
Section titled “playerPickpocketStart”Defined in: server/api.d.ts:252
Dispatched when a player’s charge begins on the game’s own Rob entry against another player, before the victim’s pockets are opened to them – the place to decide who may rob whom. Return false from a handler and the attempt is refused: the thief’s minigame ends before its loot screen opens, and nothing else follows. Handlers run synchronously, so the decision cannot wait on anything awaited.
Whether the victim notices is the game’s own rule, played on the thief’s machine against the victim’s body: it turns on the victim’s facing and on both players’ skills, exactly as against an NPC.
playerPoisonAbsorbing
Section titled “playerPoisonAbsorbing”playerPoisonAbsorbing: [
Player,Consumption,string]
Defined in: server/api.d.ts:141
Before applying a reserved pot meal’s additional poison on its eating receipt. Return false synchronously to suppress it. Runs only when nativeEffects is true. Native food spoilage and item buffs can be replaced through playerConsumptionEffects and Buffs.claim.
playerProgressionRejected
Section titled “playerProgressionRejected”playerProgressionRejected: [
Player,string]
Defined in: server/api.d.ts:716
Dispatched when a player’s client reported progression this server never ordered: a track that rose further than any gain it granted could take it, or a perk-screen perk nobody learnt. The report is kept – the game has no way to take a level back – so what happens to the player is the handler’s call; a kick is the usual answer.
playerPutDown
Section titled “playerPutDown”Defined in: server/api.d.ts:92
Dispatched once a carry is over, however it ended: the carrier dropped the body, putDown asked them to, the carried player was revived, or either of them left. A player who is leaving is still readable here; the event comes before their body is destroyed.
playerPutDownItem
Section titled “playerPutDownItem”playerPutDownItem: [
Player,string,GroundItem|null]
Defined in: server/api.d.ts:107
Dispatched once an item carry is over, however it ended: the player put it down, putDownItem asked them to, it went into a pile, or they left. groundItem is the carryable prop it became where it fell – still falling, settling where the game’s physics puts it – or null when it went into a pile or they have no room left on the ground.
playerReady
Section titled “playerReady”playerReady: [
Player]
Defined in: server/api.d.ts:121
Dispatched once per connection, after playerSpawned, when the player can play: their own client reports that the game has taken its loading screen down. The game raises that moment itself – it is its own gameplay-start signal, not a guess from timing.
That player’s client resources were already running at playerSpawned, so this is not needed to make sure a player.emit is received. It is for what the player should actually see on arrival – a welcome, a first page, a camera shot – which shown earlier would play behind the loading screen. A client that never gets that far, or disconnects first, never raises it.
playerSpawned
Section titled “playerSpawned”playerSpawned: [
Player]
Defined in: server/api.d.ts:114
Dispatched once a joining player is really standing in the world: their level is up, their body is where playerSpawning put it, and the ground under it has loaded. Anything that acts on an arriving player – kit, a welcome line, a marker – belongs here rather than in playerConnect, which fires while they are still loading the level, or in playerSpawning, where the body is still mid-placement.
The player may still be looking at the game’s loading screen; playerReady follows once they are not.
playerSpawning
Section titled “playerSpawning”playerSpawning: [
Player]
Defined in: server/api.d.ts:68
Dispatched when a player’s body needs somewhere to stand, while their own client waits on the answer behind its loading screen. This is the one moment a spawn can be chosen without anybody seeing the body move – call player.spawn(position) from the handler and that becomes where they arrive.
Handlers run synchronously, so the choice has to be made in the handler itself rather than in something awaited from it. A handler that names no placement leaves the player at the level’s own start point, which is the same tile for everybody.
reason says whether they are arriving or coming back: join for a connection, respawn after a death.
playerStatsChanged
Section titled “playerStatsChanged”playerStatsChanged: [
Player,object[]]
Defined in: server/api.d.ts:126
After the server receives changed player stats, including poison strength, drunkenness, health loss and potion-related readings. Changes are snapshots batched per server tick. The first valid report and each new body establish a baseline. These are observations, not cancellable requests; the client can coalesce intermediate values. No cause is inferred. Use consumption vetoes and custom server effects to decide gameplay before it happens.
playerXpGained
Section titled “playerXpGained”playerXpGained: [
Player,string,number]
Defined in: server/api.d.ts:691
Dispatched when XP landed on a player’s character, from their game or from this server, after every multiplier.
playerXpGaining
Section titled “playerXpGaining”playerXpGaining: [
Player,string,number,string]
Defined in: server/api.d.ts:686
Dispatched when a player’s own game produced XP – a hit landed, a lock picked, a page read – and asks for it. Return false to refuse it; the gain then never happens. xp is before this server’s rate and the player’s own multipliers. source is the game’s name for what caused it: Attack, LockpickingResult and so on, or empty. Nothing is asked while Progression.setNativeXp(false) is in force.
propDestroy
Section titled “propDestroy”propDestroy: [
Prop]
Defined in: server/api.d.ts:352
Dispatched while a prop is being despawned. The handle still resolves, so its model and its pose can be read one last time.
propSpawn
Section titled “propSpawn”propSpawn: [
Prop]
Defined in: server/api.d.ts:347
Dispatched immediately after a prop is created and replicated, whether by Prop.spawn, the /prop command, or anything else.
questTrackingChanged
Section titled “questTrackingChanged”Defined in: server/api.d.ts:482
Dispatched when a player starts or stops following a quest in the game’s journal, whichever way it happened: the track button, the game auto-tracking a quest that turns active, or the untrack that follows finishing or failing one. The client reports it – following a quest is decided there and cannot be refused here – so a handler reacts rather than vetoes. It fires only on an actual change, and only for a quest that player was given.
resourceStart
Section titled “resourceStart”resourceStart: [
string]
Defined in: server/api.d.ts:721
Dispatched after a resource entry point has run and immediately before the resource becomes running.
resourceStop
Section titled “resourceStop”resourceStop: [
string]
Defined in: server/api.d.ts:726
Dispatched while a resource is stopping, before its stop callback, timers, exports and event handlers are cleaned up.
siegeEngineDamage
Section titled “siegeEngineDamage”siegeEngineDamage: [
SiegeEngine,number,Player|null]
Defined in: server/api.d.ts:539
Dispatched when a blast takes amount off an engine with a maxHealth, before it is wrecked by it. health already reads what is left.
siegeEngineDestroy
Section titled “siegeEngineDestroy”siegeEngineDestroy: [
SiegeEngine]
Defined in: server/api.d.ts:524
Dispatched while a siege engine is being removed. The handle still resolves.
siegeEngineReady
Section titled “siegeEngineReady”siegeEngineReady: [
SiegeEngine]
Defined in: server/api.d.ts:529
Dispatched when an engine’s load cycle finishes and it can fire.
siegeEngineSpawn
Section titled “siegeEngineSpawn”siegeEngineSpawn: [
SiegeEngine]
Defined in: server/api.d.ts:519
Dispatched immediately after a siege engine is built.
siegeEngineUse
Section titled “siegeEngineUse”siegeEngineUse: [
Player,SiegeEngine,"operate"|"winch"|"leave"|"load"|"fire"]
Defined in: server/api.d.ts:534
Dispatched when a player asks something of a usable engine, standing at it: to take its place (operate) or a free winch (winch) from the game’s own prompt, or – in its place – to load it or fire it where they laid it, with the player as the attacker. Return false to refuse. leave reports a player stepping away from either and cannot be refused. A handler that works the engine itself should refuse, so it is not worked twice.
siegeEngineWreck
Section titled “siegeEngineWreck”siegeEngineWreck: [
SiegeEngine,Player|null]
Defined in: server/api.d.ts:544
Dispatched when an engine’s health runs out. Its operator and crew have been let go, and a stone still in its sling went down with it.
siegeFire
Section titled “siegeFire”siegeFire: [
SiegeEngine,Player|null,Vector3]
Defined in: server/api.d.ts:549
Dispatched the moment an engine lets its projectile go, partway through the shot fire started.
siegeImpact
Section titled “siegeImpact”siegeImpact: [
SiegeEngine|null,Vector3,Player|null]
Defined in: server/api.d.ts:554
Dispatched where a projectile came down: what the reporting player – the attacker when near enough, else whoever is nearest the target – saw it hit, checked against the arc it was thrown on, or the target itself when nobody could see it. Players within damageRadius have already been told to take their share, and NPCs have taken theirs. engine is null when it was destroyed while the stone was in the air.
siegeLadderDestroy
Section titled “siegeLadderDestroy”siegeLadderDestroy: [
SiegeLadder]
Defined in: server/api.d.ts:564
Dispatched while a siege ladder is being removed. The handle still resolves.
siegeLadderFall
Section titled “siegeLadderFall”siegeLadderFall: [
SiegeLadder,Player|null]
Defined in: server/api.d.ts:574
Dispatched when a pushed ladder hits the ground. Anyone who was on it was thrown off as it began to fall, and took the game’s own fall.
siegeLadderRaise
Section titled “siegeLadderRaise”siegeLadderRaise: [
SiegeLadder]
Defined in: server/api.d.ts:579
Dispatched when a raised ladder leans on its wall again and can be climbed.
siegeLadderSpawn
Section titled “siegeLadderSpawn”siegeLadderSpawn: [
SiegeLadder]
Defined in: server/api.d.ts:559
Dispatched immediately after a siege ladder is placed.
siegeLadderUse
Section titled “siegeLadderUse”siegeLadderUse: [
Player,SiegeLadder,"push"|"raise"]
Defined in: server/api.d.ts:569
Dispatched when a player asks to push a usable ladder from the walk at its top, or to raise a fallen one from beside its foot. Return false to refuse.
stashClose
Section titled “stashClose”stashClose: [
Stash,Player,"closed"|"lostAccess"|"timeout"|"disconnected"|"destroyed"]
Defined in: server/api.d.ts:629
A player no longer has a container open: they closed it, walked away, died or changed world (lostAccess), sent nothing for two minutes, left, or the container went.
stashDestroy
Section titled “stashDestroy”stashDestroy: [
Stash]
Defined in: server/api.d.ts:639
A container is about to go. Raised after its close and its contents’ removal, while it can still be read.
stashInteract
Section titled “stashInteract”stashInteract: [
Player,Stash,"open"|"unlock"|"lockpick"]
Defined in: server/api.d.ts:646
Dispatched for a physical chest prompt or virtual stash open(player), before access is granted. For a prompt: the player’s client holds the game’s own handler until the server answers. action is open, unlock – a key turned, which opens it in the same use – or lockpick, the minigame starting; a successful pick then opens it without asking again.
Return false to refuse it: the prompt does nothing, and no transfer screen, key or minigame ever appears. Every handler runs whatever an earlier one returned, and an async handler cannot refuse. The server has already refused what the game’s own rules forbid – a player out of reach, a container another player has open, opening a locked one, picking one that cannot be – so this only sees what the game would allow. Virtual opening has no distance check; world, player readiness, lock and exclusive access checks still apply. Closing is never asked.
stashInventoryChanged
Section titled “stashInventoryChanged”stashInventoryChanged: [
Stash,Player|null,InventoryChange]
Defined in: server/api.d.ts:634
What a container holds changed. player moved the units – change.reason is deposit or withdraw, and their inventory raises playerInventoryChanged too – or is null for a script’s addItem, removeItem or setInventory, or destroy when the container went with something in it. Save from here to keep contents across restarts: the server keeps nothing itself. A linked child’s stash is the one the player used; its stock is its master’s.
stashOpen
Section titled “stashOpen”Defined in: server/api.d.ts:624
A player holds a container view. Physical chests report the native opening; virtual stashes report the server grant before requesting the native screen.
stashSpawn
Section titled “stashSpawn”stashSpawn: [
Stash]
Defined in: server/api.d.ts:619
A container now exists: a scripted chest, a virtual stash, or one the level places, built in a virtual world the first time anything there asked for it. Every container starts empty; restore saved contents here with setInventory. The level’s containers in the global world are built before any resource runs, so restore those from resourceStart by walking Stash.all().
stoneImpact
Section titled “stoneImpact”Defined in: server/api.d.ts:599
Dispatched where a thrown stone first met something, as its thrower saw it, checked to lie within 30 m of its pile. Players within the pile’s damageRadius have been told to take their share, and NPCs have taken theirs.
stonePileDestroy
Section titled “stonePileDestroy”stonePileDestroy: [
StonePile]
Defined in: server/api.d.ts:589
Dispatched while a stone pile is being removed. The handle still resolves.
stonePileSpawn
Section titled “stonePileSpawn”stonePileSpawn: [
StonePile]
Defined in: server/api.d.ts:584
Dispatched immediately after a stone pile is placed.
stonePileThrow
Section titled “stonePileThrow”Defined in: server/api.d.ts:594
Dispatched when a player takes a stone off a pile. The game’s own stone throwing has already lifted it and heaves it over the wall at once, so it cannot be refused; make the pile not usable to stop the next one.
vendorClosed
Section titled “vendorClosed”vendorClosed: [
number,Player,number]
Defined in: server/api.d.ts:245
Dispatched when a trading session ends, whoever ended it. 0 the player closed the screen, 1 the server closed it, 2 another vendor replaced it, 3 the client could not bring the screen up, 4 the player left.
vendorTrade
Section titled “vendorTrade”vendorTrade: [
number,Player,VendorTradeLine[],VendorTradeLine[],number]
Defined in: server/api.d.ts:240
Dispatched once a deal has settled: everything in it has already moved, in one commit on the player’s inventory whose playerInventoryChanged reason is trade. balance is what the player came out with in money units – positive when the vendor paid them. What the player sold does not join the vendor’s stock; add it with setStock here if this vendor resells.
vfxDestroy
Section titled “vfxDestroy”vfxDestroy: [
Vfx]
Defined in: server/api.d.ts:387
Dispatched while a replicated particle effect is being stopped. The handle still resolves, so its name and its pose can be read one last time.
vfxSpawn
Section titled “vfxSpawn”vfxSpawn: [
Vfx]
Defined in: server/api.d.ts:382
Dispatched immediately after a replicated particle effect is placed, whether by Vfx.spawn, a command, or anything else.
worldDayChange
Section titled “worldDayChange”worldDayChange: [
number]
Defined in: server/api.d.ts:661
Dispatched when the world clock crosses midnight, whether it walked over or World.setTime jumped past. The day it carries is the one that just began.
worldResourcesReady
Section titled “worldResourcesReady”worldResourcesReady: []
Defined in: server/api.d.ts:614
Raised once after every configured world export has loaded successfully, including an empty list. WorldResource.ready is true inside the handler. A script starting later must check WorldResource.ready first; the event is not replayed. Do not await this event inside resourceStart: exports load after script startup. Handler promises are not awaited.
worldWeatherChange
Section titled “worldWeatherChange”worldWeatherChange: [
string,string,number]
Defined in: server/api.d.ts:666
Dispatched when the sky starts blending to another time-of-day preset, from World.setWeather or the /world weather command. It is raised when the blend starts, not when it settles.