HamSandwich General Usage (AMX Mod X) - Revision history

Kristi at 20:42, 30 August 2017

2017-08-30T20:42:05Z

Show changes

ConnorMcLeod at 17:55, 22 October 2013

2013-10-22T17:55:36Z

Shaman: /* About Ham Sandwich */

2008-07-21T12:15:02Z

‎About Ham Sandwich

Sawce: /* Changing Hook Parameters */

2007-05-11T03:39:55Z

‎Changing Hook Parameters

Sawce: /* Return Values */

2007-05-11T03:39:13Z

‎Return Values

Sawce: /* Config File Requirements */

2007-05-11T03:36:14Z

‎Config File Requirements

Sawce: /* About Ham Sandwich */

2007-05-11T03:34:30Z

‎About Ham Sandwich

Sawce: /* Hooking Functions */

2007-05-11T03:24:43Z

‎Hooking Functions

Sawce at 18:38, 10 May 2007

2007-05-10T18:38:16Z

Sawce: /* Hooking Functions */

2007-05-10T18:36:38Z

‎Hooking Functions

@@ Line 201: / Line 201: @@
 Similar to how FakeMeta allows for unregistering of hooks with unregister_forward, HamSandwich will allow you to disable and enable hooks whenever you want.
-The '''RegisterHam''' function will return a handle (tagged with HamHook).  You can then make subsequent calls to DisableHamHook() and EnableHamHook() with the handle to stop it from forwarding, or enable its forwards again.
+The '''RegisterHam''' function will return a handle (tagged with HamHook).  You can then make subsequent calls to DisableHamForward() and EnableHamForward() 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.

@@ Line 1: / Line 1: @@
 == About Ham Sandwich ==
-Ham Sandwich is a module that provides additional hooking and function calling capabilities to [[AMX Mod X]].  It is scheduled to be included with the 1.8 branch of AMX Mod X.
+Ham Sandwich is a module that provides additional hooking and function calling capabilities to [[AMX Mod X]].  It's included with the 1.8 branch of 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.

@@ Line 175: / Line 175: @@
 This means that, for example, if you wanted to make a plugin that halved all damage players take, you would do something like this:
   #include <amxmodx>
-  #include <fakemeta>
+  #include <hamsandwich>
   public plugin_init()
+  {

@@ Line 155: / Line 155: @@
 These natives will get the ''original'' return value from the function.
 * native GetOrigHamReturnInteger(&output);
 * native GetOrigHamReturnFloat(&Float:output);
@@ Line 162: / Line 163: @@
 These natives will change the return value to whatever you please.
 * native SetHamReturnInteger(value);
 * native SetHamReturnFloat(Float:value);

@@ Line 91: / Line 91: @@
+    }
+  }
 == Supported Mods ==

← Older revision		Revision as of 03:34, 11 May 2007
Line 68:		Line 68:

	Fortunately, these instances are kind of rare.		Fortunately, these instances are kind of rare.
		+
		+	==== Config File Requirements ====
		+	Every hook and every ExecuteHam() 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 '''HamFilter'''. 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 HamFilter, and if HamFilter returns '''PLUGIN_HANDLED''', 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 PLUGIN_HANDLED, the plugin will fail.
		+
		+	An example layout for HamFilter:
		+	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;
		+	}
		+	}

	== Supported Mods ==		== Supported Mods ==

← Older revision		Revision as of 03:24, 11 May 2007
Line 169:		Line 169:
	* native SetHamParamString(which, const output[]);		* native SetHamParamString(which, const output[]);
	* native SetHamParamTraceResult(which, tr_handle);		* native SetHamParamTraceResult(which, tr_handle);
		+
		+	=== Disabling Hooks ===
		+
		+	Similar to how FakeMeta allows for unregistering of hooks with unregister_forward, HamSandwich will allow you to disable and enable hooks whenever you want.
		+
		+	The '''RegisterHam''' function will return a handle (tagged with HamHook). You can then make subsequent calls to DisableHamHook() and EnableHamHook() 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.

@@ Line 69: / Line 69: @@
 Fortunately, these instances are kind of rare.
-=== Supported Mods ===
+== Supported Mods ==
-==== Mostly Supported ====
+=== Mostly Supported ===
 These mods have a very large list of functions that are usable in the module.
 * Counter-Strike 1.6
@@ Line 79: / Line 79: @@
 * Natural-Selection
-==== Weakly Supported ====
+=== Weakly Supported ===
 Because these mods do not contain a Linux binary, they are much harder to disassemble.  There is only plans for disassembling two functions for each (TakeDamage and Use).
 * Sven-Coop
 * Earth's Special Forces
-=== Hooking Functions ===
+== Hooking Functions ==
 The big feature for Ham Sandwich is the ability to hook virtual functions.
-==== Creating the Hook ====
+=== Creating the Hook ===
 Creating a hook is a lot like creating a hook in Fakemeta.
@@ Line 107: / Line 107: @@
 Like FakeMeta, there is a hidden last parameter (it goes after the classname in this case).  Set it to 1 to do post hooking.
-==== Blocking the Hook ====
+=== Blocking the Hook ===
 Like Fakemeta and Engine, it is possible to stop a function from being called.  This is called '''superceding'''.
-Blocking in HamSandwich is identical to how it is accomplished in Fakemeta.  In each hook, you return one of four special values:
+Blocking in Ham Sandwich is identical to how it is accomplished in Fakemeta.  In each hook, you return one of four special values:
 * HAM_IGNORED - Nothing happened, the call continues.
@@ Line 119: / Line 119: @@
 You can use the native '''GetHamReturnStatus()''' to check the current return status of the hook.
-==== Return Values ====
+=== Return Values ===
-You can get or change the return values for all the hooks available in HamSandwich.  Look in '''ham_const.inc''' for a list of all hooks and their 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.
@@ Line 143: / Line 143: @@
 * native SetHamReturnString(const value[]);
-==== Changing Hook Parameters ====
+=== Changing Hook Parameters ===
-One feature available in HamSandwich that is not available in FakeMeta is the ability to change all parameters on the fly for each hook.
+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:

@@ Line 104: / Line 104: @@
 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.
 ==== Blocking the Hook ====
@@ Line 140: / Line 142: @@
 * native SetHamReturnEntity(value);
 * native SetHamReturnString(const value[]);