HamSandwich General Usage (AMX Mod X)

About Ham Sandwich

Ham Sandwich is a module that provides additional hooking and function calling capabilities to 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.