Write Your First AMX Mod X Plugin (Hello World)

The fastest way to understand AMX Mod X is to write a plugin that does something real, compile it, and watch it run on your server. This one registers a chat command — typing /hp reports your health and armor — and greets players when they connect. It is short, it compiles, and it touches the three things every plugin uses: plugin_init, a command callback, and a client event. If the Pawn syntax here is unfamiliar, read Pawn language basics first.

1. Create the .sma source

Make a file myfirst.sma. The #include <amxmodx> line pulls in the core API; #include <cstrike> gives you CS-specific natives like armor:

#include <amxmodx>
#include <cstrike>

#define PLUGIN  "My First Plugin"
#define VERSION "1.0.0"
#define AUTHOR  "Your Name"

public plugin_init() {
    register_plugin(PLUGIN, VERSION, AUTHOR)
    register_clcmd("say /hp", "cmd_hp")
    register_clcmd("say_team /hp", "cmd_hp")
}

public cmd_hp(id) {
    if (!is_user_alive(id)) {
        client_print(id, print_chat, "[MyPlugin] You are dead.")
        return PLUGIN_HANDLED
    }

    new health = get_user_health(id)
    new armor  = cs_get_user_armor(id)

    new name[32]
    get_user_name(id, name, charsmax(name))

    client_print(id, print_chat, "[MyPlugin] %s - HP: %d, Armor: %d", name, health, armor)
    return PLUGIN_HANDLED
}

public client_putinserver(id) {
    new name[32]
    get_user_name(id, name, charsmax(name))
    client_print(0, print_chat, "[MyPlugin] Welcome, %s!", name)
}

2. Understand what each part does

• plugin_init() runs once when the plugin loads. register_plugin is mandatory — it names the plugin in amxx list.
• register_clcmd("say /hp", "cmd_hp") ties the chat text /hp to your cmd_hp function. Registering both say and say_team means it works whether typed in all-chat or team-chat.
• cmd_hp(id) receives the player's id (1–32). Returning PLUGIN_HANDLED stops the /hp text from also appearing as a public chat message.
• client_putinserver(id) is a forward AMXX calls when a player finishes connecting. client_print(0, ...) with id 0 prints to everyone.

3. Compile it

Compile myfirst.sma into myfirst.amxx. The full walkthrough is in compiling a .sma into .amxx; the short version on the server box is:

cd /home/steam/hlds/cstrike/addons/amxmodx/scripting
./amxxpc myfirst.sma

A clean compile ends with Done. and produces compiled/myfirst.amxx. Warnings about unused symbols are fine; errors stop the build and must be fixed.

4. Install it

Copy the compiled plugin into the plugins folder and register it:

cp compiled/myfirst.amxx ../plugins/myfirst.amxx

Add a line to addons/amxmodx/configs/plugins.ini:

myfirst.amxx

Then reload plugins without restarting the whole server — from RCON or the server console:

amxx reload

Or just change the map. amxx reload re-reads plugins.ini.

5. Test in game

Join the server and type /hp in chat. You should see your name, HP, and armor printed back to you, and no /hp text leaking to public chat. Connect a second client and the whole server should see the welcome line.

6. Add a cvar to toggle it

Hard-coded behaviour is fine for a first plugin, but a real one is configurable. Add a cvar so admins can switch the welcome message off without recompiling. Register it in plugin_init and check it before printing:

new g_pWelcome

public plugin_init() {
    register_plugin(PLUGIN, VERSION, AUTHOR)
    register_clcmd("say /hp", "cmd_hp")
    register_clcmd("say_team /hp", "cmd_hp")
    g_pWelcome = register_cvar("myplugin_welcome", "1")
}

public client_putinserver(id) {
    if (!get_pcvar_num(g_pWelcome))
        return
    new name[32]
    get_user_name(id, name, charsmax(name))
    client_print(0, print_chat, "[MyPlugin] Welcome, %s!", name)
}

Now admins can put myplugin_welcome 0 in server.cfg (or better, an amxx.cfg) to silence the greeting. Recompile, reload, and the cvar exists immediately — verify with myplugin_welcome in the console.

Common errors

• Plugin shows as bad load in amxx list — the .amxx was built for a newer AMXX than the server runs, or the file is corrupt. Recompile with the matching compiler; see AMX Mod X 1.9.
• /hp also appears in chat — you returned PLUGIN_CONTINUE (or nothing) instead of PLUGIN_HANDLED.
• cs_get_user_armor undefined — you forgot #include <cstrike>.
• Nothing happens on /hp — the plugin is not in plugins.ini, or you did not amxx reload / change map.
• Garbage or truncated name — the name buffer is too small or you passed the wrong length; use charsmax(name).

Verification

In the server console:

amxx list

Your plugin must appear as running (not bad load or debug). Once it does and /hp works in game, you have the full loop: edit, compile, install, reload. From here, add a cvar to toggle the feature and explore the cstrike and fun natives — and when you want a proper editor, set up VS Code for AMX Mod X.