SA-MP Forums

SA-MP Forums (
-   Plugin Development (
-   -   [Plugin] Yet Another Lua Plugin (

IllidanS4 26/10/2018 02:06 PM

Yet Another Lua Plugin

This plugin allows you to use Lua, your favourite dynamic flexible scripting language, in SA-MP, for all purposes, be it sandboxing user scripts, debugging the server, or developing filterscripts and gamemodes. YALP provides lightweight and flexible Lua environment that can use existing or future natives from SA-MP or plugins.

The main feature of YALP is a powerful interop API to interact with existing Pawn natives and callbacks. It is very easy to call existing functions, without needing to declare them anywhere:

interop.native.SetPlayerPos(0, 1235.31, -2331.84, 12.33)
YALP automatically converts all arguments to their proper Pawn cells, and allows you to specify what the function returns in the actuall call. All standard cell and single-dimensional array types are supported.

Callbacks can be specified in a similar simple way:

function interop.public.OnPlayerConnect(playerid)
  -- ...

Thanks to these mechanisms, you can use any framework you want, or build your own in Lua, without depending on new versions of this plugin.

There is no special XML, JSON or other configuration of this plugin, because you can specify everything when you create a new Lua state (you can create any number you wish, and run any code inside). You can specify what packages should be loaded or available in the Lua instance, how much maximum memory it should take, or even limit for how long Lua functions can run.

All standard Lua packages are available (although some of the more unsafe ones aren't allowed by default). The powerful interop package can interface with any Pawn native function or callback. There is also an advanced timer library with support for simple asynchronous functions (with Lua coroutines) and all sorts of timers. The remote package contains functions for remote communication between two separate Lua instance (via serialization or proxies).

The standard Lua packages are also enhanced with a couple of useful functions. Please see the wiki for a list of all new functions.

The Pawn API is basically a port of the Lua C API, allowing advanced manipulation of the Lua machine. It is recommended to use the Lua API, since it can do everything that Pawn can do, but if you need to interact with an existing complex Pawn library, it is possible as well.

Sample code
pawn Code:
#include <a_samp>
#include <YALP>

public OnFilterScriptInit()
    new Lua:l = lua_newstate(); // creates a new Lua instance
    if(lua_loadfile(l, "script.lua")) // loads a Lua script and returns an error code
        lua_stackdump(l); // prints the stack for more information about the error
    lua_bind(l); // binds the Lua instance to the current Pawn filterscript/gamemode, so all interation with it is rerouted to Lua
    // if the binding succeeds, this code is not run (and the Lua instance is destroyed if the script is unloaded)

-- script.lua
local interop = require "interop"
interop.native.print("Hello from Lua!")

IllidanS4 26/10/2018 02:09 PM

Re: Yet Another Lua Plugin
YALP v0.2 released!
  • New base functions: argcheck, optcheck, map, concat, exit.
  • New interop functions: tagname, cellmin, cellmax.
  • New debug function: numresults.
  • New timer functions: sleep, wait, waitticks.
  • New coroutine function: resumehooked.
  • interop changes: sequence tables will be marshalled as arrays (modifications are copied back after the call). heapalloc has a new parameter specifying whether to zero the memory. varargs is renamed to struct.
  • timer changes: parallelreg renamed to parallelex, order of arguments changed. Default count value was decreased to 256 from 100000.
  • package changes: require looks into the "scriptfiles/lua" directory for Lua packages and into the "plugins/lua" for C packages. require is also present even if the package module isn't loaded.
  • Tail-calling a C function will preserve the number of expected return values.
  • Functions that stored upvalue lists will now allow storing more than 255 upvalues.
  • Pawn native functions check the number of arguments.
  • Plugin version is reported in the YALP_VERSION global variable.

IllidanS4 16/11/2018 11:43 PM

Re: Yet Another Lua Plugin
YALP v0.3 released!
  • Pawn functions for controlling the Lua machine check the number of arguments.
  • exit function in the base package. It terminates any code that executes in the Lua machine and prevents any other code from running there, then deletes the machine as soon as possible.
  • Lua files can be passed into Pawn native functions. Every call creates a new copy of the original file handle (but with the same offset and access rights), which gets closed after the function is called.
  • interop.asfile and interop.asnewfile to convert Pawn File handles to Lua files. Both function create a copy of the file handle, but the first one deletes the original one as well, so it should be only used for functions which are meant to open files (without storing the result anywhere else).

lepegadore 19/11/2018 06:03 PM

Re: Yet Another Lua Plugin
Is it possible to write an entire Gamemode (including MySQL, Streamer, some LUA anticheat etc) with this? And
I wonder if there are too much speed difference handling a big gamemode with many players (No premature optimization).

Also there is a Lua Mysql package? can you post some simple example? same with Streamer.

Thanks for the Plugin.

IllidanS4 19/11/2018 07:35 PM

Re: Yet Another Lua Plugin

Originally Posted by lepegadore (Post 4066517)
Is it possible to write an entire Gamemode (including MySQL, Streamer, some LUA anticheat etc) with this? And
I wonder if there are too much speed difference handling a big gamemode with many players (No premature optimization).

Also there is a Lua Mysql package? can you post some simple example? same with Streamer.

Thanks for the Plugin.

Writing a gamemode is definitely possible with this plugin. In fact, you can replace OnFilterScriptInit with OnGameModeInit in the sample code above, and it will work like a normal gamemode.

Standard Lua packages can be easily used from your code, just use "scriptfiles/lua/*.lua" for Lua packages, and "plugins/lua/*.dll" for C packages, and the require function will load them automatically as usual.

Any SA-MP plugin can also be used, be it streamer, MySQL or something else. Native functions from all plugins are available in the interop.native table, and can be called without any prior definitions. For more information, please see the wiki.

narwn 20/11/2018 03:39 AM

Re: Yet Another Lua Plugin
thread single/multi?

IllidanS4 20/11/2018 11:06 AM

Re: Yet Another Lua Plugin

Originally Posted by narwn (Post 4066625)
thread single/multi?

I assume you inquire about the multithreading capabilities of the plugin. Since Lua is singlethreaded (like Pawn), and the server API is not thread-safe, there is no special way to execute Lua code in a different process thread. The only way is to use a plugin that offers multithreading (like PawnPlus) and invoke Lua code from a new thread (but note that some YALP packages are not thread-safe as well).

However, you can use Lua coroutines freely, and there are functions like async and timer.wait that help you run asynchronous code.

There is also timer.parallel which can execute any piece of Lua code, but pauses it after a given number of instructions, and resumes it on the next tick. If you want to execute a piece of code that can take a long time but without blocking the server (and without any corruption caused by calling thread-unsafe functions), you can use this function.

That being said, I do have an idea how to implement multi-threading in Lua, with the use of the already existing remote package. Nevertheless, I have not found a proper use case for this, and it would be fairly limited anyway (but 100 % thread-safe).

IllidanS4 28/12/2018 05:42 PM

Re: Yet Another Lua Plugin
YALP v0.4 released!
  • File marshalling for natives must be done explicitly, via interop.tofile and interop.closefile (to close the handle). This simplifies the native call code, and allows to control whether you want to destroy the file handle or not.
  • Increased performance when calling natives. interop.getnative also now has a fast parameter that can increase the performance a little bit more when passing arguments to the native, but at the cost of potential incompatibility with some functions (that manipulate the stack).
  • The COD pointer was not set correctly for fake AMX instances, causing an assertion error on Linux.

IllidanS4 07/02/2019 11:08 PM

Re: Yet Another Lua Plugin
YALP v0.5 released!
  • Minor fixes in file marshalling. lua_loadstream introduced to load a chunk from File, so other functions no longer have to read the code in Pawn.
  • Push-based parser usage. lua_loader initializes the parser, lua_write is used to provide pieces of the code to it.
  • Many constants ported from the Lua API into Pawn. Results and arguments of functions are now properly tagged.
  • lua_pushuserdata, lua_getuserdata, lua_setuserdata to copy cells to Lua userdata objects.

Bolex_ 08/02/2019 04:03 PM

Re: Yet Another Lua Plugin

All times are GMT. The time now is 04:12 PM.

Powered by vBulletin® Version 3.8.6
Copyright ©2000 - 2019, Jelsoft Enterprises Ltd.