Installing Amxmodx

This guide explains how to install and configure AMX Mod X on a GoldSrc Half-Life Dedicated Server. AMX Mod X runs through Metamod and allows you to add additional features, administration commands and server plugins without having to modify the game itself.

It can be used with Half-Life and many other GoldSrc games and mods, including Counter-Strike, Team Fortress Classic, Day of Defeat, Natural Selection and Opposing Force.

Choosing a Version of AMX Mod X

There are several versions of AMX Mod X available. For this guide I am using version 1.8.2, although newer builds are also available if you need support for more recent plugins or features.

• AMX Mod X 1.8.2 is the stable version used by a large number of existing GoldSrc servers and plugins.
• AMX Mod X 1.9 is a newer branch with additional changes and improvements.
• AMX Mod X 1.10 is the development branch and may be required by some newer plugins.

For most older plugins, version 1.8.2 will usually be sufficient. If a particular plugin requires a newer version, this will normally be mentioned by the plugin author.

Step 1: Download AMX Mod X

Download the AMX Mod X Base package from the official website. If you are installing it for another GoldSrc game such as Counter-Strike, Team Fortress Classic or Day of Defeat, you should also download the appropriate addon package for that game.

Extract the files into the folder for the game or mod you are running. For standard Half-Life this will normally be the valve folder.

Once extracted, you should have the following directory:

valve/addons/amxmodx

If you are installing AMX Mod X for another game, replace valve with the appropriate game folder, such as cstrike or tfc.

Step 2: Add AMX Mod X to Metamod

AMX Mod X is loaded as a Metamod plugin, so the next step is to tell Metamod where to find it.

Open the following file:

addons/metamod/plugins.ini

If plugins.ini does not already exist, you can create it using a normal text editor.

On Windows, add:

win32 addons/amxmodx/dlls/amxmodx_mm.dll

On Linux, add:

linux addons/amxmodx/dlls/amxmodx_mm_i386.so

Linux file and folder names are case sensitive, so make sure the path and filenames match exactly.

Step 3: Check the Installation

Restart the server once the files are in place and the Metamod configuration has been updated.

Open the server console and enter:

meta list

If everything has been installed correctly, AMX Mod X should appear in the list of Metamod plugins.

You can also check the AMX Mod X version directly with:

amxx version

If AMX Mod X responds with its version information, the installation is working.

Understanding the AMX Mod X Folders

Before adding plugins, it is worth becoming familiar with the main AMX Mod X folders. Once you understand what each folder is used for, managing the server becomes much easier.

addons/amxmodx/
    configs/
    data/
    dlls/
    logs/
    modules/
    plugins/
    scripting/

The configs folder contains most of the AMX Mod X configuration files. This includes administrator accounts, plugin lists and general settings.

The plugins folder contains compiled AMX Mod X plugins using the .amxx file extension.

The scripting folder contains the AMX Mod X compiler and plugin source files. Source files use the .sma extension.

The logs folder contains AMX Mod X log files and can be particularly useful when trying to work out why a plugin has failed to load or produced an error.

The modules and dlls folders contain the libraries used internally by AMX Mod X and its modules. These will normally already be in place after installation.

Setting Yourself as an Administrator

Once AMX Mod X is running, one of the first things you will probably want to do is give yourself administrator access.

Administrator accounts are configured in:

addons/amxmodx/configs/users.ini

For an internet server, using your Steam ID is generally the simplest option. A typical entry looks like this:

"STEAM_0:0:123456" "" "abcdefghijklmnopqrstu" "ce"

Replace STEAM_0:0:123456 with your own Steam ID.

The third section contains the administrator access flags. In the example above, all standard AMX Mod X administrator permissions are enabled.

The final section contains the account flags. The c flag tells AMX Mod X that the account should be matched using a Steam ID, while e means that no password is required.

After changing users.ini, change the map or restart the server and reconnect. You should then have the appropriate AMX Mod X administrator access.

Configuring AMX Mod X

The main AMX Mod X configuration file is:

addons/amxmodx/configs/amxx.cfg

This file contains general AMX Mod X settings and is also a useful place to add configuration values required by plugins.

Many plugins provide their own CVARs which control how they behave. These might change things such as whether a feature is enabled, how often something happens or which players are allowed to use it.

For example, a plugin might provide a setting similar to:

example_plugin_enabled 1

The actual CVARs will depend on the plugin, so always check the instructions supplied by the plugin author.

Some plugins also use their own configuration files inside:

addons/amxmodx/configs

If a plugin includes a separate configuration file, it is usually best to keep its settings there rather than adding everything to amxx.cfg.

Map Specific Configuration

AMX Mod X can also load settings for individual maps. This is useful if you want a particular CVAR or plugin setting to change only when a certain map is running.

Map configuration files are normally stored inside:

addons/amxmodx/configs/maps

For example, settings that should only be used on crossfire can be placed in:

addons/amxmodx/configs/maps/crossfire.cfg

This can be useful for changing server settings, disabling a feature or adjusting a plugin for a particular map without changing the main configuration for every map on the server.

Installing AMX Mod X Plugins

Once AMX Mod X is running, you can start adding plugins to the server. Compiled AMX Mod X plugins use the .amxx file extension.

Place the plugin inside:

addons/amxmodx/plugins

Next, open:

addons/amxmodx/configs/plugins.ini

Add the filename of the plugin on a new line. For example:

example.amxx

Save the file and change the map or restart the server. AMX Mod X should then attempt to load the plugin.

If you want to temporarily disable a plugin without deleting it, place a semicolon at the beginning of the line:

;example.amxx

This is useful if you are testing several plugins or trying to identify which plugin is causing a problem.

Compiling AMX Mod X Plugins

Some AMX Mod X plugins are distributed as .sma source files rather than compiled .amxx files. These need to be compiled before the server can load them.

Place the .sma source file inside:

addons/amxmodx/scripting

On Windows you can use the compiler supplied with AMX Mod X. The easiest option is normally to run:

compile.exe

On Linux you can use the AMX Mod X compiler directly:

./amxxpc example.sma

After a successful compilation, the finished .amxx file will normally be placed inside:

addons/amxmodx/scripting/compiled

Move the compiled file into:

addons/amxmodx/plugins

Then add the plugin filename to addons/amxmodx/configs/plugins.ini.

Include Files

Some plugin source files depend on additional include files. These use the .inc file extension and provide functions or definitions required by the source code.

Include files belong inside:

addons/amxmodx/scripting/include

If a plugin author supplies one or more .inc files, copy them into this folder before compiling the plugin.

A missing include file is one of the most common reasons a downloaded source plugin will fail to compile. You may see an error similar to:

fatal error 100: cannot read from file: "example"

This usually means the compiler cannot find an include file required by the plugin. Check the source code and the files supplied by the plugin author to see what is missing.

Compiler Errors and Warnings

If compilation fails, the compiler will normally display the line number and an explanation of the problem.

Errors prevent the plugin from compiling and will need to be corrected before an .amxx file can be produced.

Warnings are slightly different. A plugin may still compile when warnings are present, but they are worth checking as they can indicate mistakes or older code that may not behave as expected.

If you are compiling somebody else’s plugin and receive errors, make sure you are using the AMX Mod X version expected by the plugin and that all required include files are installed.

Checking Your Plugins

AMX Mod X provides several useful console commands for checking that everything is working.

To list the AMX Mod X plugins currently loaded, use:

amxx plugins

This will show the current status of each plugin. If a plugin has failed to load, it should usually be obvious from this list.

To see which AMX Mod X modules are currently loaded, use:

amxx modules

This can be useful because some plugins depend on a particular AMX Mod X module being available.

Checking the Logs

If a plugin will not load or produces an error while the server is running, the AMX Mod X logs are one of the first places I would check.

They are normally stored inside:

addons/amxmodx/logs

The log files can contain plugin errors, runtime errors and other useful information which may not be immediately obvious from the server console.

If a plugin reports an error, the log will often include the plugin name, the source line involved and a description of what went wrong.

Restarting After Changes

You do not always need to completely restart HLDS after changing an AMX Mod X configuration or installing a plugin.

In many cases, changing the map is enough for AMX Mod X to reload its plugins and configuration files. If you have changed Metamod itself, replaced an AMX Mod X library or made a more substantial change, a full server restart is the safer option.

Troubleshooting

If AMX Mod X does not appear when you run meta list, check that Metamod itself is working correctly first. You can confirm this by running:

meta version

If Metamod is running but AMX Mod X is not loading, check the entry in addons/metamod/plugins.ini and make sure the AMX Mod X library exists in the correct folder.

If an individual plugin will not load, check that the .amxx file is inside the plugins folder and that its filename has been entered correctly in addons/amxmodx/configs/plugins.ini.

If a compiled plugin shows as a bad load, check the server console and the AMX Mod X logs. It may depend on a module that is not available or may have been compiled for a different version of AMX Mod X.

If a source plugin will not compile, check the compiler output carefully. Missing include files, incorrect AMX Mod X versions and errors in the source code are the most common causes.

Where To Go Next

Once AMX Mod X is installed and configured, you have the foundation for adding all sorts of additional features to your server. This can be anything from simple administration commands and map voting through to completely new gameplay systems.

If you are experimenting with AMX Mod X development, the next step is usually learning how the .sma source files work, modifying existing plugins and eventually writing your own using Pawn.

I would also recommend keeping a copy of your working configs, plugins and scripting folders before making major changes. It makes life considerably easier if you install something that causes problems and need to return the server to a known working setup.