Difference between revisions of "User:Nosoop/Guide/Advanced"
m (→Finding VTable Offsets: Add note on how vtables are stored) |
m (Move →Finding Functions: to the top of the page) |
||
Line 2: | Line 2: | ||
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. | 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 = | = Finding VTable Offsets = | ||
Line 31: | Line 39: | ||
There are instances where the dumper isn't correct (such as for multiple inheritance), so you may need to be careful in those cases. | 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 = | = Creating Signatures = |
Revision as of 03:50, 3 December 2021
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.
Contents
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
- 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"
Calling Game Functions
SDKCall Order
When performing an SDKCall
, the parameters need to be passed in the following order:
- The SDKCall handle received from
EndPrepSDKCall
. - 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.
- 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.
- Any remaining parameters for the function.