事件回调参数

使用 samp.events.on 订阅。每个回调接收一个 event table。

公共 Envelope

每个事件都包含：

字段	类型	说明
name	string	精确事件名。
sequence	integer	运行时内单调递增的派发序号；同一次派发的所有订阅者看到相同值。
timestamp	integer	单调时钟毫秒数，不是系统日期时间。
sessionId	integer	事件所属会话。
playerGeneration	integer	事件对应的本地玩家世代。

payload table 只应在当前回调中使用；任务需要延后处理时复制其中的基础值。 未标记“可写”的字段即使被修改，也不会影响宿主行为。

生命周期、帧与 UI

事件	附加字段	说明
plugin.loaded	无	入口文件加载后派发；必须在入口求值期间订阅。
session.started	无	新运行会话开始。
session.ended	无	当前会话结束。
game.ready	无	游戏服务就绪。
server.connected	无	多人游戏连接完成。
server.disconnected	无	连接结束。
player.spawned	无	应在这里重新取得玩家及相关资源。
player.died	无	旧玩家世代资源应视为失效。
game.frame	deltaSeconds: number	每帧托管回调，工作必须有界。
draw.hud	deltaSeconds、screenWidth、screenHeight: number	唯一允许调用 samp.draw 的阶段。
ui.menu_opened	无	本插件菜单打开；需要 ui.menu。
ui.menu_closed	无	本插件菜单关闭；需要 ui.menu。
ui.control_changed	pluginId、pageId、controlId: string；value: boolean/number/string	switch 为 boolean；slider 为 number；choice/text input 为 string；button 为 "click"。应按页面和控件 ID 过滤。

本地玩家事件

事件	权限	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

需要 game.player.write：

字段	类型	可变性
damage	number	可写，有限 0..100000；写入 0 可阻止伤害。
weaponType	integer	只读输入。
bodyPart	integer	只读输入。
sourceType	"player"、"actor" 或 "entity"	只读输入。
sourcePlayerId	integer	仅来源是已知玩家时存在。
sourceActorId	integer	仅来源是已知 Actor 时存在。

回调按优先级执行，后续回调能看到之前已接受的 damage。无效修改会被忽略， 该回调不能 yield。

聊天事件

事件	权限	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

需要 chat.intercept。message: string 与 cancelled: boolean 可写。 替换文本必须是有效 UTF-8、非空、最多 4,096 字节，不含 NUL/CR/LF，且不能 以 / 开头。

command.executing

需要 command.intercept。command: string 与 cancelled: boolean 可写。 替换值同样最多 4,096 字节且不能包含换行，必须以 / 开头，并至少还有一个 字符。

两者的取消都是粘性的：一旦设为 true，后续回调不能恢复为 false。可变拦截 回调不能 yield。

检查点事件

checkpoint.entered 与 checkpoint.left 需要 game.state.read。

字段	类型	说明
kind	"normal" 或 "race"	检查点类型。
position	Vector3	坐标。
size	Vector3	方盒形检查点时存在。
radius	number	半径形检查点时存在。
raceType	integer	与 radius 一同存在。

服务器实体事件

entity.streamed_in 与 entity.streamed_out 需要 game.entity.read：

字段	类型
entityType	player、vehicle、object、actor、pickup 或 text_label
entityId	integer
streamGeneration	正 integer

streamed_in 时可将三个字段传给 samp.entity.get；streamed_out 后对应旧 Handle 已失效。

Dialog 事件

dialog.shown

需要 dialog.read：

字段	类型	说明
dialogId	integer	0..32767。
styleId	integer	数字样式 0..5。
style	string	message、input、list、password、tablist 或 tablist_headers。
title	string	标题。
message	string	正文或列表数据。
primaryButton	string	主按钮文字。
secondaryButton	string	次按钮文字，可能为空。

所有字符串均为 UTF-8；title 和每个按钮最长 1,024 字节，message 最长 16 KiB。

dialog.responding

需要 dialog.intercept。accepted: boolean、listItem: integer （-1..65534）、input: string（有效 UTF-8、最多 4,096 字节、不含 NUL/CR/LF）以及 cancelled: boolean 可写；dialogId 只读。取消是粘性的， 无效替换会被忽略，回调不能 yield。

TextDraw 事件

TextDraw 身份由 textdrawId（0..3071）和正整数 textdrawGeneration 共同组成。

事件	权限	附加 Payload
textdraw.shown	textdraw.read	身份、styleId: integer、text: string、selectable: boolean、x: number、y: number。
textdraw.hidden	textdraw.read	身份。
textdraw.text_changed	textdraw.read	身份、text: string。
textdraw.clicking	textdraw.intercept	身份、可写 cancelled: boolean。

事件中的 text 最多 4,096 字节。点击取消是粘性的，拦截回调不能 yield。