Add 2 tutorials (2 files)
Browse Source
Daemon666 committed
parent dfb5fa98ee
commit d5feeec947cb189a5be4adc9a7117c1750d07473
2 changed files
with 130 additions and 0 deletions
compile-sma-to-amxx/en.md
A
| @@ -0,0 +1,71 @@ | ||
| 1 | +--- | |
| 2 | +title: "How to Compile a .sma File into .amxx" | |
| 3 | +excerpt: "amxxpc turns Pawn source into the .amxx bytecode the server loads. How to compile locally on Linux and Windows, read the errors, target the right AMXX version, and install the result." | |
| 4 | +category: "plugin-dev" | |
| 5 | +tags: "compiling, amxxpc" | |
| 6 | +image: "" | |
| 7 | +read_time: "8 min read" | |
| 8 | +--- | |
| 9 | +<p>AMX Mod X does not run <code>.sma</code> source directly. The compiler <code>amxxpc</code> turns Pawn source into <code>.amxx</code> bytecode, and only the <code>.amxx</code> goes on the server. This guide covers compiling locally with the compiler that ships inside AMX Mod X, reading its output, and the version pitfalls that cause <code>bad load</code>.</p> | |
| 10 | + | |
| 11 | +<h2>1. Find the compiler</h2> | |
| 12 | +<p>Every AMX Mod X install ships <code>amxxpc</code> in the scripting folder:</p> | |
| 13 | +<pre>addons/amxmodx/scripting/amxxpc # Linux | |
| 14 | +addons/amxmodx/scripting/amxxpc.exe # Windows</pre> | |
| 15 | +<p>Alongside it is <code>compile.sh</code> (Linux) / <code>compile.exe</code> (Windows) and an <code>include/</code> directory holding every <code>.inc</code>. Compile from inside this folder so the includes resolve.</p> | |
| 16 | + | |
| 17 | +<h2>2. Compile on Linux</h2> | |
| 18 | +<p><code>amxxpc</code> is a 32-bit binary, so a 64-bit host needs the 32-bit C runtime or the compiler will not even start:</p> | |
| 19 | +<pre>sudo dpkg --add-architecture i386 | |
| 20 | +sudo apt update | |
| 21 | +sudo apt install -y lib32stdc++6 libc6:i386</pre> | |
| 22 | +<p>Then compile:</p> | |
| 23 | +<pre>cd addons/amxmodx/scripting | |
| 24 | +./amxxpc myplugin.sma</pre> | |
| 25 | +<p>On success the last line is <code>Done.</code> and the output lands in <code>compiled/myplugin.amxx</code>. To build every <code>.sma</code> in the folder at once, use the batch script:</p> | |
| 26 | +<pre>./compile.sh</pre> | |
| 27 | + | |
| 28 | +<h2>3. Compile on Windows</h2> | |
| 29 | +<pre>cd addons\amxmodx\scripting | |
| 30 | +amxxpc.exe myplugin.sma</pre> | |
| 31 | +<p>Or drag the <code>.sma</code> onto <code>compile.exe</code>. Output goes to the <code>compiled\</code> subfolder. If nothing appears and a console window flashes, run it from <code>cmd.exe</code> so you can read the error.</p> | |
| 32 | + | |
| 33 | +<h2>4. Read the output</h2> | |
| 34 | +<p>Distinguish the two message classes:</p> | |
| 35 | +<ul> | |
| 36 | +<li><strong>Warnings</strong> — the plugin still compiles. A <code>.amxx</code> is produced. Common ones: unused symbol, tag mismatch, symbol never used. Fix them, but they are not fatal.</li> | |
| 37 | +<li><strong>Errors</strong> — no <code>.amxx</code> is produced. The build stops.</li> | |
| 38 | +</ul> | |
| 39 | +<p>Typical errors and what they mean:</p> | |
| 40 | +<pre>error 017: undefined symbol "cs_get_user_armor"</pre> | |
| 41 | +<p>— a missing <code>#include</code> (here <code>#include <cstrike></code>), or a typo in a native name.</p> | |
| 42 | +<pre>error 001: expected token: ";" , but found ...</pre> | |
| 43 | +<p>— a syntax error, usually a missing brace or bracket on the line <em>above</em> the one reported.</p> | |
| 44 | +<pre>error 088: number of arguments does not match definition</pre> | |
| 45 | +<p>— you called a native with the wrong argument count; check the declaration in the include file.</p> | |
| 46 | + | |
| 47 | +<h2>5. Target the right AMXX version</h2> | |
| 48 | +<p>The <code>.amxx</code> must be compiled by a compiler no newer than the AMXX the server runs, or the server rejects it as <code>bad load</code>. If your server runs AMX Mod X 1.9, compile with the 1.9 <code>amxxpc</code>. Natives added in 1.9 (such as <code>client_print_color</code>) do not exist in the 1.8.2 compiler — if you use them, you must compile with 1.9 or newer. The safe rule: <strong>compile with the same AMXX version your server runs</strong>. See <a href="/tutorials/install-amx-mod-x-1-9">installing AMX Mod X 1.9</a>.</p> | |
| 49 | + | |
| 50 | +<h2>6. Include third-party headers</h2> | |
| 51 | +<p>If a plugin needs a header that is not in the stock <code>include/</code> folder (for example <code>reapi.inc</code> for a <a href="/tutorials/install-reapi">ReAPI</a> plugin), drop the <code>.inc</code> into <code>addons/amxmodx/scripting/include/</code> before compiling. <code>amxxpc</code> searches that folder for <code>#include <name></code>. Do not use a path in the include — put the file where the compiler already looks. When you use a native that only exists in a newer AMXX, the header must also be the newer one; a stale <code>amxmodx.inc</code> will report the native as an <code>undefined symbol</code> even though the compiler binary supports it.</p> | |
| 52 | + | |
| 53 | +<h2>6b. Compiling on your PC vs on the server</h2> | |
| 54 | +<p>You do not have to compile on the game server. Many admins keep a copy of the <code>scripting/</code> folder (compiler plus <code>include/</code>) on their workstation, compile there, and upload only the finished <code>.amxx</code>. That keeps source and build tools off the production box entirely. The one rule that never changes: the compiler version you build with must match the AMXX version running on the server, wherever you run it. If you maintain several servers on different AMXX versions, keep a separate <code>scripting/</code> folder per version and compile against the right one.</p> | |
| 55 | + | |
| 56 | +<h2>7. Install the compiled plugin</h2> | |
| 57 | +<pre>cp compiled/myplugin.amxx ../plugins/myplugin.amxx</pre> | |
| 58 | +<p>Add its filename to <code>addons/amxmodx/configs/plugins.ini</code>, then in the server console:</p> | |
| 59 | +<pre>amxx reload</pre> | |
| 60 | +<p>or change the map. Confirm it loaded with <code>amxx list</code>.</p> | |
| 61 | + | |
| 62 | +<h2>Common errors</h2> | |
| 63 | +<ul> | |
| 64 | +<li><strong><code>amxxpc: No such file or directory</code> on Linux</strong> — missing 32-bit runtime; install <code>lib32stdc++6</code> and <code>libc6:i386</code>.</li> | |
| 65 | +<li><strong><code>bad load</code> on the server</strong> — compiled with a newer AMXX than the server runs. Recompile with the matching version.</li> | |
| 66 | +<li><strong><code>undefined symbol</code></strong> — missing <code>#include</code> or a third-party <code>.inc</code> not in the include folder.</li> | |
| 67 | +<li><strong>Compiles but does nothing</strong> — you copied the <code>.sma</code> to <code>plugins/</code> instead of the <code>.amxx</code>. Only the compiled file loads.</li> | |
| 68 | +</ul> | |
| 69 | + | |
| 70 | +<h2>Verification</h2> | |
| 71 | +<p>A successful build produces <code>compiled/myplugin.amxx</code> and prints <code>Done.</code> with zero errors. After installing and reloading, <code>amxx list</code> shows the plugin as <code>running</code>. For an editor that runs <code>amxxpc</code> on a keystroke and jumps to the exact error line, set up <a href="/tutorials/vscode-amxx-setup">VS Code for AMX Mod X</a>.</p> |
find-crashing-plugin/en.md
A
| @@ -0,0 +1,59 @@ | ||
| 1 | +--- | |
| 2 | +title: "How to Find Which Plugin Is Crashing Your Server" | |
| 3 | +excerpt: "A disciplined bisection method for finding the AMXX or Metamod plugin that crashes your CS 1.6 server - reading the logs, halving plugins.ini, and confirming the culprit both ways." | |
| 4 | +category: "errors" | |
| 5 | +tags: "plugins, crash" | |
| 6 | +image: "" | |
| 7 | +read_time: "8 min read" | |
| 8 | +--- | |
| 9 | +<p>The server crashes, restarts, crashes again, and you have thirty plugins. Guessing wastes an evening; bisection finds the culprit in a handful of restarts. The method is the same whether the crash is a hard segfault, a map-change abort, or a slow degradation: read what the logs already told you, then halve the plugin list until one plugin is left holding the knife.</p> | |
| 10 | + | |
| 11 | +<h2>1. Read the logs before you touch anything</h2> | |
| 12 | +<p>The engine and AMXX often name the plugin for free. Look in:</p> | |
| 13 | +<pre>ls -t addons/amxmodx/logs/ | |
| 14 | +cat addons/amxmodx/logs/L*.log | tail -50</pre> | |
| 15 | +<p>And the engine's own output — <code>hlds_run</code> writes a crash file:</p> | |
| 16 | +<pre>cat debug.log | |
| 17 | +ls -la core* # a core dump, if one was written</pre> | |
| 18 | +<p>AMXX errors look like <code>Run time error 10: native error</code> or a specific plugin name with a line number. If a plugin is named right before the crash, start there — you may skip the whole bisection.</p> | |
| 19 | + | |
| 20 | +<h2>2. Reproduce it reliably</h2> | |
| 21 | +<p>You cannot bisect a crash you cannot trigger. Note exactly what causes it: a specific map change, a player action, a command, a certain player count, or simply "within N minutes". A crash on <code>changelevel</code> is often a precache or delta problem; a crash on a player action points at the plugin handling that action. Write the trigger down — you will run it after every step.</p> | |
| 22 | + | |
| 23 | +<h2>3. Halve the plugin list</h2> | |
| 24 | +<p>Open <code>addons/amxmodx/configs/plugins.ini</code>. Comment out the bottom half with a semicolon:</p> | |
| 25 | +<pre>; disabled for bisection | |
| 26 | +; zombie.amxx | |
| 27 | +; shop.amxx | |
| 28 | +statsx.amxx | |
| 29 | +adminmenu.amxx</pre> | |
| 30 | +<p>Restart, reproduce the trigger. If it still crashes, the culprit is in the enabled half; if it stops, it is in the disabled half. Re-enable/disable to keep halving the guilty half. With thirty plugins you reach one plugin in about five rounds. This is far faster than disabling one plugin at a time.</p> | |
| 31 | + | |
| 32 | +<h2>4. Don't forget Metamod plugins and modules</h2> | |
| 33 | +<p>Not everything is in <code>plugins.ini</code>. Metamod plugins (ReAPI, some anti-cheats, custom modules) live in <code>addons/metamod/plugins.ini</code>, and AMXX modules load from <code>configs/modules.ini</code>. If halving AMXX plugins never stops the crash, bisect those lists too:</p> | |
| 34 | +<pre>meta list | |
| 35 | +amxx modules</pre> | |
| 36 | +<p>A crash that survives disabling <em>every</em> AMXX plugin is either a module, a Metamod plugin, the game DLL, or the map — which is a useful result, because it clears a whole category.</p> | |
| 37 | + | |
| 38 | +<h2>5. Separate plugin crashes from engine/map crashes</h2> | |
| 39 | +<p>If the crash reproduces with a completely empty <code>plugins.ini</code>, it is not an AMXX plugin. Now the suspects are the engine, the game DLL, <code>delta.lst</code>, or a specific map. A <code>changelevel</code> crash with no plugins usually means a bad <a href="/tutorials/fix-model-overflow-precache">precache/overflow</a> or a mismatched <a href="/tutorials/install-regamedll-cs16">ReGameDLL delta.lst</a>. Test on a stock map like <code>de_dust2</code> to rule the map in or out.</p> | |
| 40 | + | |
| 41 | +<h2>6. Turn on more detail before the next bisection round</h2> | |
| 42 | +<p>You want the maximum information from each crash so you need fewer rounds. Two levers help. Raise AMXX's log verbosity so runtime errors are written with a stack, and keep the engine's console output where you can read it:</p> | |
| 43 | +<pre>amx_logging 2 | |
| 44 | +developer 1</pre> | |
| 45 | +<p>A JIT-related crash sometimes only reproduces with the AMXX JIT on; if a plugin crashes hard with no useful log, temporarily disabling the JIT can turn a silent segfault into a readable runtime error that names the plugin and line. Do this on a <strong>staging</strong> server, never by experimenting on the live one — the whole point is to stop crashing the box players are on. Once you have the plugin, put the settings back.</p> | |
| 46 | + | |
| 47 | +<h2>Common errors</h2> | |
| 48 | +<ul> | |
| 49 | +<li><strong>Bisection points nowhere</strong> — you re-enabled the wrong half, or the crash is timing-dependent. Reproduce more carefully and keep the trigger identical each round.</li> | |
| 50 | +<li><strong>Two plugins crash only together</strong> — rare but real (a shared entity or hook conflict). If halving is inconsistent, test suspect pairs.</li> | |
| 51 | +<li><strong>Crash survives an empty plugins.ini</strong> — it is a module, Metamod plugin, game DLL, or map, not an AMXX plugin.</li> | |
| 52 | +<li><strong>Only crashes with players on</strong> — a per-client code path. Note which action precedes it; that names the subsystem.</li> | |
| 53 | +</ul> | |
| 54 | + | |
| 55 | +<h2>Verification</h2> | |
| 56 | +<p>Once one plugin is isolated, prove it both ways: run the server with only that plugin disabled and confirm stability across several map changes and the original trigger, then re-enable just that plugin and confirm the crash returns.</p> | |
| 57 | +<pre>; suspected culprit isolated | |
| 58 | +; badplugin.amxx</pre> | |
| 59 | +<p>That two-way confirmation is what separates the real culprit from a coincidence. With the guilty plugin named, either update it, replace it with a maintained equivalent, or fix its source and recompile. If it turned out to be a <code>bad load</code> rather than a crash, that is a different problem — see <a href="/tutorials/fix-plugins-bad-load-after-19">the bad load fix</a>.</p> | |
| 0 | 60 |
