Events reference

Generated from sdk/api.toml by sdk/tools/apigen.py docs. Do not edit; edit the schema.

All of these are subscribed with node.on(name, fn) (C: the register_*_event family), except where an entry names another function. Handlers receive objects and decoded payloads as listed under Handler arguments; node.raw.on delivers the Raw arguments (ids and strings) instead. Handlers run on the plugin worker thread, one at a time. Read Events for the model; this page is the list.

Names follow two rules: a notification reads <subject><Verb-ed> (playerJoined, vehicleSpawned), a request a handler can deny reads <subject><Action>Request (playerConnectRequest, relayRequest). An event that was renamed lists its old spelling under Formerly: the old name still works – it subscribes to the same event, from Lua and from C – and logs one warning per resource per old name ([deprecated] event "onPlayerConnectRequest" is now "playerConnectRequest"). The old names are removed in 2.0.

Contents

• Engine events (observe) – playerAuthenticated, playerJoined, playerLeft, serverTick, serverShutdown, resourceUnload, vehicleSpawned, vehicleDeleted, vehicleDamageChanged, vehicleTagsChanged, vehicleLockChanged, vehiclePositionChanged, vehicleInputsChanged, vehicleElectricsChanged, vehiclePowertrainChanged, vehicleEngineChanged, vehicleNodesChanged, playerInputsChanged, playerHeadPoseChanged, vehicleTeleported, vehicleBreakGroupsChanged, playerCameraChanged
• Notifications (observe, with data) – vehicleEdited, vehicleReset, vehiclePainted, playerSeatChanged, vehicleCouplerChanged, vehicleControllerChanged, playerVerifyReported
• Cancellable requests (decide) – playerConnectRequest, vehicleSpawnRequest, vehicleEnterRequest, vehicleExitRequest, vehicleCouplerRequest, vehicleEditRequest, vehiclePaintRequest, vehicleTriggerRequest, vehicleNodeGrabRequest
• The relay filter – relayRequest
• Wire events from clients – <domain>:<verb>
• Module channel – module channel
• Inter-resource bus – resource event

Engine events (observe)

Fired by the server after something happened. Handlers get the subject – a Player or a Vehicle object – or nothing where there is none (serverTick, serverShutdown); return values are ignored. Subscribe with node.on(name, fn). (node.raw.on hands the raw id instead.) Names read <subject><Verb-ed>.

playerAuthenticated

node.on("playerAuthenticated", function(player) ... end)

Handler arguments: player
Raw arguments (node.raw.on): playerId
Formerly: playerConnecting (deprecated alias, warns once, removed in 2.0)

A client has authenticated and passed playerConnectRequest; it is about to receive the join replay. Its name and IP are readable already; it has no vehicles yet.

playerJoined

node.on("playerJoined", function(player) ... end)

Handler arguments: player
Raw arguments (node.raw.on): playerId
Formerly: playerJoin (deprecated alias, warns once, removed in 2.0)

The client finished joining: the world replay was delivered and it is now a normal participant. The usual place to greet, assign a role, or restore per-player state.

playerLeft

node.on("playerLeft", function(player) ... end)

Handler arguments: player
Raw arguments (node.raw.on): playerId

The client disconnected (quit, kicked, banned or timed out). Its vehicles are deleted around the same time, each with its own vehicleDeleted. The id will be reused by a later player.

serverTick

node.on("serverTick", function() ... end)

Handler arguments: none
Raw arguments (node.raw.on): -1

Once per server tick on the plugin worker. The single argument is always -1. Keep it cheap: this shares the thread with every other handler.

serverShutdown

node.on("serverShutdown", function() ... end)

Handler arguments: none
Raw arguments (node.raw.on): -1
Formerly: onShutdown (deprecated alias, warns once, removed in 2.0)

The server is stopping. Flush what you must; timers and coroutines will not run again. Plain pg.exec / pg.query statements issued from the handler are drained to the database before the pool closes, but their callbacks do not run (the worker has stopped; the server logs how many were dropped), and a callback-form pg.tx cannot commit – its coroutine needs the worker between BEGIN and COMMIT, so the pool rolls it back. The argument is -1. Each resource’s own resourceUnload(“shutdown”) follows it.

resourceUnload

node.on("resourceUnload", function(reason) ... end)

Handler arguments: reason
Raw arguments (node.raw.on): -1, -1, reason

THIS resource is about to be unloaded (server 1.2.0): its Lua state is dropped right after every handler returned. reason is “reload” – node.resources.reload (or a reload from the console) is replacing the resource, and the new instance’s entry point runs after this – or “shutdown” – the server is stopping, and this follows serverShutdown. Dispatched synchronously and to the unloading resource’s handlers only, never to another resource’s. The same limitations as serverShutdown: node.storage writes are kept (in memory at once, so the new instance reads them; flushed to disk before the server exits) and plain pg.exec / pg.query statements are delivered, but callbacks, timers and coroutines started here will not run again – put nothing after an await. Raw arguments are (-1, -1, reason): observe it from C with register_vehicle_event (the three-argument form; a native module is never a resource, so a hosted resource of another language host is the only C-side subscriber that ever hears it).

vehicleSpawned

node.on("vehicleSpawned", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

A vehicle entered the registry – spawned by a player (after vehicleSpawnRequest allowed it) or by node.spawnVehicle. The record is readable via node.getVehicle.

vehicleDeleted

node.on("vehicleDeleted", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

A vehicle left the registry: deleted by its player, by the server, or because its player left. The record is gone by the time this fires; anything you cached about it is now yours alone.

vehicleDamageChanged

node.on("vehicleDamageChanged", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

The vehicle’s damage blob changed (the authority sent a new one). Read counters and the blob with node.getVehicleDamage.

vehicleTagsChanged

node.on("vehicleTagsChanged", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

A plugin set or removed a tag on the vehicle. Read the new set with node.getVehicleTags.

vehicleLockChanged

node.on("vehicleLockChanged", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

A plugin changed the vehicle’s lock. Read the new mode and whitelist with node.getVehicleLock.

vehiclePositionChanged

node.on("vehiclePositionChanged", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

The vehicle’s sync authority sent a position snapshot – 60 Hz per vehicle while it is simulated. Read it with getVehicleTransform (and getVehicleControls when hasControls). Fired per accepted packet, COALESCED: at most one dispatch per (event, id) is pending at a time, so a handler that keeps up sees every packet and one that lags sees fewer, never a growing queue. Nothing is posted when nobody subscribed. The argument is the id only: read the data with the getter, which hands back the LATEST cached state – that is what makes coalescing lossless. For a radar or minimap prefer getVehicleTransforms on a timer: one read for every vehicle instead of one event each.

vehicleInputsChanged

node.on("vehicleInputsChanged", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

The driver’s extra input axes changed (State::Inputs is sent only on change; up to 30 Hz per vehicle while an axis moves). Read the merged set with getVehicleInputs. Fired per accepted packet, COALESCED: at most one dispatch per (event, id) is pending at a time, so a handler that keeps up sees every packet and one that lags sees fewer, never a growing queue. Nothing is posted when nobody subscribed. The argument is the id only: read the data with the getter, which hands back the LATEST cached state – that is what makes coalescing lossless.

vehicleElectricsChanged

node.on("vehicleElectricsChanged", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

An electrics delta arrived (up to 30 Hz per vehicle while gauges move). Read the merged state with getVehicleElectrics. Fired per accepted packet, COALESCED: at most one dispatch per (event, id) is pending at a time, so a handler that keeps up sees every packet and one that lags sees fewer, never a growing queue. Nothing is posted when nobody subscribed. The argument is the id only: read the data with the getter, which hands back the LATEST cached state – that is what makes coalescing lossless.

vehiclePowertrainChanged

node.on("vehiclePowertrainChanged", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

A powertrain delta arrived (up to 10 Hz per vehicle). Read the merged state with getVehiclePowertrain. Fired per accepted packet, COALESCED: at most one dispatch per (event, id) is pending at a time, so a handler that keeps up sees every packet and one that lags sees fewer, never a growing queue. Nothing is posted when nobody subscribed. The argument is the id only: read the data with the getter, which hands back the LATEST cached state – that is what makes coalescing lossless.

vehicleEngineChanged

node.on("vehicleEngineChanged", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

An engine delta arrived (up to 10 Hz per vehicle). Read the merged state with getVehicleEngine. Fired per accepted packet, COALESCED: at most one dispatch per (event, id) is pending at a time, so a handler that keeps up sees every packet and one that lags sees fewer, never a growing queue. Nothing is posted when nobody subscribed. The argument is the id only: read the data with the getter, which hands back the LATEST cached state – that is what makes coalescing lossless.

vehicleNodesChanged

node.on("vehicleNodesChanged", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

A node-position packet arrived (up to 15 Hz per vehicle while the deformation changes). Read it with getVehicleNodes. Fired per accepted packet, COALESCED: at most one dispatch per (event, id) is pending at a time, so a handler that keeps up sees every packet and one that lags sees fewer, never a growing queue. Nothing is posted when nobody subscribed. The argument is the id only: read the data with the getter, which hands back the LATEST cached state – that is what makes coalescing lossless.

playerInputsChanged

node.on("playerInputsChanged", function(player) ... end)

Handler arguments: player
Raw arguments (node.raw.on): playerId

The player, driving, sent new inputs: a position snapshot carrying its controls (60 Hz) or an extra-axes delta. Read everything with getPlayerInputs. Fired per accepted packet, COALESCED: at most one dispatch per (event, id) is pending at a time, so a handler that keeps up sees every packet and one that lags sees fewer, never a growing queue. Nothing is posted when nobody subscribed. The argument is the id only: read the data with the getter, which hands back the LATEST cached state – that is what makes coalescing lossless. The per-player form of vehicleInputsChanged / vehiclePositionChanged for tools that think in players, not cars.

playerHeadPoseChanged

node.on("playerHeadPoseChanged", function(player) ... end)

Handler arguments: player
Raw arguments (node.raw.on): playerId

The player sent a head/camera pose (about 10 Hz). Read it with getPlayerHeadPose. Fired per accepted packet, COALESCED: at most one dispatch per (event, id) is pending at a time, so a handler that keeps up sees every packet and one that lags sees fewer, never a growing queue. Nothing is posted when nobody subscribed. The argument is the id only: read the data with the getter, which hands back the LATEST cached state – that is what makes coalescing lossless.

vehicleTeleported

node.on("vehicleTeleported", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

A position snapshot carried the teleport flag: the vehicle jumped – a reset, a recovery, a server teleport – rather than drove. One event per such snapshot (rare), not coalesced. getVehicleTransform shows where it landed.

vehicleBreakGroupsChanged

node.on("vehicleBreakGroupsChanged", function(vehicle) ... end)

Handler arguments: vehicle
Raw arguments (node.raw.on): globalId

The vehicle reported break groups (parts detaching, glass breaking). Read the merged set with getVehicleBreakGroups. One event per report; they are sent only when something breaks.

playerCameraChanged

node.on("playerCameraChanged", function(player) ... end)

Handler arguments: player
Raw arguments (node.raw.on): playerId

The player’s camera moved to another vehicle – its own or one it spectates. Read the target with getPlayerCamera. One event per report. In a strict session (player:setStrict, ABI 1.12) a report that targets a vehicle the player does not occupy is not relayed to the other clients; it still fires this event, and the record player:camera() hands back then carries denied = true (absent otherwise) – the spectate attempt an audit wants to see. The argument cannot carry the flag itself: the event’s single argument is the player id, as for every engine event.

Notifications (observe, with data)

Fired AFTER the server acted on something a player did – relayed and cached an action on a vehicle, or judged a report the player’s launcher sent. Handlers get (player, vehicle, payload) – the payload decoded into a table where it is JSON, a string where it is a role name (see each event); where no vehicle is involved the raw argument is a fixed -1 and the handler gets (player, payload); return values are ignored. C observes them with register_vehicle_event.

vehicleEdited

node.on("vehicleEdited", function(player, vehicle, config) ... end)

Handler arguments: player, vehicle, config (table)
Raw arguments (node.raw.on): playerId, globalId, configJson

The player changed the vehicle’s configuration (parts, tuning) and the server relayed and cached it. data is the new config JSON text – the same the joiner replay carries.

vehicleReset

node.on("vehicleReset", function(player, vehicle, posRot) ... end)

Handler arguments: player, vehicle, posRot (table)
Raw arguments (node.raw.on): playerId, globalId, posRotJson

The player reset the vehicle (Insert / recover). data is the position/rotation JSON it was reset to. Observe-only: there is no clean previous value to restore, so it cannot be denied.

vehiclePainted

node.on("vehiclePainted", function(player, vehicle, paints) ... end)

Handler arguments: player, vehicle, paints (table)
Raw arguments (node.raw.on): playerId, globalId, paintsJson

The player repainted the vehicle and the server relayed and cached it. data is the paints JSON.

playerSeatChanged

node.on("playerSeatChanged", function(player, vehicle, role) ... end)

Handler arguments: player, vehicle (nil on foot), role
Raw arguments (node.raw.on): playerId, globalId|-1, role

A player’s seat changed: entered or left a vehicle, was seated/unseated/swapped by the server, or took over a vehicle after its authority left (grace takeover). globalId is -1 when the player is now on foot; role is “driver”, “passenger” or “none”.

vehicleCouplerChanged

node.on("vehicleCouplerChanged", function(player, vehicle, call) ... end)

Handler arguments: player, vehicle, call (table)
Raw arguments (node.raw.on): playerId, globalId, callJson

A coupler/door operation by the player was accepted, merged into the cache and relayed; data is the coupler call JSON. The after-the-fact twin of vehicleCouplerRequest, for resources that log or react rather than decide. Skipped entirely when nobody subscribed.

vehicleControllerChanged

node.on("vehicleControllerChanged", function(player, vehicle, call) ... end)

Handler arguments: player, vehicle, call (table)
Raw arguments (node.raw.on): playerId, globalId, callJson

One controller call from the vehicle’s driver or authority was accepted and merged (lights, wipers, a mod’s controller); data is the call JSON {controllerName, functionName, …}. Sent by clients only when a call changes, so sparse in practice. Skipped entirely when nobody subscribed.

playerVerifyReported

node.on("playerVerifyReported", function(player, report) ... end)

Handler arguments: player, report (table)
Raw arguments (node.raw.on): playerId, -1, reportJson

The player’s launcher helper reported a game-install check (ABI 1.12): the one every join runs at the level [General] VerifyGame asks for, and every mid-session one – requested with player:verify(level), or run by the helper on its own schedule or after a file changed. No vehicle is involved (the raw second argument is a fixed -1, which the handler does not see). report is { level = "size"|"scripts"|"full"|"strict", outcome = "clean"|"differs"|"failed", problems = <number of mismatches, as the helper reported it>, detail = <text: the first mismatching paths, or why the check could not run>, manifest = <the hash of the reference manifest the helper checked against; "" unless level is "strict"> }. Fired AFTER the server’s own verdict: a “differs” or “failed” report has already kicked the player when VerifyGame is not off, so the player may be on its way out when the handler runs – read what you need from it right away (its record, or at least its name, is still there until playerLeft has run). Observe-only; there is nothing to deny.

Cancellable requests (decide)

Fired BEFORE the server performs an action a client asked for. Handlers get (player, vehicle, payload) – the payload decoded where it is JSON; a handler that returns false – optionally with a reason string as a second value – denies the action, and the first denial wins. Every cancellable name can also be observed: a handler that returns nothing sees the request and changes nothing. Names read <subject><Action>Request.

playerConnectRequest

node.on("playerConnectRequest", function(player, name)
  return false, "reason"  -- deny
end)

Handler arguments: player, name
Raw arguments (node.raw.on): playerId, -1, name
Return: false[, reason] denies
Formerly: onPlayerConnectRequest (deprecated alias, warns once, removed in 2.0)

A client authenticated and asks to join; data is its name. Denying disconnects it with the reason (shown to the player). Bans are checked before this fires.

vehicleSpawnRequest

node.on("vehicleSpawnRequest", function(player, requestedId, config)
  return false, "reason"  -- deny
end)

Handler arguments: player, requestedId, config (table)
Raw arguments (node.raw.on): playerId, requestedId, configJson
Return: false[, reason] denies
Formerly: onVehicleSpawnRequest (deprecated alias, warns once, removed in 2.0)

The player asks to spawn a vehicle; data is the spawn config JSON (jbm, vcf, pos, rot, …). The second argument is the id the client proposed, not the final global id. Denying tells the client, which removes the car locally.

vehicleEnterRequest

node.on("vehicleEnterRequest", function(player, vehicle, role)
  return false, "reason"  -- deny
end)

Handler arguments: player, vehicle, role
Raw arguments (node.raw.on): playerId, globalId, role
Return: false[, reason] denies
Formerly: onVehicleEnterRequest (deprecated alias, warns once, removed in 2.0)

The player asks to take a seat; data is the role, “driver” or “passenger”. Fired after the vehicle’s lock allowed the claim. Denying leaves the player where it was.

vehicleExitRequest

node.on("vehicleExitRequest", function(player, vehicle, role)
  return false, "reason"  -- deny
end)

Handler arguments: player, vehicle, role
Raw arguments (node.raw.on): playerId, globalId, role
Return: false[, reason] denies
Formerly: onVehicleExitRequest (deprecated alias, warns once, removed in 2.0)

The player asks to leave its seat (go on foot or switch); data is the role it holds. Denying keeps the player seated.

vehicleCouplerRequest

node.on("vehicleCouplerRequest", function(player, vehicle, call)
  return false, "reason"  -- deny
end)

Handler arguments: player, vehicle, call (table)
Raw arguments (node.raw.on): playerId, globalId, callJson
Return: false[, reason] denies
Formerly: onVehicleCouplerRequest (deprecated alias, warns once, removed in 2.0)

The player operates a coupler or door; data is the coupler call JSON (the client Coupler schema). Denying suppresses the relay and the cache update.

vehicleEditRequest

node.on("vehicleEditRequest", function(player, vehicle, config)
  return false, "reason"  -- deny
end)

Handler arguments: player, vehicle, config (table)
Raw arguments (node.raw.on): playerId, globalId, configJson
Return: false[, reason] denies
Formerly: onVehicleEditRequest (deprecated alias, warns once, removed in 2.0)

The player changed the vehicle’s config. The client applied it optimistically, so a deny does not only suppress the relay: the server sends the initiator the PREVIOUS cached config back and its local change rolls back to the server’s truth.

vehiclePaintRequest

node.on("vehiclePaintRequest", function(player, vehicle, paints)
  return false, "reason"  -- deny
end)

Handler arguments: player, vehicle, paints (table)
Raw arguments (node.raw.on): playerId, globalId, paintsJson
Return: false[, reason] denies
Formerly: onVehiclePaintRequest (deprecated alias, warns once, removed in 2.0)

The player repainted the vehicle; optimistic on the initiator like edits, so a deny rolls the paint back to the previous cached one.

vehicleTriggerRequest

node.on("vehicleTriggerRequest", function(player, vehicle, call)
  return false, "reason"  -- deny
end)

Handler arguments: player, vehicle, call (table)
Raw arguments (node.raw.on): playerId, globalId, callJson
Return: false[, reason] denies
Formerly: onVehicleTriggerRequest (deprecated alias, warns once, removed in 2.0)

The player asks the vehicle’s sync authority to execute a controller call (in-world triggers on someone else’s car); data is the call JSON {controllerName, functionName, variables…}. Default allow. Server-side node.triggerVehicle does not fire this: the server never asks itself.

vehicleNodeGrabRequest

node.on("vehicleNodeGrabRequest", function(player, vehicle, grab)
  return false, "reason"  -- deny
end)

Handler arguments: player, vehicle, grab (table)
Raw arguments (node.raw.on): playerId, globalId, grabJson
Return: false[, reason] denies; NO HANDLER ALSO DENIES
Formerly: onVehicleNodeGrabRequest (deprecated alias, warns once, removed in 2.0)

The player wants to grab, move or release a node of the vehicle with the experimental node grabber; data is the grab JSON. FAIL-CLOSED: unlike every other cancellable, with no handler registered the request is denied, so enabling node grabbing needs a resource that says yes (see nodemp-relay). Also gated by the server’s node-grab flag (node.isNodeGrabEnabled).

The relay filter

One hook that is neither an event nor a request: a question the relay asks per packet. It is named like the requests, relayRequest, because false from a handler decides something – here, that one receiver does not get one packet.

relayRequest

node.relay.filter(function(fromPid, toPid, cat, sub, gid) return false end)

Handler arguments: fromPlayerId, toPlayerId, category, subtype, globalId
Return: false hides the packet
C: register_relay_filter
Formerly: canRelay (deprecated alias, warns once, removed in 2.0)

Consulted per (sender, receiver, packet category, subtype, vehicle) before a relay; return false to hide the packet from that receiver. Verdicts are cached, so call node.invalidateRelayCache when the data your hook reads has changed. Subscribed through node.on(“relayRequest”, fn) – or node.relay.filter(fn) – even though it is not a builtin; the handler keeps the raw ids, as this runs on the hot path. Visibility groups are the coarse, cached-for-you alternative.

Wire events from clients

Not a fixed list: a resource defines its own wire events by using a name. The same node.on subscribes to them with (player, data); the name not being a builtin is what makes it a wire event.

<domain>:<verb>

node.on("chat:send", function(player, data) ... end)
player:send("chat:msg", msg)          -- a table is JSON-encoded
node.broadcast("chat:msg", msg)

Handler arguments: playerId, data

A wire event a client sent with node.emitServer(name, data) – data is the string the client passed, by convention JSON. Any name that is not a builtin is a wire event; the naming rule is lowercase <domain>:<verb> (chat:send, vehicle:trigger). The same node.on subscribes; emitClient/emitAll send in the other direction. A resource defines its own events simply by using a name.

Module channel

Raw bytes on a numbered channel, for native modules and their client halves.

module channel

node.modules.on(channel, function(player, data) ... end)
node.modules.send(player, channel, data)  -- "all" broadcasts

Handler arguments: playerId, data
C: register_module_channel

Inbound binary data on one u32 channel, subscribed with node.onModule(channel, fn). data is an arbitrary binary string; nothing is parsed.

Inter-resource bus

Messages between resources on the same server.

resource event

node.bus.on("name", function(sourceResource, data) ... end)
node.bus.emit("name", data)

Handler arguments: sourceResourceName, data
C: register_resource_event

A message another resource (or native module) published with node.emitResource(name, data), subscribed with node.onResource(name, fn). Delivered asynchronously on the worker, to the sender as well.

Renamed events

The old spelling on the left keeps working as a deprecated alias of the name on the right (one warning per resource per old name); node.off accepts either spelling for a handler subscribed under either. Removed in 2.0.

Old name	Canonical name
playerConnecting	playerAuthenticated
playerJoin	playerJoined
onShutdown	serverShutdown
onPlayerConnectRequest	playerConnectRequest
onVehicleSpawnRequest	vehicleSpawnRequest
onVehicleEnterRequest	vehicleEnterRequest
onVehicleExitRequest	vehicleExitRequest
onVehicleCouplerRequest	vehicleCouplerRequest
onVehicleEditRequest	vehicleEditRequest
onVehiclePaintRequest	vehiclePaintRequest
onVehicleTriggerRequest	vehicleTriggerRequest
onVehicleNodeGrabRequest	vehicleNodeGrabRequest
canRelay	relayRequest