User:Nosoop/Guide/Advanced

This section is provided for users that want or need to work with game-specific functionality that SourceMod doesn't provide access to out of the box.

It's assumed that you're comfortable with programming and various terms. By the end of this page you'll have some knowledge of calling / hooking arbitrary functions in the game.

Finding Functions

• TODO refer to public SDK if you don't know what you're looking for
• TODO explain what to do in a game with symbols
• TODO suggest opening IDA's options and enabling opcode bytes
• TODO inlined functions
• TODO debugging

Finding VTable Offsets

In C++, a virtual method table (shorthand "vtable") is effectively an array of function pointers. It's intended for inheritance — a virtual ::DoThing() method can be different for different classes, and so the code will look up the correct function for a specific instance based on the table for the instance's class. Every class that uses a vtable will hold a reference to it as one of its properties.

The Hard Way

Note:This section is a work-in-progress.

• TODO count offsets in IDA

If you're familiar with the code or have sources to cross-reference against, you can search for the virtual call itself. In a Linux disassembly, it will look something like this:

; get the first vtable by dereferencing the pointer at the start of the class instance
8B 03       mov  eax, [ebx]

; push the class instance as a parameter
89 1C 24    mov  [esp], ebx

; call the fourth entry in the vtable: 0xC / sizeof(void*) = 0x3, off-by-one
Ff 50 0C    call dword ptr [eax+0Ch]

The Easy Way

If the game isn't stripped of debugging symbols, use asherkin's VTable Dumper. It provides correct offsets for Linux binaries (as it's what it works with), and estimates usually correct offsets for Windows.

There are instances where the dumper isn't correct (such as for multiple inheritance), so you may need to be careful in those cases.

Creating Signatures

The Hard Way

After you've found a function, you need to tell SourceMod the sequence of bytes unique to it. Those bytes make up a signature.

You could treat just the sequence bytes as the signature directly, but this would break very easily whenever the game is updated. At the machine-code level, the instructions might be the same for "move X to Y", but the data might change — X and Y might be in a different location in the binary altogether. For an example within a longer signature:

; sets esp to the offset aString
; the bytes 3B B3 25 01 are the absolute offset of aString in this binary
C7 04 24 3B B3 25 01    mov     dword ptr [esp], offset aString

; call function, the four bytes after E8 are the location of the function
E8 78 F0 48 00          call    _Z12UTIL_VarArgsPKcz

; sets eax to arg 0
8B 45 08                mov     eax, [ebp+arg_0]

The naive signature for that would be \xC7\x04\x24\x3B\xB3\x25\x01\xE8\x78\xF0\x48\x00\x8B\x45\x08. However, you can't rely on those bytes mentioned to be constant at all; the offsets of aString and UTIL_VarArgs might be located somewhere else after a game update.

As a solution to this, you use wildcards to mask off the bytes you don't care about. For SourceMod game config files, the sequence \x2A indicates that particular byte shouldn't be checked and to continue to the next one.

Here is what the previous signature looks like with the masked bytes displayed as ??:

C7 04 24 ?? ?? ?? ??    mov     dword ptr [esp], offset aString
E8 ?? ?? ?? ??          call    _Z12UTIL_VarArgsPKcz
8B 45 08                mov     eax, [ebp+arg_0]

A masked signature would then be \xC7\x04\x24\x2A\x2A\x2A\x2A\xE8\x2A\x2A\x2A\x2A\x8B\x45\x08.

Masking is used mainly for offsets, such as for functions and variables. Instructions generally don't change unless the function code itself is modified, at which point you'll want to revisit your binary and update accordingly.

If you're using DHooks with byte signatures (covered later), you may want to also mask out the first six bytes, as a detour will patch in an unconditional JMP at the start to trampoline into a user-defined function, and subsequent scans for the byte signature will fail.

For an extended lesson, you can look at the following material:

• Signature Scanning on the AlliedModders wiki

The Easy Way

If you're using IDA (including Free), use the makesig.idc script. If you're using Ghidra, use makesig.py.

They generally do pretty well at finding and masking byte signatures, but when it fails or you want a more robust signature, you should understand how to create the signatures manually.

It's exceedingly rare, but possible that the binary has two copies of the exact same short function (for example, when they are typechecked and statically casted to different subclasses). Both scripts will fail in that case. SourceMod's signature scanner will use the first match it finds, so if any match is acceptable, you can still use an appropriately masked signature.

Be sure to look at the disassembly to make sure that the functions are indeed the same.

Finding Addresses

Sometimes you have a symbol, but you need an address to work with. That is what the "Addresses" section of a game configuration file is used for.

To find an address, you start from a known location reference (signature). You may then have to jump to references (that is, dereference locations), then get an offset from the previous reference.

read keys indicate an offset to load / dereference relative to the previous address, and offset means to shift the previous address without any dereference.

For a C++-like example:

// start from an address
uintptr_t addr = FindLocation("some_signature");
addr = *reinterpret_cast<uintptr_t*>(addr + 40); // gameconf: "read" "40"
addr = *reinterpret_cast<uintptr_t*>(addr); // gameconf: "read" "0"
addr += 13; // gameconf: "offset" "13"

Note:This section is a work-in-progress.

Calling Game Functions

Note:This section is a work-in-progress.

SDKCall Order

When performing an SDKCall, the parameters need to be passed in the following order:

1. The SDKCall handle received from EndPrepSDKCall.
2. The this instance. this may be omitted in the following cases:
   • The function was declared as static, where there is no this to pass in.
   • The function was declared with the SDKCall_GameRules or SDKCall_EntityList call types; SDKTools itself will provide the appropriate global instance.
3. The return buffer. If the function returns a Vector or QAngle, the parameter is a float[3]. If the function returns a char*, the parameters should be a char[] buffer and an int specifying the size of the buffer. If the function returns a primitive type / entity / edict, it will be the return value of the SDKCall, so no such return buffer is necessary.
4. Any remaining parameters for the function.

Hooking Game Functions (with DHooks)

Note:This section is a work-in-progress.