AlliedModders Wiki - User contributions [en]

Optimizing Plugins (AMX Mod X Scripting)

2017-08-30T21:30:43Z

Kristi:

{{LanguageSwitch}}

==Introduction==
[[Admin-Mod]] and [[AMX Mod X]] became very popular because of their easy to use scripting language. However, the words "scripting language" come with a lot of loaded preconceptions. Most people assume that because it's scripted:
*You can't possibly make it any faster
*It's pre-compiled, so it's already quite fast
*Details don't matter, as it's only "scripting" anyway

Especially, with [[Pawn]] (formerly Small), none of these are true. The compiler, in fact, is very poor at optimizing, and you can '''greatly''' increase the speed and efficiency of your plugins by keeping a few rules in mind. Remember - it's more important to minimize instructions than it is to minimize lines of code.

===Terms===
To read this document, you will need to understand a few concepts beforehand:
*<tt>BRANCHING</tt> - When the processor takes a different path of code. For example, to call a function or to use an if statement, the processor will "branch". Modern processors attempt to predict pathways with "branch prediction", but it's best to avoid branching a lot if possible.
*<tt>STACK ALLOCATION</tt> - In Pawn, all local data is stored on the stack, a big chunk of continuous memory. Whenever you create a variable on the stack, it is automatically written with zeroes.
*<tt>HEAP ALLOCATION</tt> - In Pawn, temporary data that needs to be referenced by a native is stored on the heap, another area of contiguous, but less restrictive memory.
*<tt>DATA SECTION</tt> - This is an area of memory built into your .amxx file. In fact, it "becomes" the heap at load time. All your strings and arrays are hardcoded into this area.
*<tt>EXPENSIVENESS</tt> - To be "expensive" in computer science means an operation requires a lot of CPU processing. It usually does not refer to memory size, only to processing cycles and time. Addition is inexpensive, floating power operations are expensive. However, both are inexpensive in comparison to writing a file. An inexpensive operation can also be called "cheap".
*<tt>BIG-OH NOTATION</tt> - O(*) notation refers to the expensiveness of an algorithm. If something is O(n), it occurs in linear time -- meaning that for N items, it will complete relative to N. O(N^2) means with N items, it will complete relative to N^2. O(1) means "constant time" - no matter what N is, it will run in the same amount of time.

==Compiler Optimizations==
These optimizations have to do with changing how your code is compiled. While the syntax may remain the same, you are not only increasing compile time, but increasing your plugin's efficiency and speed at run time.

===Always Save Results===
Observe the example code snippet below:
<pawn>if (get_user_team(player) == TEAM_T)
{
//...code
} else if (get_user_team(player) == TEAM_CT) {
//...code
} else if (get_user_team(player) == TEAM_SPECTATOR) {
//...code
}</pawn>
This is a mild example of "cache your results". When the compiler generates assembly for this code, it will (in pseudo code) generate:
<pre>
CALL get_user_team
COMPARE+BRANCH
CALL get_user_team
COMPARE+BRANCH
CALL get_user_team
COMPARE+BRANCH
</pre>
Notice the problem? We have called <tt>get_user_team</tt> an extra two times than necessary. The result doesn't change, so we can save it. Observe:
<pawn>new team = get_user_team(player)
if (team == TEAM_T)
{
//...code
} else if (team == TEAM_CT) {
//...code
} else if (team == TEAM_SPECTATOR) {
//...code
}</pawn>
Now, the compiler will only generate this:
<pre>
CALL get_user_team
COMPARE+BRANCH
COMPARE+BRANCH
COMPARE+BRANCH
</pre>
If <tt>get_user_team</tt> were an expensive operation (it's relatively cheap), we would have recalculated the entire result each branch of the <tt>if</tt> case.

===Switch instead of If===
If you can, you should use <tt>switch</tt> cases instead of <tt>if</tt>. This is because for an if statement, the compiler must branch to each consecutive <tt>if</tt> case. Using the example from above, observe the switch version:
<pawn>new team = get_user_team(player)
switch (team)
{
case TEAM_T:
//code...
case TEAM_CT:
//code...
case TEAM_SPECTATOR:
//code...
}</pawn>
This will generate what's called a "case table". Rather than worm through displaced <tt>if</tt> tests, the compiler generates a table of possible values, which the virtual machine knows to browse through:
<pre>
CALL get_user_team
COMPARE
COMPARE
COMPARE
</pre>

===Don't Re-index Arrays===
A common practice in Small is to "save space" by re-indexing arrays. There are a few myths behind this, such as saving memory, assuming the compiler does it for you, or readability. Fact: none of these are true. Observe the code below:
<pawn>new players[32], num, team
get_players(players, num, "h")
for (new i=0; i<num; i++)
{
team = get_user_team(players[i])
set_user_frags(players[i], 0)
}</pawn>
For this, the compiler generates code similar to:
<pre>
:LOOP_BEGIN
LOAD i
LOAD players
CALC
LOAD players[i]
CALL get_user_team
LOAD i
LOAD players
CALC
LOAD players[i]
CALL set_user_frags
</pre>
See what happened? The compiler does not cache array indexing. Because we've used <tt>players[i]</tt> each time, every instance generates 4-6 (or more) instructions which load <tt>i</tt>, the address of <tt>players</tt>, computes the final location, and then grabs the data out of memory. It is much faster to do:
<pawn>new player
for (new i=0; i<num; i++)
{
player = players[i]
team = get_user_team(player)
set_user_frags(player, 0)
}</pawn>
Not only is this more readable, but look at how much cruft we've shaved off the compiler's generated code:
<pre>
:LOOP_BEGIN
LOAD i
LOAD players
CALC
LOAD players[i]
STORE player
CALL get_user_team
LOAD player
CALL set_user_frags
</pre>
In a large loop you can drastically reduce codesize in this manner.

===Global vs Local and Variables in Loops===
It is important to realize that every variable in [[Pawn]] is automatically zeroed. For global variables, they are static and permanent, thus they are zeroed when your plugin is loaded. Variables in functions, however, must be zeroed dynamically. This is a slow and tedious operation, and you should not only avoid relying on it when necessary, but you should keep that fact in mind when using arrays.

[[Arrays]] in [[Pawn]] are "cells" of data. Each cell is four or eight bytes, depending on whether your processor is 32bit or 64bit. To create an array of 4096 cells, for example:
<pawn>new array[4096]</pawn>
The compiler generates code to manually zero every single one of the 16,384 bytes in that location. Normally, this isn't too bad -- but it can be absolutely deadly in a function which is called quite often. For example, <tt>server_frame</tt> is called on every [[server tick]] in [[AMX Mod X]]. To declare an array of that size in <tt>server_frame</tt> is highly unnecessary. Instead, you can take advantage of the fact that not only are globals free of charge, but <tt>server_frame</tt> does not need to be re-entrant. That is, you will never call <tt>server_frame</tt> inside of <tt>server_frame</tt>, so making the variable global will not bring up the problem of one instance of the function overwriting data from another instance of the same function. Observe:
<pawn>new g_serverframe_array[4096]
public server_frame()
{
//...code that uses g_serverframe_array
}</pawn>
This will execute conseridably faster. You can do this with smaller arrays too.

Likewise, it is equally important to avoid declaring arrays inside of loops. Consider the following block of code:
<pawn>for (new i=0; i<num; i++)
{
new message[255], name[32], player
player = players[i]
get_user_name(player, name, 31)
format(message, 254, "Hello, %s", name)
}</pawn>
If there are 32 players, this loop will actually resize and zero out over 1K of memory thirty two times in a row. Not good! However, on the other hand, it's nice that the message is zeroed out for us each time. <tt>Tip:</tt> you often only need to zero out the first character of a string. This will make the entire string empty. The code below is much more efficient:
<pawn>new message[255], name[32], player
for (new i=0; i<num; i++)
{
player = players[i]
name[0] = '^0'
message[0] = '^0'
get_user_name(player, name, 31)
format(message, 254, "Hello, %s", name)
}</pawn>
This has the effect of safely making the string empty beforehand, as well as largely reducing a lot of run-time overhead.

===Static vs Global===
An alternative to global variables is static variables, which are internally the same but easier to work with for programming.

A variable declared with the keyword "static" instead of "new" operates in the same way a global does (it is created only once) but the variable is local to the function; this means the code is much easier to read, while drastically improving speed just like a global variable. Example:
<pawn>stock SomeBigFunction()
{
static gaben[255];
format(gaben, "%L", LANG_SERVER, "STUFF");
}</pawn>

This has the same effect as declaring <tt>gaben</tt> as global, except only <tt>SomeBigFunction</tt> can use it.

{{qnotice|Be careful of re-entrancy!}}
When a variable is static, it has the same re-entrancy problems of a global variable. That means, if your function might be called recursively, or twice in the same stack frame, you should not use static variables. This is most often the case for API provided to other plugins or helper functions. Triggered events are usually never called twice on the same execution chain.

===Constant variables===
You can declare a variable "constant" by adding the "const" keyword before the variable name:

<pawn>new const AMX_GABEN[] = "amx_gaben"</pawn>

What this does is prevents the variable from being changed; essentially, you've locked the variable to a certain value. In this way, a constant can offer a type safe method of simplifying code, unlike a define, which is not type safe.

In addition, constant variables are often optimized out, resulting in quicker and smaller code.

===For Loop Comparisons===
A common mistake is to write code like this:
<pawn>new string[256] = "something long"
for (new i=0; i<strlen(string); i++)
//...code</pawn>
This plays off a similar principle from before: cache results. The compiler will actually recompute your string length on each iteration of the loop. This will have even worse effects if your string changes mid-loop. A more sensible method is:
<pawn>new string[256] = "something long"
new len = strlen(string)
for (new i=0; i<len; i++)
//...code</pawn>

==Tips and Tricks==
===Lookup Tables===
Precompute what can be precomputed. For example, say you have a mapping of weapon indices to names:
<pawn>if (weapon == CSW_AK47)
copy(name, len, "weapon_ak47")</pawn>
Ignoring the fact that we have <tt>get_weapon_name</tt> in [[AMX Mod X]], this is inefficient. We could precompute this result in a table:
<pawn>new g_WeaponNamesTable[TOTAL_WEAPONS][] = {
//..0 to CSW_AK47-1
"weapon_ak47",
//..CSW_AK47+1 to TOTAL_WEAPONS-1
};</pawn>

===Perfect Hashing===
:TODO: explain this

===Local Strings===
The [[Pawn]] compiler does not optimize the DATA section, which stores all hardcoded strings and global arrays. If you reference the same hardcoded string 500 times in your plugin, it will appear 500 different times. If this seems bad enough, it actually does this with all strings. For example, the empty string ("") appears everywhere in the include files, usually used as a default parameter to many natives. This too is copied into the data section for each unique reference.

For example:
<pawn>set_cvar_num("amx_gaben", get_cvar_num("amx_gaben") + 1)</pawn>
This will create two copies of "amx_gaben" in the DATA section. While this doesn't really hurt, it does increase the size of your plugin.

Similarly, this has the same problem:
<pawn>#define AMX_GABEN "amx_gaben"
set_cvar_num(AMX_GABEN, get_cvar_num(AMX_GABEN) + 1)</pawn>
The only way to avoid this mess is to use global variables. As stated earlier, they're basically free storage.
<pawn>new AMX_GABEN[] = "amx_gaben"
set_cvar_num(AMX_GABEN, get_cvar_num(AMX_GABEN) + 1)</pawn>

Again, while not necessary, this will reduce your plugin's size in memory and on disk. If you're already using defines, you can make this switch easily.

In order to prevent this from changing, you may want to declare it constant:

<pawn>new const AMX_GABEN[] = "amx_gaben"
set_cvar_num(AMX_GABEN, get_cvar_num(AMX_GABEN) + 1)</pawn>

Now it is a perfectly safe method of storage.

==Faster Natives==
AMX Mod X replaces many of the old AMX Mod natives with faster versions. Read below to discover them.

===Cvar Pointers===
As of AMX Mod X 1.70, you can cache "cvar pointers". These are direct accesses to cvars, rather than named access. This is a critical optimization which is dozens of times faster. For example:
<pawn>new g_enabled = register_cvar("csdm_enabled", "1")
//OR
new g_enabled = get_cvar_pointer("csdm_enabled")

stock SetCSDM(num)
set_pcvar_num(g_enabled, num)

stock GetCSDM()
return get_pcvar_num(g_enabled)
</pawn>
All of the cvar* functions (except for set_cvar_string) are mapped to [get|set]_pcvar_*. You can get a cached cvar pointer with get_cvar_pointer() or register_cvar().

===FormatEX===
As of AMX Mod X 1.70, there is an ultra high-speed version of format() called formatex(). It skips copy-back checking, unlike format(). formatex() cannot be used if a source input is the same as the output buffer. For example, these are invalid:
<pawn>new buffer[255]
formatex(buffer, charsmax(buffer), "%s", buffer);
formatex(buffer, charsmax(buffer), buffer);
formatex(buffer, charsmax(buffer), "%d %s", buffer[2]);</pawn>

It should be noted that format() will behave the same as formatex() if it detects that there will be no copy-back needed. However, formatex() does not check this, and thus is slightly faster for situations where the coder is sure of its usage.

===File Writing===
As of AMX Mod X 1.70, there are new natives for file writing. Read_file and write_file are O(n^2) functions for consecutive read/writes. fopen(), fgets(), fputs(), and fclose() are O(n) (or better) depending on how you use them.

[[Category:Scripting (AMX Mod X)]]

Button constants (AMX Mod X)

2017-08-30T20:56:45Z

Kristi: /* Constants */

{{LanguageSwitch}}

==Usage==
Button constants are generally used to determine when an entity is doing a certain action, such as jumping, attacking, or moving. This is used because +/- commands cannot be hooked by the HL engine (if they are made by the HL engine).

For example, this would work:
<pawn>register_concmd("+explode","explode");</pawn>

However this would not:
<pawn>register_concmd("+attack","hook_attack");</pawn>

==Constants==

A full list of constants can be found [http://amxmodx.org/api/hlsdk_const#pev-entity-pev-button-or-pev-entity-pev-oldbuttons-values/ here].

==Implementation==
If, for example, it is desired to check when a player is attacking, one would use the following:
<pawn>#include <amxmodx>
#include <engine>

public plugin_init()
{
register_plugin("Attack Test","1.0","Hawk552");
}

public client_PreThink(id)
{
if(entity_get_int(id,EV_INT_BUTTON) & IN_ATTACK)
{
// do something
}
}</pawn>

Notice how this uses the & operator, rather than the && operator. This is because a bit value is returned, and the & operator checks if a bit value is contained in another bit value.

To set an entity's button, the same type of idea can be implemented:
<pawn>#include <amxmodx>
#include <engine>

public plugin_init()
{
register_plugin("Attack Test","1.0","Hawk552");
}

public client_PreThink(id)
{
entity_set_int(id,EV_INT_button,IN_ATTACK);
}</pawn>

This sets the client's attack flag to ''on'' every time a frame is rendered.

To get an entity's buttons, and then ommit a certain button, one would use the following:
<pawn>#include <amxmodx>
#include <engine>

public plugin_init()
{
register_plugin("Attack Test","1.0","Hawk552");
}

public client_PreThink(id)
{
entity_set_int(id,EV_INT_button,entity_get_int(id,EV_INT_button) & ~IN_ATTACK);
}</pawn>

Say, for example, during a certain time, the client is jumping and attacking at the same time. In this case, the entity_get_int(id,EV_INT_button) function would return IN_ATTACK and IN_JUMP. Using the ~ operator removes the certain bit value, making it into merely IN_JUMP.

There are many more ways to use button constants, and not all must be used on players. They are simply more commonly implemented when dealing with players.

[[Category:Scripting (AMX Mod X)]]

HamSandwich General Usage (AMX Mod X)

2017-08-30T20:42:05Z

Kristi:

== About Ham Sandwich ==
Ham Sandwich is a module that provides additional hooking and function calling capabilities to [[AMX Mod X]].

Instead of hooking and executing Half-Life engine calls, like the modules FakeMeta and Engine do, this hooks and executes virtual function calls.

=== What is a virtual function? ===
A virtual function is a member function of a class in C++. In the case of Ham Sandwich, the virtual function would be a member function of a game entity. The virtual functions deal with various events in game, such as damage, and using entities.

Unlike normal member functions, virtual functions can be changed by class derivatives. For example, a typical hierarchy of entities in Half-Life game dlls look something like this:
CBaseEntity
CBaseAnimating
CBaseMonster
CZombie
CHeadCrab
CBarnacle
CBasePlayer
CBot

Now for example, if CBaseEntity has the virtual function called "FunctionA", and that function does nothing. But, CBarnacle also declares the function "FunctionA", and instead of doing nothing it causes the barnacle to die.

If something like this were to be executed:
CBaseEntity *ent=GET_PRIVATE(entity);
ent->FunctionA();

And the entity were a barnacle, the barnacle would die. If the entity was a zombie, nothing would happen.

=== What are some limitations? ===

Dealing with virtual functions have a couple minor drawbacks.
==== Custom Entities ====
Hooking virtual functions, such as TakeDamage, that get called on custom entities is a little bit awkward.

Because of the way where classes derive, and they get their own virtual table for each class, the type of class that the game dll allocates will be whatever gets hooked for a particular hook.

For example, say you have a plugin like this:
<pawn>
#include <amxmodx>
#include <fakemeta>
#include <hamsandwich>

new myStr;

public plugin_init()
{
myStr = engfunc( EngFunc_AllocString, "info_target" );

register_clcmd( "make_entity", "cmdMakeEntity" );

RegisterHam(Ham_TakeDamage, "MyEntityClass", "damageHook"); // Error!
}

public cmdMakeEntity( id )
{
new ent = engfunc( EngFunc_CreateEntity, myStr );
set_pev( ent, pev_classname, "MyEntityClass" );
// ...
}
</pawn>
That will not work, because the class "MyEntityClass" is not native to the gamedll. Instead, you would need to hook TakeDamage for "info_target", and do some form of parsing on the entities that get passed to it (such as checking classname), if you want to deal with custom entity hooking.

==== End of Chain Derivatives ====
The normal way virtual functions get called is by a virtual table that resides somewhere in the class. A magical index is assigned to each function, and then it looks up the function pointer inside of the virtual table, and executes the required function.

However, compilers are smart enough to optimize away the virtual function lookup if it knows two things about a call:
* The exact class type of the entity.
* That the entity is not derived any further.

An example would be using the hierarchy shown earlier. If, inside of <code>CBot::TakeDamage</code> a call to the virtual function <code>CBot::Killed</code> is made, most compilers will optimize the virtual function lookup out, so that <code>CBot::TakeDamage</code> would then directly call <code>CBot::Killed</code>. This means that the hook would never be called.

Fortunately, these instances are kind of rare.

==== Config File Requirements ====
Every hook and every <code>ExecuteHam()</code> call requires an entry for the function which the scripter is attempting to hook or execute. The function needs to be in the amxmodx/configs/hamdata.ini config file, under the game mod and operating system.

If a function that the script attempts to hook or call is not configured in the hamdata.ini file, then the module will cause the plugin to cease operation, as this is a fatal error.

The fatal errors can be filtered out by including a forward in the script called <code>HamFilter</code>. This is similar to native/module filters available inside of the core of amxmodx, whenever a fatal error occurs, it will pass along the parameters to <code>HamFilter</code>, and if <code>HamFilter</code> returns <code>PLUGIN_HANDLED</code>, the error will be ignored (but the attempted hook or execution will not take place). If the forward does not exist, or if it returns something other than <code>PLUGIN_HANDLED</code>, the plugin will fail.

An example layout for HamFilter:
<pawn>
public HamFilter(Ham:which, HamError:err, const reason[])
{
// Ignore an unconfigured ns_awardkill
if (which == Ham_NS_AwardKill && err == HAM_FUNC_NOT_CONFIGURED)
{
return PLUGIN_HANDLED;
}

// We absolutely need to be able to use cs_roundrespawn!
// If we can't, then the plugin cannot continue.
if (which == Ham_CS_RoundRespawn)
{
return 0;
}
}
</pawn>

Additionally, you can check to see if a function is valid to execute or hook by using the <code>IsHamValid()</code> native. The validity of a function is determined when the module is first loaded, and it will never change, so if you want to check it, there is no need to do so before every execute.

== Supported Mods ==
=== Mostly Supported ===
These mods have a very large list of functions that are usable in the module.
* Counter-Strike 1.6
* Condition Zero
* Day of Defeat
* Team Fortress Classic
* The Specialists
* Natural-Selection

=== Weakly Supported ===
Because these mods do not contain a Linux binary, they are much harder to disassemble.
* Sven-Coop
* Earth's Special Forces

== Hooking Functions ==
The big feature for Ham Sandwich is the ability to hook virtual functions.

=== Creating the Hook ===
Creating a hook is a lot like creating a hook in Fakemeta.

<pawn>
#include <amxmodx>
#include <hamsandwich>

public plugin_init()
{
RegisterHam(Ham_TakeDamage, "player", "player_hurt");
}

public player_hurt(this, inflictor, attacker, Float:damage, damagebits)
{
// Stuff...
}
</pawn>

This creates a basic hook which is called any time a player takes damage. Look in '''ham_const.inc''' for forward parameters for each hook.

Like Fakemeta, there is a hidden last parameter. Set it to 1 to do post hooking.

=== Blocking the Hook ===
Like Fakemeta and Engine, it is possible to stop a function from being called. This is called '''superceding'''.

Blocking in Ham Sandwich is identical to how it is accomplished in Fakemeta. In each hook, you return one of four special values:

* <code>HAM_IGNORED</code> - Nothing happened, the call continues.
* <code>HAM_HANDLED</code> - You did something, but the call continues.
* <code>HAM_OVERRIDE</code> - The call will still be executed, but instead you will change the return value.
* <code>HAM_SUPERCEDE</code> - The call is not executed, and you use your return value, if applicable.

You can use the native <code>GetHamReturnStatus()</code> to check the current return status of the hook.

=== Return Values ===
You can get or change the return values for all the hooks available in Ham Sandwich. Look in '''ham_const.inc''' for a list of all hooks and their return values.

These natives will get any ''modified'' return values.
<tt>
* native GetHamReturnInteger(&output);
* native GetHamReturnFloat(&Float:output);
* native GetHamReturnVector(Float:output[3]);
* native GetHamReturnEntity(&output);
* native GetHamReturnString(output[], size);
</tt>

These natives will get the ''original'' return value from the function.
Note that this is '''only''' valid to call in a post hook, it will be undefined to call it at any other time.
<tt>
* native GetOrigHamReturnInteger(&output);
* native GetOrigHamReturnFloat(&Float:output);
* native GetOrigHamReturnVector(Float:output[3]);
* native GetOrigHamReturnEntity(&output);
* native GetOrigHamReturnString(output[], size);
</tt>

These natives will change the return value to whatever you please.
Note that this will have no effect on the actual return value from the function '''unless''' the return status of the hook is <code>HAM_OVERRIDE</code> or <code>HAM_SUPERCEDE</code>.
<tt>
* native SetHamReturnInteger(value);
* native SetHamReturnFloat(Float:value);
* native SetHamReturnVector(const Float:value[3]);
* native SetHamReturnEntity(value);
* native SetHamReturnString(const value[]);
</tt>

=== Changing Hook Parameters ===
One feature available in Ham Sandwich that is not available in FakeMeta is the ability to change all parameters on the fly for each hook.

This means that, for example, if you wanted to make a plugin that halved all damage players take, you would do something like this:
<pawn>
#include <amxmodx>
#include <hamsandwich>

public plugin_init()
{
RegisterHam(Ham_TakeDamage, "player", "player_hurt");
}

public player_hurt(this, inflictor, attacker, Float:damage, damagebits)
{
// Player will now take half damage
SetHamParamFloat(4, damage / 2.0);
return HAM_HANDLED;
}
</pawn>

All hooks after the one you change them in will see the modified values. Hooks are executed in the order in which they are registered.

All available parameter changing natives are:
<tt>
* native SetHamParamInteger(which, value);
* native SetHamParamFloat(which, Float:value);
* native SetHamParamVector(which, const Float:value[3]);
* native SetHamParamEntity(which, value);
* native SetHamParamString(which, const output[]);
* native SetHamParamTraceResult(which, tr_handle);
</tt>

=== Disabling Hooks ===

Similar to how FakeMeta allows for unregistering of hooks with <code>unregister_forward()</code>, HamSandwich will allow you to disable and enable hooks whenever you want.

The <code>RegisterHam()</code> function will return a handle (tagged with <code>HamHook</code>). You can then make subsequent calls to <code>DisableHamForward()</code> and <code>EnableHamForward()</code> with the handle to stop it from forwarding, or enable its forwards again.

There is no way to completely unregister the hooks (until map change), as deleting a hook is a delicate process.

Building AMX Mod X

2017-08-30T19:27:19Z

Kristi:

AMX Mod X is a large project, but we've tried to make it as easy to build as possible. The directions here will step you through the entire process.

=Requirements=

==Windows==
<ol>
<li>Install Visual Studio or Visual C++ 2010 or higher. Express editions should work fine. If you use 2013 or higher, make sure to get the "Desktop" version: [http://www.visualstudio.com/downloads/download-visual-studio-vs#d-express-windows-desktop Visual Studio Express 2013 for Desktop].</li>
<li>Install [http://git-scm.com/ Git]. Make sure that you select the option that adds Git to PATH.</li>
<li>Next, you will need to start an environment capable of running Python and interacting with the Visual Studio compiler. There are two ways to do this.
<ul>
<li>Use [https://wiki.mozilla.org/MozillaBuild MozillaBuild]. MozillaBuild comes with Python, Mercurial, and a unix-like shell.
<ol>
<li>Install MozillaBuild.</li>
<li>Navigate to <tt>C:\mozilla-build</tt> and run the batch file corresponding to your Visual Studio version. For example, <tt>start-msvc10.bat</tt> for Visual Studio 2010 (10.0). Do not run an x64 version.</li>
<li>Add Git to MozillaBuild's <tt>PATH</tt>. The easiest way to do this is to enter the following commands:
<pre>
echo "export PATH=\$PATH:/c/Program\ Files\ $x86$/Git/bin" >> ~/.profile
source ~/.profile
</pre>
</li>
</ol>
</li>
<li>Or, you can manually set up a shell.
<ol>
<li>Install [https://www.mercurial-scm.org/ Mercurial].</li>
<li>Install [http://python.org/ Python] 2.7. It will install to C:\Python27 by default. (Version 3.4 will work, but is not recommended for compatibility with other tools).</li>
<li>Add Python to your <tt>PATH</tt> variable. Go to Control Panel, System, Advanced, Environment Variables. Add <tt>C:\Python27;C:\Python27\Scripts</tt> to <tt>PATH</tt> (or wherever your Python install is).</li>
<li>Under Start, Programs, Microsoft Visual Studio, select the "Visual Studio Tools" folder and run "Visual Studio Command Prompt". Alternately, open a normal command prompt and run <tt>"C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\vcvars.bat"</tt>. Substitute your Visual Studio version if needed.</li>
</ol>
</li>
</ul>
</ol>

Note that AMX Mod X also has Visual Studio project files. These can be used for local development, however, they are not maintained nor are they used for official builds.

==Linux==
<ol>
<li>Install Git, via either system packages or from the [http://git-scm.com/ Git] distribution.</li>
<li>Install either the GNU C Compiler or the Clang compiler. On Debian/Ubuntu, the following commands will give you everything:
<pre>
sudo apt-get install gcc g++ clang
</pre>
</li>
<li>If building on a 64-bit system, a few additional packages may be required. For example on Debian/Ubuntu they are:
<pre>
sudo apt-get install ia32-libs
sudo apt-get install lib32z1 lib32z1-dev
sudo apt-get install libc6-dev-i386 libc6-i386
sudo apt-get install gcc-multilib g++-multilib
</pre>
</li>
</ol>

==Mac OS X==
Mac OS X 10.7 or higher is required to build, however, AMX Mod X will work on versions as early as 10.5.

<ol>
<li>Install the Xcode Command Line Tools.
<ul>
<li>For OS X 10.9 or higher, run the command below in Terminal and click the Install button in the window that appears.
<pre>
xcode-select --install
</pre>
</li>
<li>For earlier versions of OS X, download and install Xcode from the App Store. Launch Xcode and then navigate to Preferences -> Downloads -> Components -> Command Line Tools -> Install. If you have recently upgraded Xcode, you will need to perform this step again. AMX Mod X cannot build without Xcode's command line tools.</li>
</ul>
</ol>

=Dependencies=
Building AMX Mod X requires AMBuild, Metamod, the Half-Life SDK, and optionally MySQL 5. If you're using Linux, OS X, or Windows with MozillaBuild, you download and run the following script to get everything:

<pre>
https://raw.githubusercontent.com/alliedmodders/amxmodx/master/support/checkout-deps.sh
bash checkout-deps.sh
</pre>

This will download everything required into <tt>amxmodx</tt>, <tt>hlsdk</tt>, and <tt>metamod-am</tt>. If AMBuild is not installed, it will also download it into <tt>ambuild</tt>, and prompt you for your password to install it.

If for some reason this script doesn't work, or you can't use it, you can get AMX Mod X and its dependencies like so:
<pre>
git clone https://github.com/alliedmodders/ambuild
git clone https://github.com/alliedmodders/metamod-hl1
git clone https://github.com/alliedmodders/hlsdk
git clone https://github.com/alliedmodders/amxmodx
cd ambuild
python setup.py install # May need sudo or root on Linux/OS X
</pre>

=Configuring=

The first time you are building AMX Mod X, you must ''configure'' the build. First create a build folder, and then run <tt>configure.py</tt>. For example:
<pre>
mkdir build
cd build
python ../configure.py
</pre>

It is safe to reconfigure over an old build. However, it's probably a bad idea to configure inside a random, non-empty folder.

There are a few extra options you can pass to <tt>configure</tt>:
*--enable-debug - Compile with symbols and debug checks/assertions.
*--enable-optimize - Compile with optimizations.
*--no-mysql - If you didn't install MySQL, you can choose not to build the extension.

=Building=

To build AMX Mod X, simply navigate to your build folder and type <tt>ambuild</tt>:
<pre>
cd build
ambuild
</pre>

Alternately, you can specify the path of the build folder:
<pre>
ambuild build
</pre>

The full package layouts that would be shipped for release are in the <tt>package</tt> folder of the build.

[[Category:Documentation (AMX Mod X)]]