Lua runtime and sandbox

Each plugin uses Lua 5.4.8 with its own bounded state. The sandbox exposes the base, table, string, math, and UTF-8 libraries plus the public samp API.

Deliberately unavailable

The runtime does not expose file loading, dynamic code loading, garbage-collector control, bytecode dumping, the operating-system library, the I/O library, the debug library, the package library, or the raw coroutine library.

Use:

• package-local require() for modules;
• samp.storage for persistent data;
• samp.timer for one-shot timers;
• samp.task for managed sleeping tasks;
• public events instead of polling hidden game state.

Callback rules

Every callback is protected by instruction and wall-clock budgets. A callback should do a small, deterministic amount of work. Avoid large table rebuilds, unbounded loops, repeated string concatenation, and per-frame storage writes.

Only APIs marked with the managed phase may change game state. Call them from events, timers, managed tasks, or menu callbacks—not at the top level while the plugin is loading.

draw.hud APIs are valid only inside a draw.hud callback.

Errors

An API rejects wrong types, non-finite numbers, out-of-range values, missing permissions, invalid phases, and stale handles. Repeated errors or timeouts disable only the faulty plugin for the current session.