is4code / yalp

Yet Another Lua Plugin for SA-MP

YALP v1.1

YALP, short for Yet Another Lua Plugin, aims to be a simple yet extendable SA-MP plugin allowing to use Lua for SA-MP server programming.

Compared to older Lua plugins, YALP doesn't export any of the SA-MP natives or callbacks directly. Instead, it exposes a set of functions to interact with the server via a virtual filterscript, mimicking calls to AMX functions. The actual server API can be ported entirely with Lua, which removes the need to update the plugin for new versions of SA-MP and maintain all functions, and also allows the use of other plugins.

Installation

Download the latest release for your platform to the "plugins" directory and add "YALP" (or "YALP.so" on Linux) to the plugins line in server.cfg.

Include YALP.inc to create and control Lua machines on-the-fly.

Building

Use Visual Studio to build the project on Windows, or make on Linux.

Example

local interop = require "interop"
local native = interop.native

local commands = {}

function commands.lua(playerid, params)
  -- no need to import native functions, simply call them! 
  native.SendClientMessage(playerid, -1, "Hello from Lua!")
  return true
end

function commands.setpos(playerid, params)
  -- even a function from any plugin can be used
  local fail, x, y, z = interop.vacall(native.sscanf, interop.asboolean, params, "fff")(0.0, 0.0, 0.0)
  -- return values can be easily specified
  if fail then
    return native.SendClientMessage(playerid, -1, "Wrong arguments!")
  end
  native.SetPlayerPos(playerid, x, y, z)
  return true
end

function interop.public.OnPlayerCommandText(playerid, cmdtext)
  -- properly convert values to Lua (YALP cannot determine their types)
  playerid = interop.asinteger(playerid)
  cmdtext = interop.asstring(cmdtext)
  
  -- take advantage of everything Lua has to offer
  local ret
  cmdtext:gsub("^/([^ ]+) ?(.*)$", function(cmd, params)
    local handler = commands[string.lower(cmd)]
    if handler then
      ret = handler(playerid, params)
    end
  end)
  return ret
end

Credits

• Zeex for creating subhook, the backbone of this plugin.
• The creators of Lua.

yalp's Issues

open.mp compatibility

#include <open.mp>
#include <YALP>

main()
{
    return;
}

new Lua:l;

public OnGameModeInit()
{
    print("Test");
    new File:scriptfile = fopen("main.lua", io_read);
    l = lua_newstate();
    if(lua_load(l, "ScriptReader", _:scriptfile, flength(scriptfile) char) || !lua_bind(l))
    {
        lua_stackdump(l);
        lua_close(l);
    }
    return 1;
}

forward ScriptReader(Lua:L, buffer[], File:file, size);
public ScriptReader(Lua:L, buffer[], File:file, size)
{
    new length = flength(file);
    new read = fblockread(file, buffer, length * 8 / cellbits);
    buffer[read] =
        ((fgetchar(file, false) & 0xFF)) |
        ((fgetchar(file, false) & 0xFF) << 8) |
        ((fgetchar(file, false) & 0xFF) << 16);
    fclose(file);
    return -length;
}

do return "test" end

local interop = require "interop"

local public = interop.public
local SendClientMessage, SetPlayerHealth
import(interop.native) -- assigns SendClientMessage and SetPlayerHealth from interop.native.SendClientMessage and interop.native.SetPlayerHealth

local COLOR_WHITE = 0xFFFFFFFF

local function tofloat(num) -- when calling native functions with a float parameter, a float value must be ensured
    return 0.0 + num
end

function public.OnPlayerConnect(playerid) -- adding a function to the "public" table automatically registers the callback (based on the name)
    SendClientMessage(playerid, COLOR_WHITE, "Hello from Lua!") -- calling a native function requires almost no modifications
end

local commands = {}

function commands.hp(playerid, params)
    local hp = tonumber(params)
    if not hp then
        return SendClientMessage(playerid, COLOR_WHITE, "Usage: /hp [value]")
      end
      SetPlayerHealth(playerid, tofloat(hp))
      SendClientMessage(playerid, COLOR_WHITE, "Your health was set to "..hp.."!")
      return true
end

function public.OnPlayerCommandText(playerid, cmdtext)
      playerid = interop.asinteger(playerid) -- YALP cannot guess the type of the arguments, so they must be explicitly converted
      cmdtext = interop.asstring(cmdtext)
  
      local ret
      cmdtext:gsub("^/([^ ]+) ?(.*)$", function(cmd, params)
        local handler = commands[string.lower(cmd)]
        if handler then
              ret = handler(playerid, params)
        end
      end)
      return ret
end

print("Lua script initialized!")

[2023-10-06T02:45:44+0200] [Info] Loading plugin: YALP
[2023-10-06T02:45:44+0200] [Info] YALP v1.1 loaded
[2023-10-06T02:45:44+0200] [Info] Created by IllidanS4
[2023-10-06T02:45:44+0200] [Info] Test
[2023-10-06T02:45:44+0200] [Error] (sleep mode)