Events

Subscribe with samp.events.on(name, callback, options). The returned subscription has unsubscribe().

For the exact fields, types, permissions, and mutability of every event, use the Event payload reference.

local subscription = samp.events.on("player.spawned", function(event)
    samp.log.info(event.name)
end, {
    priority = 100,
    once = true
})

-- subscription:unsubscribe()

Higher priority runs first. Use once = true for a one-shot subscription.

Event envelope

Events include a stable envelope where applicable:

Field	Meaning
name	Event name.
sequence	Monotonic dispatch sequence.
timestamp	Monotonic event time in milliseconds.
sessionId	Current game runtime session.
playerGeneration	Current local-player generation.

Main event groups

• Lifecycle: plugin.loaded, session.started, session.ended, game.ready, server.connected, server.disconnected.
• Local player: player.spawned, player.died, player.health_changed, vehicle and interior changes.
• Chat: received player messages, server messages, chat bubbles, and outgoing interception.
• World: checkpoints and streamed entity lifecycle.
• Interaction: dialogs, TextDraws, and plugin-menu controls.
• Frames: game.frame and draw.hud.

Mutable events

Some events expose writable fields. Cancellation is sticky: after one plugin sets cancelled = true, a later plugin cannot restore the operation.

samp.events.on("chat.message_received", function(event)
    samp.log.info(
        event.playerName .. ": " .. event.message
    )
end, {
    priority = 0
})

samp.events.on("chat.message_sending", function(event)
    if event.message == "!cancel" then
        event.cancelled = true
    end
end)

Mutable callbacks cannot yield. Keep them especially short because they delay the original interaction.