Add register-event-vs-ham-vs-reapi/en.md
Browse Source
Daemon666 committed
parent ed83c2dc3d
commit c8167ca6e3ebf2ad0d92b2619c8573caf34c94b0
1 changed file
with 80 additions and 0 deletions
register-event-vs-ham-vs-reapi/en.md
A
| @@ -0,0 +1,80 @@ | ||
| 1 | +--- | |
| 2 | +title: "register_event vs Hamsandwich vs ReAPI: When to Use Which" | |
| 3 | +excerpt: "Three ways to hook the game from AMXX, what each one actually intercepts, their dependencies, and a decision rule for picking the right one." | |
| 4 | +category: "plugin-dev" | |
| 5 | +tags: "hooks, comparison" | |
| 6 | +image: "" | |
| 7 | +read_time: "7 min read" | |
| 8 | +--- | |
| 9 | +<p>AMX Mod X gives you three fundamentally different ways to react to what happens in a round, and choosing wrong means either code that cannot see what you need or a dependency you did not have to take on. <code>register_event</code> listens to network messages. Ham Sandwich hooks virtual functions inside the game DLL. ReAPI hooks ReGameDLL's real functions with named arguments. They overlap in what they can do but differ sharply in <em>what they can see</em>, <em>whether they can change it</em>, and <em>what they require to be installed</em>.</p> | |
| 10 | + | |
| 11 | +<h2>1. register_event — the network message layer</h2> | |
| 12 | +<p>Events fire when the game DLL sends a message to a client: someone died (<code>DeathMsg</code>), health changed (<code>Health</code>), a weapon became active (<code>CurWeapon</code>). It is pure core AMXX — no module, no engine replacement — so it runs on stock HLDS as happily as on ReHLDS. See <a href="/tutorials/register-event-explained">the register_event guide</a> for details.</p> | |
| 13 | +<p>Its limitation is that it is a <em>notification</em>, not an interception. By the time <code>DeathMsg</code> is sent, the player is already dead. You can react, but you cannot prevent, and you cannot read anything the message does not carry. It is also occasionally lossy: a message that the DLL chooses not to send is an event you never see.</p> | |
| 14 | + | |
| 15 | +<h2>2. Ham Sandwich — virtual function hooks</h2> | |
| 16 | +<p>Ham Sandwich (module <code>hamsandwich</code>) hooks the virtual methods of game entities: <code>Ham_TakeDamage</code>, <code>Ham_Killed</code>, <code>Ham_Spawn</code>, <code>Ham_Player_PreThink</code>. These fire <em>as the function runs</em>, in both a pre and a post variant, so you can read the real arguments and — crucially — block or modify them:</p> | |
| 17 | +<pre>#include <amxmodx> | |
| 18 | +#include <hamsandwich> | |
| 19 | + | |
| 20 | +public plugin_init() | |
| 21 | +{ | |
| 22 | + register_plugin("Ham Demo", "1.0", "CSB") | |
| 23 | + RegisterHam(Ham_TakeDamage, "player", "fw_take_damage", 0) | |
| 24 | +} | |
| 25 | + | |
| 26 | +public fw_take_damage(victim, inflictor, attacker, Float:damage, bits) | |
| 27 | +{ | |
| 28 | + // halve all incoming damage | |
| 29 | + SetHamParamFloat(4, damage * 0.5) | |
| 30 | + return HAM_HANDLED | |
| 31 | +}</pre> | |
| 32 | +<p>Ham Sandwich works on both original CS and ReGameDLL, which is its great advantage: portable damage/spawn/kill hooks that run anywhere. The cost is that it deals in raw offsets — entity classnames, parameter positions — and gives you no named members. See <a href="/tutorials/hamsandwich-basics">the Ham Sandwich guide</a>.</p> | |
| 33 | + | |
| 34 | +<h2>3. ReAPI — the ReGameDLL native layer</h2> | |
| 35 | +<p>ReAPI (module <code>reapi</code>) exposes ReGameDLL and ReHLDS internals directly: hook chains (<code>RegisterHookChain</code>), named members (<code>get_member</code>/<code>set_member</code>), and high-level natives (<code>rg_give_item</code>, <code>rg_add_account</code>). It is the richest and cleanest of the three — but it <strong>requires ReGameDLL</strong>. A plugin that <code>#include <reapi></code> will not load on a server running the stock game DLL.</p> | |
| 36 | +<pre>#include <amxmodx> | |
| 37 | +#include <reapi> | |
| 38 | + | |
| 39 | +public plugin_init() | |
| 40 | +{ | |
| 41 | + register_plugin("ReAPI Demo", "1.0", "CSB") | |
| 42 | + RegisterHookChain(RG_CBasePlayer_TakeDamage, "on_take_damage", 0) | |
| 43 | +} | |
| 44 | + | |
| 45 | +public on_take_damage(const victim, inflictor, attacker, Float:damage, bits) | |
| 46 | +{ | |
| 47 | + SetHookChainArg(4, ATYPE_FLOAT, damage * 0.5) | |
| 48 | + return HC_CONTINUE | |
| 49 | +}</pre> | |
| 50 | +<p>If you ship a ReAPI plugin, set both <code>reapi_required</code> and <code>regamedll_required</code> in its metadata — the two go together. Install steps are in <a href="/tutorials/install-reapi">the ReAPI install guide</a>, which itself depends on <a href="/tutorials/install-regamedll-cs16">ReGameDLL</a>.</p> | |
| 51 | + | |
| 52 | +<h2>4. The decision rule</h2> | |
| 53 | +<table> | |
| 54 | +<thead><tr><th></th><th>register_event</th><th>Ham Sandwich</th><th>ReAPI</th></tr></thead> | |
| 55 | +<tbody> | |
| 56 | +<tr><td>Requires</td><td>Core AMXX only</td><td>hamsandwich module</td><td>ReGameDLL + reapi</td></tr> | |
| 57 | +<tr><td>Can block / modify</td><td>No</td><td>Yes</td><td>Yes</td></tr> | |
| 58 | +<tr><td>Named arguments</td><td>No</td><td>No</td><td>Yes</td></tr> | |
| 59 | +<tr><td>Runs on stock CS DLL</td><td>Yes</td><td>Yes</td><td>No</td></tr> | |
| 60 | +</tbody> | |
| 61 | +</table> | |
| 62 | +<p>In practice:</p> | |
| 63 | +<ul> | |
| 64 | +<li><strong>You only need to know something happened</strong> — a kill for a HUD, a weapon switch for a speed cap — use <code>register_event</code>. It is the lightest and most portable.</li> | |
| 65 | +<li><strong>You need to change damage, spawning, or killing, and the plugin must run on any server</strong> — use Ham Sandwich. It is the portable interception layer.</li> | |
| 66 | +<li><strong>You are already on ReGameDLL and want clean, correct, named access</strong> — use ReAPI. It replaces piles of Ham + fakemeta guesswork with readable natives, at the price of a hard dependency.</li> | |
| 67 | +</ul> | |
| 68 | + | |
| 69 | +<h2>5. They compose</h2> | |
| 70 | +<p>Real plugins mix all three: a <code>register_event</code> on <code>DeathMsg</code> to update a scoreboard, a <code>RegisterHam(Ham_Spawn, ...)</code> to give spawn protection, and — on a ReGameDLL server — <code>rg_add_account</code> to hand out money. There is no rule against combining them; the rule is to take the <em>lightest</em> tool that can see and do what a given feature needs, so the plugin loads on the widest set of servers.</p> | |
| 71 | + | |
| 72 | +<h2>Common mistakes</h2> | |
| 73 | +<ul> | |
| 74 | +<li><strong>Reaching for ReAPI on a stock-DLL server</strong> — the plugin fails to load with a module error. Confirm ReGameDLL first with <code>regamedll_version</code> in the console.</li> | |
| 75 | +<li><strong>Trying to block damage with <code>register_event</code></strong> — impossible; events are notifications. Move the logic to <code>Ham_TakeDamage</code> or the ReAPI hook chain.</li> | |
| 76 | +<li><strong>Hooking the same effect in two layers</strong> — e.g. blocking damage in Ham <em>and</em> ReAPI. Pick one; double-hooking produces confusing double-applied modifications.</li> | |
| 77 | +</ul> | |
| 78 | + | |
| 79 | +<h2>Verification</h2> | |
| 80 | +<p>For any hook, add a <code>server_print</code> at the top of the handler and confirm it fires exactly once per real in-game event. If a Ham or ReAPI plugin refuses to load, check the AMXX logs for a module-load line — a missing <code>hamsandwich</code> or <code>reapi</code> module is the usual cause, covered in <a href="/tutorials/fix-amxx-module-failed-to-load">the module-failed-to-load fix</a>.</p> | |
| 0 | 81 |
