Add reapi-getting-started/en.md
Browse Source
Daemon666 committed
parent 2752a50df7
commit a91fcd6eda578db41d357c070ef9f71c3a1c5268
1 changed file
with 73 additions and 0 deletions
reapi-getting-started/en.md
A
| @@ -0,0 +1,73 @@ | ||
| 1 | +--- | |
| 2 | +title: "Getting Started with ReAPI: Hooks, Natives and Members" | |
| 3 | +excerpt: "ReAPI exposes ReGameDLL and ReHLDS internals to AMXX with named hook chains, get_member/set_member, and high-level rg_ natives. Requires ReGameDLL." | |
| 4 | +category: "plugin-dev" | |
| 5 | +tags: "reapi, amxmodx" | |
| 6 | +image: "" | |
| 7 | +read_time: "8 min read" | |
| 8 | +--- | |
| 9 | +<p>ReAPI (module <code>reapi</code>) is the modern way to touch CS 1.6 internals from Pawn. Instead of fighting the game through fakemeta offsets and Ham Sandwich guesswork, it gives you named hook chains, named struct members, and high-level natives that do the right thing. The catch is non-negotiable: <strong>ReAPI requires ReGameDLL</strong>, and most of its hooks require ReHLDS too. A plugin that <code>#include <reapi></code> will not load on a stock game DLL. Confirm your stack first with <code>regamedll_version</code> in the server console; if that is unknown, install <a href="/tutorials/install-regamedll-cs16">ReGameDLL</a> and <a href="/tutorials/install-reapi">ReAPI</a> before writing a line.</p> | |
| 10 | + | |
| 11 | +<h2>1. Hook chains with RegisterHookChain</h2> | |
| 12 | +<p>ReAPI hooks are called <em>hook chains</em>. <code>RegisterHookChain</code> takes a function id, your callback, and a post flag. The function ids are the real ReGameDLL functions, prefixed <code>RG_</code>, and ReHLDS functions prefixed <code>RH_</code>:</p> | |
| 13 | +<pre>#include <amxmodx> | |
| 14 | +#include <reapi> | |
| 15 | + | |
| 16 | +public plugin_init() | |
| 17 | +{ | |
| 18 | + register_plugin("ReAPI Demo", "1.0", "CSB") | |
| 19 | + | |
| 20 | + RegisterHookChain(RG_CBasePlayer_TakeDamage, "on_take_damage", 0) | |
| 21 | + RegisterHookChain(RG_CBasePlayer_Spawn, "on_spawn_post", 1) | |
| 22 | + RegisterHookChain(RG_RoundEnd, "on_round_end", 0) | |
| 23 | +}</pre> | |
| 24 | +<p>As with Ham Sandwich, the post flag chooses pre (<code>0</code>) or post (<code>1</code>). The difference is clarity: the hook name says exactly which game function you are on, and the arguments arrive named and typed.</p> | |
| 25 | + | |
| 26 | +<h2>2. Reading, changing and blocking</h2> | |
| 27 | +<p>Inside a hook, read the arguments as normal parameters. To change an argument, use <code>SetHookChainArg(position, type, value)</code>; to change the return value, <code>SetHookChainReturn(type, value)</code>. Control flow uses <code>HC_CONTINUE</code> (proceed), <code>HC_SUPERCEDE</code> (block the original), and <code>HC_BREAK</code>:</p> | |
| 28 | +<pre>public on_take_damage(const victim, inflictor, attacker, Float:damage, bits) | |
| 29 | +{ | |
| 30 | + if (!is_user_connected(attacker)) | |
| 31 | + return HC_CONTINUE | |
| 32 | + | |
| 33 | + // halve incoming damage, then let the call proceed | |
| 34 | + SetHookChainArg(4, ATYPE_FLOAT, damage * 0.5) | |
| 35 | + return HC_CONTINUE | |
| 36 | +}</pre> | |
| 37 | +<p>The <code>ATYPE_*</code> constants tell ReAPI the argument's type: <code>ATYPE_INTEGER</code>, <code>ATYPE_FLOAT</code>, <code>ATYPE_STRING</code>, <code>ATYPE_CLASSPTR</code>, <code>ATYPE_EDICT</code>, <code>ATYPE_EVARS</code>. Match the type to the parameter or the write is ignored.</p> | |
| 38 | + | |
| 39 | +<h2>3. Named members</h2> | |
| 40 | +<p>This is where ReAPI earns its keep. <code>get_member</code> and <code>set_member</code> read and write the player's C++ class fields by name — no offsets, no fakemeta pev tricks:</p> | |
| 41 | +<pre>public give_money(id) | |
| 42 | +{ | |
| 43 | + new money = get_member(id, m_iAccount) | |
| 44 | + set_member(id, m_iAccount, money + 1000) | |
| 45 | + | |
| 46 | + new team = get_member(id, m_iTeam) | |
| 47 | + server_print("player %d is on team %d with $%d", id, team, money + 1000) | |
| 48 | +}</pre> | |
| 49 | +<p>Entity variables (the old <code>entvars_t</code>) have named accessors too, <code>get_entvar</code>/<code>set_entvar</code>, which replace fakemeta's <code>pev</code>/<code>set_pev</code>:</p> | |
| 50 | +<pre>set_entvar(id, var_health, 150.0) | |
| 51 | +new Float:speed = get_entvar(id, var_maxspeed)</pre> | |
| 52 | +<p>The member and var constant names live in the reapi includes — open them and use the exact identifiers rather than inventing likely-looking ones.</p> | |
| 53 | + | |
| 54 | +<h2>4. High-level natives</h2> | |
| 55 | +<p>ReAPI also ships <code>rg_</code> natives that wrap common actions correctly, so you do not reconstruct game logic by hand:</p> | |
| 56 | +<pre>rg_add_account(id, 5000) // give money (updates HUD) | |
| 57 | +rg_give_item(id, "weapon_awp") // give a weapon the proper way | |
| 58 | +rg_remove_all_items(id, false) // strip inventory</pre> | |
| 59 | +<p><code>rg_give_item</code> runs the same path the buy menu uses, so ammo, HUD, and prediction all stay correct — a recurring problem when people fake weapon-giving with raw engine calls. Check the reapi include for the exact native list and argument order.</p> | |
| 60 | + | |
| 61 | +<h2>5. Plugin metadata</h2> | |
| 62 | +<p>When you publish a ReAPI plugin, its metadata must declare the dependency so nobody tries to run it on the wrong stack: set both <code>reapi_required</code> and <code>regamedll_required</code>. The two always travel together — ReAPI's hooks are ReGameDLL's functions.</p> | |
| 63 | + | |
| 64 | +<h2>Common errors</h2> | |
| 65 | +<ul> | |
| 66 | +<li><strong>Plugin fails to load: reapi module error</strong> — the <code>reapi</code> module is not in <code>modules.ini</code>, or ReGameDLL is not installed. Verify with <code>regamedll_version</code>; a stock DLL cannot support ReAPI.</li> | |
| 67 | +<li><strong><code>SetHookChainArg</code> does nothing</strong> — wrong <code>ATYPE_*</code> for the parameter, or you called it in a post hook. Arguments can only be changed in a pre hook.</li> | |
| 68 | +<li><strong>Unknown member constant at compile time</strong> — you guessed a member name. The valid <code>m_*</code> and <code>var_*</code> identifiers are in the reapi includes; there is no member that is not defined there.</li> | |
| 69 | +<li><strong>Money/weapon given but HUD wrong</strong> — you set <code>m_iAccount</code> directly instead of using <code>rg_add_account</code>, which also refreshes the client. Prefer the <code>rg_</code> native when one exists.</li> | |
| 70 | +</ul> | |
| 71 | + | |
| 72 | +<h2>Verification</h2> | |
| 73 | +<p>Load the plugin on a confirmed ReGameDLL server and check the AMXX log shows it running, not failed. Trigger each hook and confirm a <code>server_print</code> fires with sane named values. For a member write, read it back and confirm it stuck; for <code>rg_add_account</code>, watch the money counter update on the client. If you are weighing ReAPI against the portable alternatives, read <a href="/tutorials/register-event-vs-ham-vs-reapi">register_event vs Hamsandwich vs ReAPI</a>; for raw engine access on non-ReGameDLL servers, <a href="/tutorials/fakemeta-basics">fakemeta basics</a> covers the fallback.</p> | |
| 0 | 74 |
