Struct Amx 

pub struct Amx { /* private fields */ }

Wrapper over the raw *mut AMX and the exported function table.

Implementations

impl Amx

pub fn new(ptr: *mut AMX, fn_table: usize) -> Amx

Builds the wrapper.

ptr is the pointer received in callbacks such as AmxLoad; fn_table is the address resolved during plugin initialization (typically stored in a global AtomicUsize read in Load() from crate::consts::ServerData::AmxExports).

pub fn register(&self, natives: &[AMX_NATIVE_INFO]) -> Result<(), AmxError>

Registers plugin natives in the VM via amx_Register.

Generally called in AmxLoad — the #[native] macro + initialize_plugin! build the list automatically; only call manually from raw code.

Errors

Propagates any AmxError returned by amx_Register — typically AmxError::NotFound if a listed native is not declared in the script, or VM state errors if called outside the load cycle.

pub fn exec(&self, index: AmxExecIdx) -> Result<i32, AmxError>

Executes the public function identified by index in the VM.

Returns the Pawn return value (i32). Arguments must have been pushed via push (in reverse order) and Allocator (for strings/arrays) before this call.

Errors

Propagates any AmxError from script execution — notably Exit/Assert (Pawn aborted), StackError/StackLow/HeapLow (stack or heap overflow), Divide, Native (a called native returned an error) or Index if index does not match a valid function.

pub fn find_native(&self, name: &str) -> Result<i32, AmxError>

Index of a native by name (resolved via amx_FindNative).

Errors

AmxError::NotFound if name contains an interior NUL byte or if the native is not registered in the VM.

pub fn call_native(&self, name: &str, params: &[i32]) -> Result<i32, AmxError>

Calls a native registered by another plugin in the same AMX.

SA-MP plugins inject their natives into every loaded AMX via amx_Register, which writes a host function pointer into the native’s entry inside the AMX_HEADER natives table. This helper resolves the name through amx_FindNative, reads that function pointer back, builds the params block in the AMX convention (first cell = argc * sizeof(cell), then the arguments), and invokes the native.

Integer arguments are passed as their i32 value. Floats are passed bit-cast to i32 (use f32::to_bits then i32::from_ne_bytes on to_ne_bytes, or f32::to_bits() as i32). String and array arguments are AMX cell addresses returned by Allocator::allot_string/Allocator::allot_buffer — same marshalling as for exec_public.

Example

// Calling Streamer_CreateDynamicObject from a Rust plugin
fn on_amx_load(&mut self, amx: &Amx) -> AmxResult<()> {
    let model_id: i32 = 1337;
    #[allow(clippy::cast_possible_wrap)]
    let x = 100.0_f32.to_bits() as i32;
    let y = 200.0_f32.to_bits() as i32;
    let z =  10.0_f32.to_bits() as i32;
    let object_id = amx.call_native(
        "Streamer_CreateDynamicObject",
        &[model_id, x, y, z, 0, 0, 0],
    )?;
    log::info!("created dynamic object id={object_id}");
    Ok(())
}

Errors

• AmxError::NotFound if name contains an interior NUL byte, the native is not registered, or its address is still zero (registered name but no host pointer attached).
• AmxError::MemoryAccess if the AMX header cannot be read.
• AmxError::Index if the resolved index is out of range for the natives table reported by the AMX header.
• Any AmxError propagated from the called native via amx.error (re-raised by the caller through amx_try!).

pub fn find_public(&self, name: &str) -> Result<AmxExecIdx, AmxError>

Index of a public function by name — pass the result to exec.

use samp_sdk::amx::Amx;
use samp_sdk::error::AmxResult;
fn has_on_player_connect(amx: &Amx) -> AmxResult<bool> {
    let idx = amx.find_public("OnPlayerConnect")?;
    Ok(i32::from(idx) >= 0)
}

Errors

AmxError::NotFound if name contains an interior NUL byte or if the public function is not declared in the Pawn script.

pub fn find_pubvar<T>(&self, name: &str) -> Result<Ref<'_, T>, AmxError>

where T: AmxPrimitive,

Ref<T> pointing to a public variable declared in the Pawn script.

let version = amx.find_pubvar::<f32>("my_plugin_version")?;
// outdated
if *version < 1.0 { }

Errors

AmxError::NotFound if name contains an interior NUL byte or if the pubvar is not declared. AmxError::MemoryAccess if the address returned by the VM is invalid.

pub fn flags(&self) -> Result<AmxFlags, AmxError>

Flags of the loaded .amx.

Errors

Propagates any AmxError returned by amx_Flags — in practice, it only fails if the internal AMX* is corrupted or null.

pub fn get_ref<T>(&self, address: i32) -> Result<Ref<'_, T>, AmxError>

where T: AmxPrimitive,

Resolves an AMX cell (relative address) to a typed Ref<T>.

Errors

AmxError::MemoryAccess if address does not correspond to a valid cell in the Pawn script address space.

pub fn push<'a, T>(&'a self, value: T) -> Result<(), AmxError>

where T: AmxCell<'a>,

Pushes an AmxCell value onto the VM stack. Use in reverse order of the public function’s arguments before calling exec.

Errors

Propagates any AmxError from amx_Push — typically AmxError::StackError/StackLow if the stack is full.

pub fn strlen(&self, value: *const i32) -> Result<usize, AmxError>

Length in characters of an AMX string at address value.

Errors

AmxError::MemoryAccess if value does not point to valid memory in the script space. Other AmxError are propagated from amx_StrLen.

pub fn allocator(&self) -> Allocator<'_>

Creates an Allocator bound to this Amx.

All memory allocated via Allocator::allot/Allocator::allot_buffer/ Allocator::allot_string is released automatically when the Allocator goes out of scope (Drop). Keep it alive while using the returned references.

pub fn amx(&self) -> Option<NonNull<AMX>>

Raw pointer to the AMX (non-null) or None if constructed with null.

pub fn header(&self) -> Option<NonNull<AMX_HEADER>>

Raw pointer to the AMX_HEADER of the loaded .amx.

pub fn cip(&self) -> Option<u32>

Current instruction pointer (cip) — a code-segment offset in a debug hook. Read as u32.

pub fn frame(&self) -> Option<i32>

Current frame pointer (frm); local/argument symbols are addressed relative to it.

pub fn stack(&self) -> Option<i32>

Current stack pointer (stk).

pub fn heap(&self) -> Option<i32>

Current heap pointer (hea).

pub fn stp(&self) -> Option<i32>

Top of the stack (stp) — the upper bound of the data address space.

pub fn read_cell(&self, addr: i32) -> Option<i32>

Reads a 32-bit cell from the data segment at addr, validating bounds like amx_GetAddr. Returns None if the address is inaccessible.

Reads byte-wise (no alignment assumption). Usable from a debug hook.

pub fn write_cell(&self, addr: i32, value: i32) -> bool

Writes a 32-bit cell to the data segment at addr, validating bounds like amx_GetAddr. Returns false if the address is inaccessible.

Writes byte-wise (no alignment assumption). Usable from a debug hook to edit a variable while the VM is paused.

pub fn install_debug_hook(&self, cb: extern "C" fn(*mut AMX) -> i32)

Installs a debug hook callback into this VM (amx->debug = cb), the equivalent of amx_SetDebugHook. The VM then calls cb on every line, provided the .amx was compiled with -d2/-d3.

The callback runs on the VM thread and crosses the FFI boundary, so it must never unwind (no panics).

pub fn remove_debug_hook(&self)

Removes a previously installed debug hook, restoring amx->debug to a no-op callback that returns AMX_ERR_NONE.

Trait Implementations

impl AmxExt for Amx

fn ident(&self) -> AmxIdent

Opaque identity of the Amx — useful for maps and cross references.

impl Debug for Amx

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.