核心运行环境 API

签名中的方括号表示可选参数。参数类型、范围、权限、调用阶段或资源预算不符合 要求时，函数通常会抛出 Lua 错误。

运行时信息

值	类型	说明
samp.api.version	string	当前 Plugin API 版本，当前为 "1.1"。
samp.plugin.id	string	Manifest 中的稳定插件 ID。
samp.plugin.version	string	当前安装的插件版本。

samp.api.has(name [, minimumVersion])

返回 boolean。name 是最长 128 字节的能力名；minimumVersion 可选， 格式如 "1.1"。只有能力存在且版本要求满足时才返回 true。它适合检测 可选能力，但不能代替 Manifest 权限声明。

日志

samp.log.debug(message)
samp.log.info(message)
samp.log.warn(message)
samp.log.error(message)

message 必须是最长 2,048 字节的字符串。宿主会自动添加插件 ID 和日志级别， 函数无返回值。

事件订阅

samp.events.on(name, callback [, options])

注册 callback(event) 并返回订阅 Handle：

local subscription = samp.events.on("player.spawned", callback, {
    priority = 100,
    once = true
})
subscription:unsubscribe()

参数	类型	规则
name	string	非空，最长 96 字节。
callback	function	接收一个事件 table。
options.priority	integer	可选，-1000..1000，默认 0；数值越高越先执行。
options.once	boolean	可选，默认 false；首次派发后自动取消订阅。

每个插件最多同时拥有 256 个订阅。订阅时会检查该事件所需权限。 unsubscribe() 可重复调用且无返回值。完整字段见事件回调参数。

Lua 模块

require(name)

从 modules/<name>.lua 加载模块并返回模块结果。点号会映射为目录，例如 require("ui.colors") 加载 modules/ui/colors.lua。

模块名最长 128 字节，只能包含字母、数字、_ 和 .，不能以点开头或结尾， 也不能出现连续点号。模块按名称缓存；模块返回 nil 时调用者得到 true。 插件不能加载原生模块，也不能读取自身 modules/ 之外的文件。

定时器与托管任务

samp.timer.after(delayMs, callback)

创建一次性定时器，返回 { cancel = function }。delayMs 是 0..86,400,000 的整数；每个插件最多 256 个定时器。cancel() 可重复调用。

samp.task.spawn(callback)

启动托管协程并返回 { cancel = function }。每个插件最多 256 个任务。 回调没有参数；取消当前正在运行的任务会安全终止它。

samp.task.sleep(delayMs)

将当前托管任务暂停 0..86,400,000 毫秒，无返回值。只能在 samp.task.spawn 创建的任务中调用。普通事件回调和可变拦截事件不能 yield。

插件私有存储

以下函数均需要 plugin.storage：

local value = samp.storage.get(key [, default])
samp.storage.set(key, value)
samp.storage.remove(key)

项目	约束
key	1–64 个 ASCII 字符；首字符为字母或数字；后续还可以使用 _、-、.。
value	string、boolean 或有限 number。
键不存在	get 返回传入的默认值；未传默认值时返回 nil。
单个字符串	最多 16 KiB。
插件配额	最多 128 个条目、1 MiB 编码数据。

set 和 remove 无返回值；删除不存在的键也视为成功。

当前会话优先使用内存缓存，磁盘写入由有界异步队列完成。每个插件最多排队 64 个不同键的写入；卸载时宿主会等待该插件的待写入项，并使用临时文件和 备份文件恢复被中断的写入。

数字格式化

samp.format.number(value [, precision])

返回与系统区域无关的十进制定长字符串。value 必须有限且绝对值不超过 9,000,000,000,000；precision 为 0..6 的整数，默认 0，结果会四舍五入。

游戏状态

samp.game.state()

需要 game.state.read，返回快照：

字段	类型	说明
sessionId	integer	当前运行会话标识。
playerGeneration	integer	当前本地玩家世代。
ready	boolean	游戏服务是否可用。
paused	boolean	游戏是否暂停。
multiplayer	boolean	多人游戏运行环境是否存在。
localPlayerAvailable	boolean	当前是否能取得本地玩家 Handle。
interior	integer	当前室内 ID；不可用时为 0。

当前服务器

samp.server.current()

需要 server.state.read。没有多人游戏运行环境时返回 nil，否则返回：

字段	类型	说明
sessionId	integer	快照所属会话。
address	string	主机名或 IP。
port	integer	服务器端口。
name	string	UTF-8 服务器名称；尚未取得时可能为空。
state	string	waiting、connecting、connected、joining、restarting 或 unknown。
connected	boolean	是否已完全连接。
connecting	boolean	是否正在连接或加入。
lan	boolean	LAN 模式标志。

API 1.1 快照与消息接口

samp.world.time() 和 samp.world.weather() 需要 game.state.read，分别 返回 { hour, minute } 与 { weather, holdTime }，不可用时返回 nil。 samp.checkpoint.state() 返回 { normal, race }；普通检查点包含 position、extent，竞速检查点包含 position、radius、raceType。 samp.camera.state() 返回只读的 { position, direction, up, mode, fov }， 摄像机不可用时返回 nil。

samp.network.stats() 需要 network.stats.read，返回只读传输快照：

{
    queuedPackets, queueHighWatermark,
    receivedPackets, receivedBytes, sentPackets, sentBytes,
    droppedRealtime, rejectedMalformed, maxDispatchAgeMs,
    droppedInspectionEvents, interceptionBypasses
}

droppedRealtime 是客户端队列压力，不是互联网丢包率；网络事件只提供最多 4,096 字节的 payload 前缀，不能用来同步改写数据。

samp.audio.play(url)、samp.audio.stop() 和 samp.audio.state() 需要 audio.playback。URL 必须是最长 255 字节的 http 或 https 地址；成功播放 后当前流归调用插件所有，新的播放会替换旧流，插件只能停止自己拥有的流。 state() 返回 { playing, owned, url }，卸载时自动停止插件拥有的流。

samp.chat.notify() 需要 ui.chat，只显示本地通知；文本必须是 UTF-8， 每条最长 1,024 字节，颜色使用 0xAARRGGBB。samp.chat.send() 与 samp.command.send() 需要 chat.send，仍会经过正常拦截链；聊天不能以 / 开头，命令必须以 / 开头并至少还有一个字符，文本不得包含 NUL、CR 或 LF。 samp.clipboard.get() 和 .set() 分别需要 ui.clipboard.read 与 ui.clipboard.write；剪贴板文本使用 UTF-8，单次最长 16 KiB，写入异步提交。