Основная среда API

Квадратные скобки в сигнатурах обозначают необязательные параметры. Ошибка типа, диапазона, разрешения, фазы или бюджета обычно вызывает ошибку Lua.

Идентификация

Значение	Тип	Описание
samp.api.version	string	Активная версия API, сейчас "1.1".
samp.plugin.id	string	ID установленного плагина.
samp.plugin.version	string	Версия установленного плагина.

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

Возвращает boolean. Имя возможности — строка до 128 байт; версия имеет вид "1.1". Результат true, только если поддерживаются и возможность, и версия.

Журнал

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

message — строка до 2 048 байт. Функции ничего не возвращают.

Подписки

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

Возвращает Handle с методом unsubscribe():

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

Параметр	Правила
name	Непустая строка до 96 байт.
callback	Функция callback(event).
options.priority	Целое -1000..1000, по умолчанию 0; большее выполняется раньше.
options.once	Boolean, по умолчанию false; удалить после первой доставки.

До 256 подписок на плагин. Разрешение события проверяется при подписке. unsubscribe() идемпотентен. Поля описаны в событиях.

Модули

require(name)

Загружает modules/<name>.lua; точки превращаются в каталоги. Имя до 128 байт, только буквы, цифры, _ и ., без точки в начале/конце и без ... Результат кэшируется. Если модуль вернул nil, вызывающий получает true. Доступ за пределы собственного modules/ и нативные модули запрещены.

Таймеры и задачи

Сигнатура	Контракт
samp.timer.after(delayMs, callback)	Одноразовый таймер; задержка 0..86 400 000 мс; возвращает { cancel }; максимум 256.
samp.task.spawn(callback)	Управляемая корутина; возвращает { cancel }; максимум 256.
samp.task.sleep(delayMs)	Приостанавливает только управляемую задачу на 0..86 400 000 мс.

cancel() идемпотентен. Обычные события и изменяемые перехваты не могут yield.

Приватное хранилище

Требуется plugin.storage:

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

Ключ имеет 1–64 ASCII-символа, начинается с буквы/цифры; далее разрешены также _, -, .. Значение — string, boolean или конечный number. Строка — до 16 КиБ. Лимит плагина: 128 записей и 1 МиБ данных. Отсутствующий ключ возвращает default или nil; set и remove ничего не возвращают.

Форматирование

samp.format.number(value [, precision]) возвращает независимую от локали десятичную строку. Значение конечное, модуль до 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	Среда multiplayer существует.
localPlayerAvailable	boolean	Можно получить Player Handle.
interior	integer	Текущий интерьер или 0.

Сервер

samp.server.current() требует server.state.read и возвращает nil без multiplayer, иначе table:

Поле	Тип	Значение
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 }: normal содержит position/extent, race — position/radius/raceType. samp.camera.state() возвращает read-only { position, direction, up, mode, fov } или nil, если камера недоступна.

samp.network.stats() требует network.stats.read и возвращает snapshot:

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

droppedRealtime отражает давление локальной очереди, а не потерю пакетов в Интернете. Сетевые события дают префикс payload до 4096 байт и не переписывают данные синхронно.

samp.audio.play(url), samp.audio.stop() и samp.audio.state() требуют audio.playback. URL — http/https, до 255 байт; новый play заменяет текущий stream, остановить можно только свой. state() возвращает { playing, owned, url }, а при выгрузке свой stream останавливается.

samp.chat.notify() требует ui.chat, показывает только локальное уведомление; UTF-8 текст ограничен 1024 байтами, цвет — 0xAARRGGBB. Отправка через samp.chat.send()/samp.command.send() требует chat.send и проходит через обычные перехватчики; chat не начинается с /, command начинается с / и имеет символ после него, NUL/CR/LF запрещены. Clipboard требует соответствующие ui.clipboard.read/write; UTF-8 значение ограничено 16 КиБ, запись асинхронна.