AlliedModders Wiki - User contributions [en]

HamSandwich General Usage (AMX Mod X)

2008-07-21T12:15:02Z

Shaman: /* About Ham Sandwich */

== About Ham Sandwich ==
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.

=== What is a virtual function? ===
A virtual function is a member function of a class in C++. In the case of Ham Sandwich, the virtual function would be a member function of a game entity. The virtual functions deal with various events in game, such as damage, and using entities.

Unlike normal member functions, virtual functions can be changed by class derivatives. For example, a typical hierarchy of entities in Half-Life game dlls look something like this:

CBaseEntity
CBaseAnimating
CBaseMonster
CZombie
CHeadCrab
CBarnacle
CBasePlayer
CBot

Now for example, if CBaseEntity has the virtual function called "FunctionA", and that function does nothing. But, CBarnacle also declares the function "FunctionA", and instead of doing nothing it causes the barnacle to die.

If something like this were to be executed:
CBaseEntity *ent=GET_PRIVATE(entity);
ent->FunctionA();

And the entity were a barnacle, the barnacle would die. If the entity was a zombie, nothing would happen.

=== What are some limitations? ===

Dealing with virtual functions have a couple minor drawbacks.
==== Custom Entities ====
Hooking virtual functions, such as TakeDamage, that get called on custom entities is a little bit awkward.

Because of the way where classes derive, and they get their own virtual table for each class, the type of class that the game dll allocates will be whatever gets hooked for a particular hook.

For example, say you have a plugin like this:

#include <amxmodx>
#include <fakemeta>
#include <hamsandwich>

new myStr;
public plugin_init()
{
myStr = engfunc( EngFunc_AllocString, "info_target" );

register_clcmd( "make_entity", "cmdMakeEntity" );

RegisterHam(Ham_TakeDamage, "damageHook", "MyEntityClass"); // Error!
}
public cmdMakeEntity( id )
{
new ent = engfunc( EngFunc_CreateEntity, myStr );
set_pev( ent, pev_classname, "MyEntityClass" );
// ...
}

That will not work, because the class "MyEntityClass" is not native to the gamedll. Instead, you would need to hook TakeDamage for "info_target", and do some form of parsing on the entities that get passed to it (such as checking classname), if you want to deal with custom entity hooking.

==== End of Chain Derivatives ====
The normal way virtual functions get called is by a virtual table that resides somewhere in the class. A magical index is assigned to each function, and then it looks up the function pointer inside of the virtual table, and executes the required function.

However, compilers are smart enough to optimize away the virtual function lookup if it knows two things about a call:
* The exact class type of the entity.
* That the entity is not derived any further.

An example would be using the hierarchy shown earlier. If, inside of CBot::TakeDamage a call to the virtual function CBot::Killed is made, most compilers will optimize the virtual function lookup out, so that CBot::TakeDamage would then directly call CBot::Killed. This means that the hook would never be called.

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;
}
}

Additionally, you can check to see if a function is valid to execute or hook by using the '''IsHamValid()''' native. The validity of a function is determined when the module is first loaded, and it will never change, so if you want to check it, there is no need to do so before every execute.

== Supported Mods ==
=== Mostly Supported ===
These mods have a very large list of functions that are usable in the module.
* Counter-Strike 1.6
* Condition Zero
* Day of Defeat
* Team Fortress Classic
* The Specialists
* Natural-Selection

=== 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 ==
The big feature for Ham Sandwich is the ability to hook virtual functions.

=== Creating the Hook ===
Creating a hook is a lot like creating a hook in Fakemeta.

#include <amxmodx>
#include <hamsandwich>

public plugin_init()
{
RegisterHam(Ham_TakeDamage, "player_hurt", "player");
}

public player_hurt(this, inflictor, attacker, Float:damage, damagebits)
{
// Stuff...
}

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.

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 ===
Like Fakemeta and Engine, it is possible to stop a function from being called. This is called '''superceding'''.

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.
* HAM_HANDLED - You did something, but the call continues.
* HAM_OVERRIDE - The call will still be executed, but instead you will change the return value.
* HAM_SUPERCEDE - The call is not executed, and you use your return value, if applicable.

You can use the native '''GetHamReturnStatus()''' to check the current return status of the hook.

=== 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.
* native GetHamReturnInteger(&output);
* native GetHamReturnFloat(&Float:output);
* native GetHamReturnVector(Float:output[3]);
* native GetHamReturnEntity(&output);
* native GetHamReturnString(output[], size);

These natives will get the ''original'' return value from the function.
Note that this is '''only''' valid to call in a post hook, it will be undefined to call it at any other time.
* native GetOrigHamReturnInteger(&output);
* native GetOrigHamReturnFloat(&Float:output);
* native GetOrigHamReturnVector(Float:output[3]);
* native GetOrigHamReturnCbase(&output);
* native GetOrigHamReturnString(output[], size);

These natives will change the return value to whatever you please.
Note that this will have no effect on the actual return value from the function '''unless''' the return status of the hook is HAM_OVERRIDE or HAM_SUPERCEDE.
* native SetHamReturnInteger(value);
* native SetHamReturnFloat(Float:value);
* native SetHamReturnVector(const Float:value[3]);
* native SetHamReturnEntity(value);
* native SetHamReturnString(const value[]);

=== Changing Hook Parameters ===
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:
#include <amxmodx>
#include <hamsandwich>
public plugin_init()
{
RegisterHam(Ham_TakeDamage, "player_hurt", "player");
}
public player_hurt(this, inflictor, attacker, Float:damage, damagebits)
{
SetHamParamFloat(4, damage / 2.0);
return HAM_HANDLED;
}

All hooks after the one you change them in will see the modified values. Hooks are executed in the order in which they are registered.

All available parameter changing natives are:

* native SetHamParamInteger(which, value);
* native SetHamParamFloat(which, Float:value);
* native SetHamParamVector(which, const Float:value[3]);
* native SetHamParamEntity(which, value);
* native SetHamParamString(which, const output[]);
* 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.

SourceMod 1.0.2 Release Notes

2008-06-01T01:21:39Z

Shaman: Team Fortress -> Team Fortress 2

__FORCETOC__

SourceMod 1.0.2 is a feature and bug-fix upgrade from 1.0.1. If you need help upgrading, see [[Upgrading SourceMod]].

*[[Image:checkmark.gif]] '''All old plugins and extensions will continue to work.'''
*[[Image:checkmark.gif]] '''This release has new config files, but no config changes.'''
*[[Image:badmark.gif]] '''Config files introduced during the beta period have been changed (see notes).'''
*[[Image:badmark.gif]] '''This release has one very minor compatibility change.'''
*[[Image:checkmark.gif]] '''This release has no translation changes.'''
<br />

=Custom Admin Menu=
Also known as the "dynamic admin menu," the admin menu now has a much greater degree of customization. Server administrators can add new entries onto the menu via configuration files. For more information, see [[Custom Admin Menu (SourceMod)]].

=TF2 Extension=
The TF2 extension adds scripting functionality to servers running Team Fortress 2. It also adds two new multi-targets for admin commands:
*@red - Everyone on the red team
*@blue - Everyone on the blue team

The new scripting functionality is split into [http://docs.sourcemod.net/api/index.php?fastload=file&id=49& natives] and [http://docs.sourcemod.net/api/index.php?fastload=file&id=50& stocks].

=RegEx Extension=
The new regular expression extension adds scripting features for text pattern matching. You can view the new API [http://docs.sourcemod.net/api/index.php?fastload=file&id=52& here].

=Entity Output Hooking=
Entity outputs are delayed inputs from one entity to another. This system allows maps to queue actions on certain entities. When a specific action happens, the queue is emptied, and all of the inputs are fired.

SourceMod now allows scripts to intercept when these events fire. This is a powerful feature that lets plugins listen for very specific events, for example, when a door opens (class CDoor, event "OnOpen").

The API for this is [http://docs.sourcemod.net/api/index.php?fastload=file&id=51& here].

=Map Config Helper=
There is a new forward, [http://docs.sourcemod.net/api/index.php?fastload=show&id=852& OnAutoConfigsBuffered], for map config plugin authors. Using [http://docs.sourcemod.net/api/index.php?fastload=show&id=582& OnConfigsExecuted] to run config files is a mistake, because config files must be guaranteed to have already loaded by that point in time, and [http://docs.sourcemod.net/api/index.php?fastload=show&id=454& ServerCommand] is delayed.

Plugins with this mistake were notified a few weeks ago, and with this release, authors should make sure they fix any conflicts.

=Changes=
*The admin menu is now user-modifiable (the "Dynamic Admin Menu").
*Added a TF2 extension with Team Fortress 2 functions.
*Added a RegEx extension with regular expression functions.
*Added functions to SDKTools for hooking entity outputs.
*Added preliminary support for the DoD:S Orange Box beta.
*Added a forward for map config plugins for preventing race conditions.
*Added a %b format specifier for binary printing.
*Added sm_dump_datamaps command (SDKTools) for enumerating datamap properties.
*Added sm_dump_admcache command for debugging the admin cache.
*Added {{amb|1715}} - TraceHull functions to SDKTools (complementing TraceRay).
*Added {{amb|1694}} - FindCharInString() function.
*Added {{amb|1685}} - GetTickInterval() function.
*Added {{amb|1620}} - ActivateEntity() function to SDKTools (for Orange Box particle system).
*Added {{amb|1610}} - StripQuotes() function.
*Added {{amb|1558}} - Compiler now has __BINARY_PATH__ and __BINARY_FILE__ macros.
*Fixed {{amb|1686}} - ReplaceString* with an empty search string crashed; it now throws an error instead.
*Fixed {{amb|1684}} - Blank passwords required an existing but empty setinfo password.
*Fixed {{amb|1595}} - Extension load failures did not show a platform error message.
*Fixed {{amb|1583}} - MySQL string fetch from prepared queries returned corrupted data.
*Fixed {{amb|1358}} - Timeleft did not reset on TF2 restarts.
*Fixed cases where the JIT was too cautious in space optimizations.
*Fixed TF2/Cstrike extensions being loadable on incompatible games.
*Fixed various documentation inconsistencies and typos.
*Fixed internal bugs with file extension handling.

=Notes=
==Blank Passwords==
There is a possible compatibility regression from {{amb|1684}}. SetAdminPassword() has been modified to remove any set password when given an empty string. Previously, a blank password ("") would force an admin to use "setinfo" to set an empty password, but this functionality was deemed unuseful and unintended. Blank passwords now remove any set password.

==Moved Config Files==
Two files were moved during the shift from beta to release. These files were introduced during the beta cycle and thus this modification is not considered a compatibility change. Nonetheless, there is a compatibility shim for this change.

*'''configs/dynamicmenu/adminmenu_grouping.txt''' is now '''configs/adminmenu_grouping.txt'''
*'''configs/dynamicmenu/menu.ini''' is now '''configs/adminmenu_custom.txt'''
*'''configs/dynamicmenu has been removed'''

Temporary compatibility is as follows: If any older file exists, it is loaded instead of the new file. If an old file cannot be found, the new file is loaded instead. This compatibility shim will be removed from all branches next release.

==DoD:S Beta Support==
Since DoD:S Orange Box is a beta, its SDKTools support is experimental only. It will be officially supported when DoD:S Orange Box is officially released.

==Web Compiler==
The web compiler has been updated to build 1.0.2-compatible plugins. Old SourceMod installations will be able to run these plugins as long as no new functionality is used.

==Removed TF2 Stocks==
More broken TF2 stocks have been removed. There are no compatibility shims for them.
*TF2_GivePlayerWeapon
*TF2_EquipPlayerClassWeapons
*TF2_SetPlayerClass's third parameter is now ignored

These functions may be restored in full if workarounds can be found.

=Support Schedule=
SourceMod 1.0.2 replaces SourceMod 1.0.0, and 1.0.0 is no longer supported.

SourceMod 1.0.1 will continue to be supported, however, all bug fixes will occur in the 1.0.3 branch (which includes all changes in 1.0.2). Support for 1.0.1 will stop when 1.0.3 is released.