SourceMod DevLog

Let’s look at a basic example function first:

 public String:junk(id) 
{
     new String:stuff = string("Data:") 
     for(new x=0; x<4; x++) 
     {
           strnCat(stuff, x)
     }
     return stuff; 
}

All this crazy function does is return “Data:0123″. Now let’s look at what happens with the dynamic string while this function runs.

We declare the string like this:

But what if your plugin has pre-allocation turned on?

- Each time a string expands in size it needs more space in the computer’s memory, it can’t simply request more space directly after its current space, it has to delete everything and start over. This process is time consuming. If pre-allocating is turned on then all strings start off with an invisible “buffer” zone to allow strings to expand a little without having to re-allocate that string.

We now have 1/3rd more space allocated before the string has to be re-created in memory. But this isn’t good enough for our unusual function above (The empty characters at the end are not spaces, they are nothing/NULL). The string would still have to be allocated / destroyed a total of three times in this call.

In situations when the following is true
1. The programmer knows exactly how much space they will need
2. That space is more than 1/3rd the strings original size

Then the following natives are of use –
pString(num) – Pre-Allocate string
pCString(const word[], num) – Pre-Allocate + Data

Here is our code again with an improvement:

 public String:junk(id) 
{
     new String:stuff = pCString("Data:", 9) 
     for(new x=0; x<4; x++) 
     {
           strnCat(stuff, x)
     }
     return stuff; 
}

When the string is first created it is done so with 9 characters so it only needs to be allocated a single time and thus the function runs faster.

Try to keep in mind that the 9 character allocation is _NOT_ the same as a character array size, if you try and put a 10th character in this string it will work fine but behind the scenes it will have to completely re-allocate a new string to hold all ten characters.

No, I didn’t really like Matrix Realoded, and the original Matrix was much better, but in case of SourceHook, it is the other way round.

As you may know, my original SourceHook, an easy-to-use virtual-function hooking framework, was only able to hook interfaces that are available on startup, before anything is initialized, that is, exposed by the engine or the gamedll. That was a big limitation, so I decided to remove it. I have also added support for overloaded functions. Many things have changed, and so has the SourceHook API.

Interface declarations
Right. This is the shif_*.h stuff. Two changes in here:
1) You have to #define __SH_DYNAMIC to true or false before specifying SH_FUNCDECL_BEGIN.
2) The SH_FUNCDECL* macros have a new parameter.

Let’s look at these in detail:
1) If you #define __SH_DYNAMIC to false, SourceHook loads the interface on Initialization. For this, it uses the good old __SH_GETINTERFACE macro you also have to #define. Usually, for things like IVEngineServer, it looks like this:

#define __SH_DYNAMIC false
#define __SH_GETCURINTERFACE (IVEngineServer*)g_SM_HL2Connector.GetInterfaceFn()(INTERFACEVERSION_VENGINESERVER, NULL)

If you #define __SH_DYNAMIC to true, it means that the interface is not loaded on statup. You still have to #define __SH_GETCURINTERFACE to something although it’s unused; I use NULL.

2) The new parameter is the so called overload. Consider this interface:

class IGaben
{
public:
   virtual void EatYams(const char *location) = 0;  // Eats all yams from location
   virtual void EatYams(const char *location, int amount) = 0; // Only eats amount of yams from location

   virtual void Vomit() = 0; // Too many yams :X
};

When SourceHook builds the VTable struct and the delegate/function pointer typedefs, it needs an unique name for each function. That’s why the overload parameter was added. It is simply appended to everything that needs to have an unique name. You would do something like this in your interface declaration:

SH_FUNCDECL1_void(EatYams, 0, SH_NOATTRIB, const char*)
SH_FUNCDECL2_void(EatYams, 1, SH_NOATTRIB, const char*, int)

SH_FUNCDECL0_void(Vomit, 0, SH_NOATTRIB)

Note that this is the only place where you need to specify the overload parameter – when hooking functions, the compiler decides which one to hook depending on the type if the function you pass. (If you pass a type that does not correspond to any overloaded function, you get some weird error)

Usage
There are a few changes with the macros:
SH_HOOK_STATICFUNC and SH_HOOK_MEMBERFUNC remain the same; so do SH_REMOVE_STATICFUNC and SH_REMOVE_MEMBERFUNC.

The old SH_GET_CALLCLASS is now SH_GET_CALLCLASS_STATIC.

The SH_ADDINTERFACE and SH_REMOVEINTERFACE macros are new. They hook/unhook an interface pointer:

   SH_ADDINTERFACE(GetInterfaceFunc, Interface, Pointer);
   SH_REMOVEINTERFACE(GetInterfaceFunc, Interface, Pointer, reset);

GetInterfaceFunc is, as always, SourceMod’s GetInterface function; Interface is suprisingly the interface, and pointer is a pointer to an instance. SH_REMOVEINTERFACE also has a fourth bool parameter, reset. If this is set to true, the VTable is reset to its original values. Note that this is not necessary, but it should be done if you can ensure that the Pointer is not destroyed yet.

Also note that we do not reprotect vitual function tables anymore. Damaged Soul has found out that this can also reprotect other other vtables in the same page, which leads to crashes when we try to access it later. Thanks!

Ok, so what now, after you have called SH_ADDINTERFACE on some pointer? You can start hooking! It actually works the same way the “normal” hook functions work, but these have a new parameter:

#define SH_GET_CALLCLASS(GetInterfaceFunc, Interface, InterfacePointer)
#define SH_HOOKDYNAMIC_STATICFUNC(GetInterfaceFunc, Interface, InterfaceFunction,
   InterfacePointer, YourFunction, Post)
#define SH_HOOKDYNAMIC_MEMBERFUNC(GetInterfaceFunc, Interface, InterfaceFunction,
   InterfacePointer, YourInstance, YourMemberFunction, Post)
#define SH_REMOVEDYNAMIC_STATICFUNC(GetInterfaceFunc, Interface, InterfaceFunction,
   InterfacePointer, YourFunction)
#define SH_REMOVEDYNAMIC_MEMBERFUNC(GetInterfaceFunc, Interface, InterfaceFunction,
   InterfacePointer, YourInstance, YourMemberFunction)

I think these are pretty self-explaining. Don’t forget to SH_REMOVEINTERFACE after you are done.

I have also added a new macros that can be used from handlers: META_IFACEPTR. The value of this macros is the pointer to the interface that was meant to be called.

Here is a small illustration of dynamic hooking:

class OMGOMGOMG : public ConCommandBase
{
public:
	bool IsCommand()
	{
		SM_LOG("OMGOMGOMG::IsCommand called. Returning true. this=%p", this);
		return true;
	}
};
OMGOMGOMG g_Lol1;
OMGOMGOMG g_Lol2;

class OLOLHOOK
{
public:
	bool IsCommandHook()
	{
		if (META_IFACEPTR == &g_Lol1)
		{
			SM_LOG("IsCommandHook called; ptr=%p => superceding with true", META_IFACEPTR);
			RETURN_META_VALUE(MRES_SUPERCEDE, true);
		}
		else
		{
			SM_LOG("IsCommandHook called; ptr=%p => overriding with false", META_IFACEPTR);
			RETURN_META_VALUE(MRES_OVERRIDE, false);
		}
	}
};
OLOLHOOK g_omgomg;


// This is neccessary so the compiler is not too clever and does not bypass the vtable lookup
ConCommandBase *lol1 = &g_Lol1;
ConCommandBase *lol2 = &g_Lol2;

SH_ADDINTERFACE(GetInterface, ConCommandBase, lol1);
SH_ADDINTERFACE(GetInterface, ConCommandBase, lol2);

SH_HOOKDYNAMIC_MEMBERFUNC(GetInterface, ConCommandBase, IsCommand, lol1, &g_omgomg,
   &OLOLHOOK::IsCommandHook, false);
SH_HOOKDYNAMIC_MEMBERFUNC(GetInterface, ConCommandBase, IsCommand, lol2, &g_omgomg,
   &OLOLHOOK::IsCommandHook, false);

SM_LOG("g_Lol1.IsCommand() = %d", lol1->IsCommand() ? 1 : 0);
SM_LOG("g_Lol2.IsCommand() = %d", lol2->IsCommand() ? 1 : 0);

This example produces this log output:

L 02/07/2005 - 15:13:56: [SM] IsCommandHook called; ptr=06DF166C => superceding with true
L 02/07/2005 - 15:13:56: [SM] g_Lol1.IsCommand() = 1
L 02/07/2005 - 15:13:59: [SM] IsCommandHook called; ptr=06DF16E4 => overriding with false
L 02/07/2005 - 15:13:59: [SM] OMGOMGOMG::IsCommand called. Returning true. this=06DF16E4
L 02/07/2005 - 15:13:59: [SM] g_Lol2.IsCommand() = 0

SourceMod’s Scripting Framework can potentially adapt to many languages. How does this work out in terms of us supporting them?

C++ is the “official” native language of SourceMod. It’s also how we’re writing the base admin plugin.

The official supported scripting language is “JavaScript”, implemented by Mozilla’s SpiderMonkey. The MetaEngine for it, and the associated base connector and documentation, will be maintained by developer Blaubaer.

Finally, we’ve made a MetaEngine for “AMX/Small”. The core of this is a direct copy from AMX Mod X, so things like error tracing will remain the same. This is considered DEPRECATED and UNSUPPORTED. As Manip posted a few entries ago, he is the official maintainer for it, giving him a chance to play around with some new ideas.

On another note, you may remember the specialized plugin forums from www.amxmodx.org – I’m hoping to somehow acquire a vBulletin license (maybe some kind soul will donate one or money for one ), because there’s no way in hell I’m rewriting those hacks for phpBB again – the codebase is absolutely awful. It would also give me (or rather: Freecode) a chance to port our almost-ugly SourceMod theme. That’s up in the air though, but it would be nice to have good forum software before the first major release.