Pawn API

For use in Pawn, YALP exports the majority the Lua C API, adapted in some places to Pawn. Since most of the functions behave exactly like the original ones, it is better to read the Lua Reference Manual, or the include file. Only the functions which differ from the originals are listed in this section.

Since handling errors between Pawn and Lua code is tricky, you should only use these functions to create and destroy a Lua instance, and provide Pawn functions which cannot be ported to Lua. Public and native functions are usable from pure Lua as well (via the interop package). Pawn code operating with Lua should take care of handling all error situations and managing the validity of the Lua instance.

native Lua:lua_newstate(lua_lib:load=lua_baselibs, lua_lib:preload=lua_newlibs, memlimit=-1);

Creates a new Lua instance, specifying optionally the base packages that should be loaded, and other packages that are available via require. memlimit (kilobytes) may be specified as well to specify the maximum memory capacity of the Lua instance (allocations past the limit will fail).

The result of this function is a Lua handle, or Lua:0 on failure.

native lua_load(Lua:L, const reader[], data, bufsize=-1, chunkname[]="");

Repeatedly calls a Pawn function (whose name is in reader) to load a Lua chunk. YALP allocates a buffer of size bufsize on the heap and passes it to the function. The public function should have this signature:

forward lua_reader(Lua:L, buffer[], data, size);

data is not used by YALP and only serves as an additional parameter to the function, and size is the size of the allocated buffer in cells. YALP will repeatedly call the function and expects it to provide pieces of a Lua chunk via buffer. Since a chunk can be stored in both binary and textual form, buffer should contain raw bytes of the chunk and not a string. The function can return a positive integer, indicating the size of the provided chunk in bytes, or 0, indicating the end of the chunk. If the function returns a negative integer, it represents the negated size of the final piece of the chunk (so the function will not be called again).

The resulting chunk is parsed and pushed on the stack as a Lua function.

native lua_stackdump(Lua:L, depth=-1);

Prints depth elements from the Lua stack (top to bottom), useful for debug.

native lua_tostring(Lua:L, idx, buffer[], size=sizeof(buffer));

Obtains the textual representation of a Lua value at idx on the stack. If it is not a number or a string, it calls tostring first on it.

native lua_pushpfunction(Lua:L, const f[]);

Pushes a function to the Lua stack with its implementation in a public function whose name is passed in f. When the function is called from Lua, the public function is found and executed. The function should have the following signature:

forward lua_pfunction(Lua:L);

Creating this function is similar to the C API. All passed arguments are present on the stack and must be marshalled via the API to Pawn values. The function should return an integer specifying the number of return values from the top of the stack that are returned.

stock lua_loadfile(Lua:L, const name[], bufsize=-1)
stock lua_dofile(Lua:L, const name[], bufsize=-1)

Opens a file (via fopen) and loads it as a Lua chunk, and (in case of lua_dofile) executes it. Returns the error code if an error occured during parsing or executing the chunk, or 0 in case of no errors.

native lua_bind(Lua:L);

If a function is on top of the Lua stack, and the interop module has not been loaded yet, calling this function terminates the execution of the Pawn script and reroutes all AMX calls to the Lua instance. Its lifetime will be bound to the original Pawn program (filterscript or gamemode), which will be blocked from executing any other code.

This function makes it possible to run Lua code as a gamemode, and is useful if you want to decrease the number of used filterscripts (since the interop package must create a new one for it to work properly).