Core runtime API

Lua uses nil, boolean, number, string, function, and table. Signatures in this reference put optional arguments in brackets. A call that violates its type, range, permission, phase, or resource budget raises a Lua error unless stated otherwise.

Runtime identity

Value	Type	Meaning
samp.api.version	string	Active Plugin API version, currently "1.0".
samp.plugin.id	string	Stable ID from the installed manifest.
samp.plugin.version	string	Installed plugin version.

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

Returns boolean. name is a capability string up to 128 bytes. minimumVersion, when present, is a numeric API version such as "1.0". The result is true only when both the capability and version are supported. Use this for optional behavior, not as a replacement for manifest permissions.

Logging

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

message is a string of at most 2,048 bytes. The host attaches the plugin ID and selected severity. The functions return nothing.

Subscriptions

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

Registers callback(event) and returns a subscription handle:

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

Argument	Type	Rules
name	string	Non-empty, at most 96 bytes.
callback	function	Receives one event table.
options.priority	integer	Optional, -1000..1000, default 0; higher runs first.
options.once	boolean	Optional, default false; removes the subscription after its first dispatch.

A plugin may hold at most 256 subscriptions. Event-specific permissions are checked when subscribing. unsubscribe() is idempotent and returns nothing. See Event payloads.

Modules

require(name)

Loads modules/<name>.lua and returns the module result. Dots map to directories: require("ui.colors") loads modules/ui/colors.lua.

name is at most 128 bytes and may contain letters, digits, _, and .; leading, trailing, or repeated dots are rejected. Modules are cached by name. If a module returns nil, callers receive true. Plugins cannot load native modules or files outside their own modules/ directory.

Timers and managed tasks

samp.timer.after(delayMs, callback)

Schedules a one-shot callback and returns { cancel = function }. delayMs is an integer from 0 to 86,400,000. A plugin may have at most 256 timers. cancel() is idempotent.

samp.task.spawn(callback)

Starts a managed coroutine and returns { cancel = function }. A plugin may have at most 256 tasks. The callback has no arguments. Cancelling is idempotent; cancelling the currently executing task stops it safely.

samp.task.sleep(delayMs)

Suspends the current managed task for 0..86,400,000 milliseconds. It returns no value and raises an error outside a task created by samp.task.spawn. Ordinary event callbacks and mutable interception callbacks cannot yield.

Private storage

All storage calls require plugin.storage. Values are private to the plugin ID.

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

Item	Contract
key	1–64 ASCII characters; starts with a letter or digit; remaining characters may also use _, -, ..
value	string, boolean, or finite number.
Missing key	get returns the supplied default, or nil.
String size	At most 16 KiB per value.
Plugin quota	At most 128 entries and 1 MiB encoded data.

set and remove return nothing. Removing a missing key succeeds.

Formatting

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

Returns a locale-independent decimal string. value must be finite and have absolute value at most 9,000,000,000,000. precision is an integer 0..6, default 0. The result is rounded to the requested fixed precision.

Game state

samp.game.state()

Requires game.state.read and returns:

Field	Type	Meaning
sessionId	integer	Current runtime session identity.
playerGeneration	integer	Current local-player generation.
ready	boolean	Game services are available.
paused	boolean	The game is paused.
multiplayer	boolean	A multiplayer runtime exists.
localPlayerAvailable	boolean	A local-player Handle can currently be acquired.
interior	integer	Active interior ID, or 0 when unavailable.

The table is a snapshot; call again for fresh state.

Current server

samp.server.current()

Requires server.state.read. Returns nil without a multiplayer runtime; otherwise returns:

Field	Type	Meaning
sessionId	integer	Session to which this snapshot belongs.
address	string	Server host or IP.
port	integer	Server port.
name	string	UTF-8 server name; may be empty before it is known.
state	string	waiting, connecting, connected, joining, restarting, or unknown.
connected	boolean	Fully connected.
connecting	boolean	Connection or join is in progress.
lan	boolean	LAN mode flag.