Event callback parameters

Subscribe with samp.events.on. Every callback receives one event table.

Common envelope

Every event contains:

Field	Type	Meaning
name	string	Exact event name.
sequence	integer	Monotonic dispatch sequence within the runtime. All subscribers to one dispatch see the same value.
timestamp	integer	Monotonic event timestamp in milliseconds; not wall-clock time.
sessionId	integer	Session associated with the event.
playerGeneration	integer	Local-player generation associated with the event.

Payload tables are valid for the callback only. Copy primitive values if a task needs them later. Unless marked mutable, changing a field has no host effect.

Lifecycle, frame, and UI events

Event	Additional fields	Notes
plugin.loaded	none	Dispatched after the entry file loads; subscribe during entry evaluation to receive it.
session.started	none	A new runtime session began.
session.ended	none	Current session ended.
game.ready	none	Game services became ready.
server.connected	none	Multiplayer connection completed.
server.disconnected	none	Connection ended.
player.spawned	none	Acquire new player/resources here.
player.died	none	Previous player-generation resources must be considered stale.
game.frame	deltaSeconds: number	Per-frame managed callback. Keep work bounded.
draw.hud	deltaSeconds, screenWidth, screenHeight: number	Only phase in which samp.draw is available.
ui.menu_opened	none	This plugin's menu became visible; requires ui.menu.
ui.menu_closed	none	This plugin's menu was closed; requires ui.menu.
ui.control_changed	pluginId, pageId, controlId: string; value: boolean/number/string	Switch: boolean; slider: number; choice/text input: string; button: "click". Filter by page and control ID.

Local-player events

Event	Permission	Payload
player.health_changed	game.player.read	previousHealth: number, health: number.
player.vehicle_entered	game.vehicle.read	vehicleId: integer, passenger: boolean.
player.vehicle_left	game.vehicle.read	vehicleId: integer, passenger: boolean.
player.interior_changed	game.state.read	previousInterior: integer, interior: integer.

player.damage_before

Requires game.player.write. Additional fields:

Field	Type	Mutability
damage	number	Writable, finite 0..100000; set 0 to suppress damage.
weaponType	integer	Read-only input.
bodyPart	integer	Read-only input.
sourceType	"player", "actor", or "entity"	Read-only input.
sourcePlayerId	integer	Present only for a known player source.
sourceActorId	integer	Present only for a known actor source.

Handlers run by priority and each sees the accepted result of earlier handlers. Invalid replacements are ignored. The callback cannot yield.

Chat events

Event	Permission	Payload
chat.message_received	chat.read	playerId: integer, playerName: string, message: string, localPlayer: boolean.
chat.server_message_received	chat.read	message: string, color: integer (ARGB).
chat.bubble_received	chat.read	playerId: integer, message: string, color: integer, drawDistance: number, durationMs: integer.

chat.message_sending

Requires chat.intercept. message: string and cancelled: boolean are writable. The replacement must be valid UTF-8, non-empty, at most 4,096 bytes, contain no NUL/CR/LF, and must not begin with /.

command.executing

Requires command.intercept. command: string and cancelled: boolean are writable. The replacement has the same 4,096-byte and line restrictions, must start with /, and must contain at least one character after it.

Cancellation is sticky for both events: once true, later handlers cannot set it back to false. Mutable interception callbacks cannot yield.

Checkpoint events

checkpoint.entered and checkpoint.left require game.state.read.

Field	Type	Meaning
kind	"normal" or "race"	Checkpoint kind.
position	Vector3	Checkpoint position.
size	Vector3	Present for box-shaped checkpoints.
radius	number	Present for radius-shaped checkpoints.
raceType	integer	Present together with radius.

Server entity events

entity.streamed_in and entity.streamed_out require game.entity.read. Both contain:

Field	Type
entityType	player, vehicle, object, actor, pickup, or text_label
entityId	integer
streamGeneration	positive integer

On streamed_in, pass all three fields to samp.entity.get. On streamed_out, an existing Handle for that identity is stale.

Dialog events

dialog.shown

Requires dialog.read.

Field	Type	Meaning
dialogId	integer	0..32767.
styleId	integer	Numeric style 0..5.
style	string	message, input, list, password, tablist, or tablist_headers.
title	string	Dialog title.
message	string	Dialog body/list data.
primaryButton	string	Primary button label.
secondaryButton	string	Secondary button label; may be empty.

All strings are UTF-8. title and each button are at most 1,024 bytes; message is at most 16 KiB.

dialog.responding

Requires dialog.intercept. Fields accepted: boolean, listItem: integer (-1..65534), input: string (valid UTF-8, maximum 4,096 bytes, no NUL/CR/LF), and cancelled: boolean are writable. dialogId is read-only. Cancellation is sticky, invalid replacements are ignored, and the callback cannot yield.

TextDraw events

All TextDraw identities combine textdrawId (0..3071) and textdrawGeneration (positive integer).

Event	Permission	Additional payload
textdraw.shown	textdraw.read	identity, styleId: integer, text: string, selectable: boolean, x: number, y: number.
textdraw.hidden	textdraw.read	identity.
textdraw.text_changed	textdraw.read	identity, text: string.
textdraw.clicking	textdraw.intercept	identity, writable cancelled: boolean.

Text may contain at most 4,096 bytes in an event. Click cancellation is sticky; the interception callback cannot yield.