search

multitheftauto / amx

MTA AMX compatibility layer.
zlib License
31 stars 8 forks source link
multi-theft-auto sa-mp

readme

amx - MTA AMX compatibility layer

Introduction

amx is a software package that allows the execution of unmodified San Andreas: Multiplayer 0.3.7 gamemodes, filterscripts and plugins on Multi Theft Auto: San Andreas 1.5.8 and higher servers. It is open source, and a prebuilt binary for Windows is available for testing purposes right now.

License

amx is free and open source. You are allowed to use and modify it free of charge in any way you please.

You are allowed to redistribute (modified) versions of amx, provided that you:

Compatibility

Compatibility is quite high:

See Limitations for a list of features that are currently missing.

Extra features

Apart from being compatible, amx also offers a number of extra features:

Installation

amx consists of a binary server module (.dll/.so) and a Lua resource. It will only run on MTA:SA 1.0 and later. Installation steps are lined out below.

Extracting

Extract the "mods" folder into your MTA "server" directory.

Configuration

Migrating gamemodes, filterscripts, plugins from an SA-MP server

If you have an SA-MP server with a number of modes and scripts that you would like to host on your MTA server, you can easily migrate these with an automated tool. For Windows, a graphical click-through wizard is provided: amxdeploy.exe (.NET Framework 2.0 required). For Linux there is an interactive Perl script: amxdeploy.pl. Simply run the tool appropriate for your operating system and follow the instructions. The tool will:

Special note for Linux users infamiliar with Perl

amxdeploy.pl uses some modules that are not part of a standard Perl installation. These are:

If you don't have these yet, you need to install them before you can run the script. To do this, open a terminal, switch to root and start cpan. If this is the first time you start cpan, it will walk you through some configuration (selection of download mirrors etc.). After it's set up, type install <modname> for each module to download and install it, for example: install XML::Twig.

Once the modules are installed you should be able to run the script without problems: perl amxdeploy.pl.

Maintenance of your MTA server

The migration tool is mainly meant for moving over files from an SA-MP server to a fresh amx install. To add SA-MP content to your MTA server at a later point, you probably want to take the manual route. Information about this is lined out below.

Finishing up

Running gamemodes and filterscripts

Before you can run sa-mp modes or filterscripts, you need to start the amx resource. Type this command in the server console or as admin in the ingame console:

start amx

Alternatively you can add it to the autostart list of your server, in mtaserver.conf. Once amx is started you can use the following commands to start and stop gamemodes and filterscripts:

start amx-name
stop amx-name
start amx-fs-name
stop amx-fs-name

Alternatively, you can use the SA-MP style changemode and (un)loadfs commands. At most one gamemode can be running at any time, the number of running filterscripts is unlimited.

Go ahead and try starting the example gamemode (amx-test) and filterscript (amx-fs-test).

New Pawn scripting functions

Here follows a quick reference for the new Pawn native functions amx introduces. To use them, #include <a_amx> in Pawno.

AddPlayerClothes

native AddPlayerClothes ( playerid, type, index );

Applies the specified clothing to a player. See the clothes page for a list of valid type and index ID's. Note: this function only has a visible effect on players with the CJ skin.

GetPlayerClothes

native GetPlayerClothes ( playerid, type );

Returns the clothes index of the specified type which the player is currently wearing. See the clothes page for a list of valid type and index ID's. Note: the returned value is only relevant for players with the CJ skin.

RemovePlayerClothes

native RemovePlayerClothes ( playerid, type );

Removes the specified clothing from a player. See the clothes page for a list of valid type ID's. Note: this function only has a visible effect on players with the CJ skin.

ShowPlayerMarker

native ShowPlayerMarker ( playerid, show );

Shows or hides the blip of one specific player.

GetVehicleVelocity

native GetVehicleVelocity ( vehicleid, &Float:vx, &Float:vy, &Float:vz );

Returns the velocity of a vehicle along the x, y and z axes. No more manual speed calculation with timers.

SetVehicleVelocity

native SetVehicleVelocity ( vehicleid, Float:vx, Float:vy, Float:vz );

Sets the velocity of a vehicle. Make it jump or suddenly come to a halt.

SetVehicleModel

native SetVehicleModel ( vehicleid, model )

Changes the model of a vehicle; more practical than destroying and recreating it.

lua

native lua ( const fnName[], {Float,_}:... );

Calls a Lua function. The function must be defined in a .lua file in the same resource as the calling .amx, and must have been registered earlier with amxRegisterLuaPrototypes. See also Pawn-Lua interaction.

Example:

new playerid = lua("luaTestfn1", 1.3, "Test string");

amxRegisterPawnPrototypes

native amxRegisterPawnPrototypes ( const prototype[][] );

Registers prototypes for public functions that can be subsequently called from Lua scripts with pawn. The prototype list must be terminated with an empty string. See also Pawn-Lua interaction.

This example code registers two functions. The first one takes a float and a string argument and returns a player ID, the second takes a player ID and returns nothing:

new prototypes[][] = {
    "p:pawnTestfn1", { "f", "s" },
    "pawnTestfn2", { "p" },
    ""
};
amxRegisterPawnPrototypes(prototypes);

amxVersion

native amxVersion ( &Float:ver );

Retrieves the amx version as a floating point number, e.g. 1.3.

amxVersionString

native amxVersionString ( buffer[], size );

Retrieves the complete amx version string.

New Lua scripting functions

A number of new Lua functions were also introduced.

pawn

variant pawn ( string fnName, ... )

Calls a Pawn function. The function must be public, must be defined in an .amx file in the same resource as the calling .lua, and must have been registered earlier with amxRegisterPawnPrototypes.

Example:

local player = pawn('pawnTestfn1', 0.5, 'Test string')

amxIsPluginLoaded

bool amxIsPluginLoaded ( string pluginName )

Checks if a specific SA-MP server plugin is currently loaded. pluginName is the name of the plugin without a file extension.

amxRegisterLuaPrototypes

bool amxRegisterLuaPrototypes ( table prototypes )

Registers prototypes of Lua functions that can subsequently be called from a Pawn script with lua. See also Pawn-Lua interaction.

The following example code registers two functions - the first one takes a float and a string argument and returns a player element, the second takes a player element and returns nothing:

amxRegisterLuaPrototypes(
    {
        ['p:luaTestfn1'] = { 'f', 's' },
        ['luaTestfn2']   = { 'p' }
    }
)

amxVersion

float amxVersion ( )

Returns the amx version as a floating point number, for example 1.3.

amxVersionString

string amxVersionString ( )

Returns the complete amx version string.

New MTA events

amx also provides events for detecting when .amx files are loaded and unloaded.

onAMXStart

onAMXStart ( resource res, string amxName )

Triggered when an .amx file has just finished loading and initializing. The source of this event is the root element of the resource containing the .amx file. res is the resource pointer to this resource. amxName is the name of the .amx file minus the extension.

You should only call pawn after this event has triggered; if you call it in the main body of a Lua script, .amx files won't have registered their functions yet.

onAMXStop

onAMXStop ( resource res, string amxName )

Triggered when an .amx file was unloaded. The source of this event is the root element of the resource containing the .amx file. res is the resource pointer to this resource. amxName is the name of the .amx file minus the extension.

Pawn-Lua interaction

amx allows developers to enrich their gamemodes and other scripts with Lua code, which is easier and more efficient to write than Pawn. To make this possible, a new Pawn function, lua was added to call Lua functions, and a Lua function called pawn correspondingly calls public Pawn functions.

A resource that uses the interaction functions will contain both one or more .amx files (<amx/> in meta.xml) and serverside MTA scripts (<script/>). Both Pawn and Lua scripts can only call other-language scripts that are in the same resource.

Registering prototypes

Before you can call a function with lua or pawn you need to define its prototype, which consists of the types of its arguments and return value. Each type corresponds to a single letter:

Letter Type
b boolean
i integer
f floating point
s string
p player
v vehicle
o object
u pickup

Pawn functions are registered with amxRegisterPawnPrototypes, Lua functions with amxRegisterLuaPrototypes. Both functions associate a number of function names with their argument types and (optionally) return type. To specify a return type, prepend the function name with the type letter followed by a colon (:), for example: f:testfn. If you do not specify a return type (i.e. only specify the name, testfn), "i" will be assumed.

See the syntax sections of the two registration functions for the precise syntax to use.

Calling other-language functions

Use lua to call a Lua function from Pawn, and pawn to call a Pawn function from Lua. The functions have the same syntax: a string containing the name of the function, followed by the arguments to the function. amx takes care of any necessary argument and return value conversions: for example an .amx vehicle ID passed to lua will arrive in the Lua function as an MTA vehicle element, and vice versa (provided the correct prototype was registered for the Lua function).

Passing arguments by reference

It is possible to pass arguments by-reference from Pawn to Lua - however this is not possible in the opposite direction.

To make an argument be passed by reference, modifications in both the Lua function's prototype and body are necessary. In the prototype, prepend the type letter with a &. In the function's code, write _[argname] instead of argname for reading and writing the argument (argname holds the memory address in the .amx of the argument).

Cross-language calling limitations

Some limitations apply to cross-language calling.

Example

This example code demonstrates registering prototypes and calling other-language functions, with arguments passed by value and by reference.

test.pwn ```pawn #include #include main() { new prototypes[][] = { "p:testfn", { "p", "f", "s" }, "" }; amxRegisterPawnPrototypes(prototypes); } public testfn(playerid, Float:f, str[]) { printf("pawn> testfn: %d %.1f %s", playerid, f, str); return playerid; } public OnGameModeInit() { new vehicleid = CreateVehicle(415, 0.0, 0.0, 3.0, -90.0, 0, 1, 5000); new vehicletype = 0; // vehicletype is passed by reference new success = lua("getVehicleType", vehicleid, vehicletype, "Test text from Pawn"); if(success) printf("pawn> Vehicle type: %d", vehicletype); SetGameModeText("Blank Script"); AddPlayerClass(0, 1958.3783, 1343.1572, 15.3746, 269.1425, 0, 0, 0, 0, 0, 0); return 1; } public OnPlayerRequestClass(playerid, classid) { SetPlayerPos(playerid, 1958.3783, 1343.1572, 15.3746); SetPlayerCameraPos(playerid, 1958.3783, 1343.1572, 15.3746); SetPlayerCameraLookAt(playerid, 1958.3783, 1343.1572, 15.3746); return 1; } ```
test.lua ```lua function getVehicleType(vehicle, pVehicleType, str) print('lua> ' .. str) print('lua> ' .. _[pVehicleType]) local model = getElementModel(vehicle) if model then _[pVehicleType] = model return true else return false end end addEventHandler('onAMXStart', root, function() -- Note that we are calling pawn() from the onAMXStart event instead of -- in the main script body. Calling it from the main body would fail as -- the Pawn functions have not yet been registered at that point. local player = pawn('testfn', getRandomPlayer(), 0.8, 'Test string from Lua') if player then print('lua> ' .. getClientName(player)) else print('lua> No random player') end end ) amxRegisterLuaPrototypes({ ['b:getVehicleType'] = { 'v', '&i', 's' } }) ```
Sample output of this code ``` lua> Test text from Pawn lua> 0 pawn> Vehicle type: 415 pawn> testfn: 1 0.8 Test string from Lua lua> arc_ ```

Limitations

Even though amx offers a high level of compatibility, not everything is perfect. Below is a list of limitations that may or may not be addressed in later versions of amx and Multi Theft Auto.

Credits

amx was developed by arc_. Special thanks go out to: