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.6 and higher servers. It is open source, and a prebuilt binary for Windows is available for testing purposes right now.

• License
• Compatibility
• Extra features
• Installation
• Running gamemodes and filterscripts
• New scripting features
• New Pawn scripting functions
• New Lua scripting functions
• New MTA events
• Pawn-Lua interaction
• Limitations
• Author and thanks

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:

• do not charge for them,
• keep the original credits and licence intact,
• clearly list any modifications you made, and
• do not present them as an official version.

Compatibility

Compatibility is quite high:

• Almost all SA-MP scripting functions and callbacks are implemented.
• Database functions (db_*) are implemented.
• HTTP function is implemented and properly works with HTTPS requests.
• SA-MP server plugins work unmodified, if they don't use memory hacking.
• SA-MP style rcon commands are available from the server console and the ingame console.

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:

• New scripting features (include a_amx.inc to use these):

  • CJ clothes
  • Walking style
  • Player stats
  • Vehicle variants
  • Garages
  • Traffic light state
  • Control state
  • Glitches

• In addition to the new native functions, gamemodes run in amx can also call Lua functions. Lua scripts can in turn call public Pawn functions.

  Using Lua not only gives you access to the wide range of MTA functions that offer a lot of functionality that SA-MP doesn't have, but also allows you to write code in a much more comfortable and efficient fashion than Pawn. For example, while Pawn is a subset of C and requires you to create a temporary buffer and call one or more functions to concatenate strings, you can simply do str1 = str2 .. str3 in Lua.

• You can load plugins dynamically, while the server is running. Use the loadplugin console command for this.

• There is no hard-coded max filterscript count, the number of running filterscripts is unlimited.

Installation

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

Extracting

• All needed binary files are in the archive provided on releases page. Unpack amx.zip and extract the mods folder into your MTA server directory.

• amx folder located in mods/deathmatch/resources is a place for the mentioned Lua resources. It will be empty at this moment, so you need to copy all the latest files of amx folder from this repository into your amx folder.

Configuration

• Open server/mods/deathmatch/mtaserver.conf in a text editor. Add the following line within the <config> node:

  <module src="king.dll"/>
  

  (Use "king.so" on Linux systems). This will instruct the MTA server to load the module on startup.

• At this point you can add the amx resource to the autostart list if you want. Doing this will allow you to use SA-MP style rcon commands in the server console as soon as the server is started.

  <resource src="amx" startup="1" protected="0"/>
  

  Save and close mtaserver.conf.

• After starting the MTA server you should see the following output:

  Resource ‘amx’ requests some acl rights. Use the command ‘aclrequest list amx’

  Run aclrequest list amx to see what ACL rights are needed, and if you are happy with the request, type aclrequest allow amx all.

  The following rights are used for the following purposes:

  • general.ModifyOtherObjects:
    • to access files of amx-* resources
  • function.startResource
function.stopResource
function.restartResource:
    • to automatically (re)start filterscripts when amx starts
    • for rcon
  • function.getServerPassword
function.setServerPassword:
    • for rcon

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:

• install the selected SA-MP gamemodes and filterscripts as MTA resources,
• copy the selected plugins to MTA,
• copy all scriptfiles to MTA,
• set up the MTA mapcycler resource according to the gamemode cycling configuration in SA-MP's server.cfg, and
• set up the autostart filterscripts and plugins according to SA-MP's server.cfg.

Special note for Linux users infamiliar with Perl

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

• File::Copy::Recursive
• XML::Twig

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.

• In SA-MP, there is one folder that contains all gamemodes and another that contains all filterscripts. In MTA, it is the convention to create a separate resource (i.e. folder) for each gamemode. amx follows the MTA convention for better integration, which means that a resource needs to be created for each gamemode and filterscript. The naming convention for these is amx-name for gamemodes and amx-fs-name for filterscripts.

  So, to add a new gamemode or filterscript, you create a folder in server/mods/deathmatch/resources/, place one or more .amx files in it, and add an appropriate meta.xml. Additionally you need to copy all the content from your scriptfiles folder in server/mods/deathmatch/resources/amx/scriptfiles.

  The meta.xml files of gamemodes and filterscripts are slightly different. Two resources, amx-test and amx-fs-test, are included in the amx repository as examples. Most times you can simply copy-paste these to a new resource and adjust the names in it.

• To specify what filterscripts to autostart when amx loads, open server/mods/deathmatch/resources/amx/meta.xml and edit the "filterscripts" setting. Its value is a list of filterscript names separated by spaces. For example:

  <setting name="filterscripts" value="adminspec vactions"/>
  

  This will start the resources amx-fs-adminspec and amx-fs-vactions.

• Plugins go in server/mods/deathmatch/resources/amx/plugins. Additionally you need to specify what plugins to load when amx starts: open server/mods/deathmatch/resources/amx/meta.xml and edit the "plugins" setting. Its value consists of the names of the plugins to start, separated by spaces. For example:

  <setting name="plugins" value="crashdetect mysql"/>
  

  This will load crashdetect.dll and mysql.dll on Windows, or .so on Linux.

• jbeta's mapcycler resource (shipped with the MTA server) is used for automatic map cycling. The cycling is configured in server/mods/deathmatch/resources/mapcycler/mapcycle.xml. For each gamemode, add a line like this:

  <game mode="amx" map="amx-name" rounds="1"/>
  

  By default, the gamemodes are run in the order in which they appear in the list; you can also opt to randomly select the next mode from the list by setting the type attribute of the root <cycle> node to "shuffle".

  Automatic cycling will only happen when the mapcycler resource is started. You can start it manually (start mapcycler) or add it to the autostart list of your server (mtaserver.conf). If mapcycler is not started, amx will let players vote on the next mode instead.

Finishing up

• If you are planning to compile Pawn scripts that use the new native functions provided by amx, place a_amx.inc in your Pawno "include" directory.

• You are done!

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 st