-
Notifications
You must be signed in to change notification settings - Fork 19
AMX natives
native Amx:amx_this();Returns the pointer to the current AMX machine that executes the script. This can be used to compare known AMX instances or call remote functions, but note that there is no guarantee that the pointer will remain valid for the duration of the server. If an AMX instance is destroyed and another one is created, there is a chance it will acquire the pointer of the old one. Use amx_handle if you want to ensure the instance is valid.
native Handle:amx_handle();Creates a handle object that contains the value of amx_this() that becomes dead when the AMX instance is unloaded.
native Amx:amx_source();When called in a native hook, returns the pointer to the AMX instance that called the hooked native. Returns Amx:0 if no hooks are active.
native Handle:amx_source_handle();Creates a handle object with the value of amx_source() that becomes dead when the AMX instance is unloaded. Returns HANDLE_NULL if no hooks are active.
native amx_name(name[], size=sizeof(name));
native String:amx_name_s();Returns the name of the script, is available.
native amx_call_native(Amx:amx, const function[], const format[], AnyTag:...);Calls a native function from the scope of a specific AMX instance. See pawn_call_native for more information. amx can be a value returned from amx_this(), amx_source(), AMX_ALL (meaning the function should be called in all loaded AMX instance), or AMX_OTHERS (all but not the current one).
native amx_call_public(Amx:amx, const function[], const format[], AnyTag:...);Calls a public function from the scope of a specific AMX instance. See amx_call_native or pawn_call_public for more information.
native amx_err:amx_try_call_native(Amx:amx, const function[], &result, const format[], AnyTag:...);Calls a native function from the scope of a specific AMX instance but suppresses all errors. See amx_call_native or pawn_try_call_native for more information.
native amx_err:amx_try_call_native_msg(Amx:amx, const function[], &result, msg[], msg_size=sizeof(msg), const format[]="", AnyTag:...);
native amx_err:amx_try_call_native_msg_s(Amx:amx, const function[], &result, &StringTag:msg, const format[], AnyTag:...);Calls a native function from the scope of a specific AMX instance but suppresses all errors. The error message is returned in msg. See amx_call_native or pawn_try_call_native_msg for more information.
native amx_err:amx_try_call_public(Amx:amx, const function[], &result, const format[], AnyTag:...);Calls a native function from the scope of a specific AMX instance but suppresses all errors. See amx_call_native or pawn_try_call_public for more information.
native amx_name_length();Returns the maximum length of any name defined in the current script.
native amx_num_publics();Returns the number of public functions in the current script.
native amx_public_index(const function[]);Finds a public function by its name. Returns an index ranging from 0 to amx_num_publics() - 1, or -1 if no function was found.
native amx_public_name(index, name[], size=sizeof(name));
native String:amx_public_name_s(index);Returns the name of a public function specified by its index.
native [2]amx_encode_public(index);Returns a packed string that stores a public function index. This string can be used as an argument to call functions that accept a function name, bypassing name lookup. Any characters may be appended to the string without affecting its recognition.
native [2]amx_encode_public_name(const function[]);Finds a public function by its name and returns a packed string that encodes its index. See amx_encode_public.
native [3]amx_encode_value_public(index, AnyTag:value);Like amx_encode_public, but appends an integer value to the encoded string. Use amx_try_decode_value to decode it.
native [3]amx_encode_value_public_name(const function[], AnyTag:value);Like amx_encode_public_name, but appends an integer value to the encoded string. Use amx_try_decode_value to decode it.
native amx_public_addr(index);Returns the code address of a public function represented by its index.
native amx_public_at(code=cellmin);Attempts to find a public function that contains the code represented by address code (the current position in the code by default). Returns the index of the function or -1 if not found.
If the code isn't currently executing a public function, this function may return incorrect results.
native amx_num_natives();Returns the number of native functions imported (i.e. used) by the current script.
native amx_native_index(const function[]);Returns the index of a native function imported in the current script, or -1 if no function was found.
native amx_native_name(index, name[], size=sizeof(name));
native String:amx_native_name_s(index);Returns the name of a native function specified by its index.
native [2]amx_encode_native(index);Encodes a native function specified by its index so that it is usable in all cases where a native function name is expected. See amx_encode_public. Any characters may be appended to the string without affecting its recognition.
native [2]amx_encode_native_name(const function[]);Encodes a native function specified by its name so that it is usable in all cases where a native function name is expected. See amx_encode_public_name.
native [3]amx_encode_value_native(index, AnyTag:value);Like amx_encode_native, but appends an integer value to the encoded string. Use amx_try_decode_value to decode it.
native [3]amx_encode_value_native_name(const function[], AnyTag:value);Like amx_encode_native_name, but appends an integer value to the encoded string. Use amx_try_decode_value to decode it.
native amx_encoded_length();Returns the length of the string produced by amx_encode_public and amx_encode_native. This is 6 currently (a signature character and 5 bytes to store the integer).
native bool:amx_try_decode_value(const encoded[], &AnyTag:value);Attempts to decode the value stored in a string produced by amx_encode_value_public or amx_encode_value_native. The tag of the value is not preserved. Returns true on success.
The value itself is stored in a 5-character string in "base" 255 (not 256 because the null character cannot be used). The first character is the most significant one, and also stores the original value modulo 127.
stock amx_yield(val=0)This function terminates the execution of the current script, returning a value from its entry point public function. Compared to task_yield, it exists immediately, and the following code will never be executed.
This function must be in Pawn, because it uses #emit halt 0 which cannot be reproduced from a plugin.
native amx_error(amx_err:code, result=0);Causes the AMX machine to exit in an error state.
native bool:amx_tailcall();When called in a nested call, replaces the parent stack frame with the current stack frame. This means that returning from the current function will skip the caller function and return to the one that called the caller function instead.
This function can help with recursive calls. When you ensure that return func(...); is the only way func is called, no by-ref arguments point to local variables in the to-be-removed stack frame, and no heap manipulation was done (i.e. no temporary by-ref variables), you can call amx_tailcall at the top of func to remove the parent stack frame.
This function returns true if the stack frame was successfully removed (i.e. this is not a top-level public function). Executing while(amx_tailcall()){} and then returning is functionally equivalent to calling amx_yield.
native amx_parallel_begin(count=1);If the script is compiled with debugging information (the BREAK opcode), this function registers a debug handler that, when called, effectively calls wait_ticks(1), scheduling the execution of the script on the next tick. count specifies how many BREAK instructions should be processed before pausing the script. This function is used by the amx_parallel macro.
native amx_parallel_end();Ends the effect of amx_parallel_begin.
native Var:amx_var(&AnyTag:var);Returns a reference to a variable in the script. It can be used in other scripts to access local data.
native Var:amx_var_arr(AnyTag:arr[], size=sizeof(arr));Returns a reference to an array variable in the script.
native Var:amx_public_var(AMX:amx, const name[]);Returns a reference to a public variable in the script.
native bool:amx_valid(Var:var);Returns true if a given variable reference object is valid. However, the variable itself may not be (see amx_linked and amx_inside).
native bool:amx_delete(Var:var);Deletes a variable reference. Must be used to free the object.
native bool:amx_linked(Var:var);Returns true if the variable reference points to a valid AMX instance.
native bool:amx_inside(Var:var);Returns true if the variable reference points to a valid memory range in an AMX instance (i.e. its value may be changed).
native Var:amx_alloc(size, bool:zero=true);Allocates space on the AMX heap and returns a variable reference to it. The allocated space will be available for the duration of the current function, but must be freed when no longer.
native bool:amx_free(Var:var);Frees the heap memory associated with the variable reference. The variable object will not be deleted.
native amx_set(Var:var, AnyTag:value, index=0);Sets the value of a variable at a given index.
native amx_get(Var:var, index=0);Returns the value of a variable at a given index.
native amx_sizeof(Var:var);Returns the size of a given variable.
native bool:amx_my(Var:var);Returns true if the variable reference points to this AMX instance.
native amx_to_ref(Var:var, ref[1][]);If the variable reference points to this AMX instance, modifies the indirection table of ref to point to the variable. ref[0] will be indexable and point directly to the variable.
native bool:amx_fork(fork_level:level=fork_machine, &result=0, bool:use_data=true, &amx_err:error=amx_err:0);The default behaviour of this function is to clone the current AMX machine and run the new copy starting from the code that follows the function call. In the forked AMX machine, this function returns true. Once the execution of the script exits, the returned value is passed to result and the execution continues from the original call in the original AMX machine, the function returning false. Aside from exiting the standard way, amx_yield and amx_commit may be used to exit from the code. If the forked code exists via an error, you can use the error parameter to obtain the error code.
The lifetime of the new AMX machine is temporary, ending as soon as no code runs in it or there are no references to it. It is possible to extend it by using a threaded block, in which case the execution is restored when a thread is detached, but the machine is not destroyed. This way, a true multithreaded environment can be created with each thread having its own isolated memory. Task-based functions can also be used to extend the lifetime of the fork.
It is possible to use this function without creating a new AMX machine, by setting the level parameter to fork_exec or fork_data. In this case, the state (registers, stack+heap in case of fork_data) of the original AMX machine is saved before executing the following code, and restored after that. It may help to work with plugin functions which expect to be notified of a new AMX before using their natives, but it decreases isolation and prevents the features the function has when used in combination with threaded code.
If the caller doesn't intend to use the static data of the script, use_data can be set to false. For fork_machine, the new AMX machine will not be updated with the latest static data of the original machine (and amx_commit will not restore it), or for fork_data or less, the function will not attempt to protect the static variables from the effects of the forked code.
Creating a forked block can be done by using the amx_forked pseudo-statement. After it, a block of code is expected, which will be entered by calling amx_fork using the arguments of the statement. At the end of the block, amx_fork_end is called to exit the block. In the block, you can call amx_yield to exit it, but using amx_commit there is not recommended. Returning from the block will automatically end it as well.
native amx_commit(bool:context=true);This function can be only used from a forked AMX machine. It destroys the fork and copies all its state back to the original AMX machine, provided it is still waiting for its termination. If context is false, it will destroy the current context instead of the original one.
native amx_fork_end();This function is used automatically by the amx_forked statement to end it. If used in a non-forked code, it will only print a warning to the log, unlike amx_yield, which will terminate the script.
native AmxGuard:amx_guard(AnyTag:value, tag_id=tagof(value));Creates a new AMX guard for a specific resource. The guard is deleted when the AMX instance in which it was created is unloaded.
native AmxGuard:amx_guard_arr(AnyTag:value[], size=sizeof(value), tag_id=tagof(value));Creates a new guard for an array of resources (passed by value). Semantics akin to amx_guard.
native bool:amx_guard_valid(AmxGuard:guard);Returns true if the guard is valid, or false otherwise.
native amx_guard_free(AmxGuard:guard);Deletes the guard and frees the resource.