Hooking

Hooking is a C++ exclusive feature of SML that allows you to attach a custom function body to a existing function.

All C/C++ functioning hooking stuff can be found in #include "Patching/NativeHookManager.h". All Blueprint function hook stuff can be found in #include "Patching/BlueprintHookManager.h".

C/C++ Function Hooks

The hooking interface provides distinct 3 ways of hooking functions, each of which have two types of call order.

If multiple hooks are attached to the same function, these hooks will then get called in the order they were registered.

There is a normal hook which gets called before the actual function gets called. Through this hook you are able to prevent the final function call and you are also able to overwrite the return value. If you cancel the execution of the final function, you can prevent the following hooks from being called. Keep in mind that this means that another hook can prevent your hooks from being called by Satisfactory. The normal hook’s signature is void(TCallScope<HookFuncSignature>&, hookFuncParams). If you hook a member function, the this pointer is handled like a parameter and is the first parameter used. As long as you don’t cancel the final function execution, or do it yourself by calling the scope object, the final function will be implicitly called after your hook function returns.

Sometimes when hooking functions that return custom types such as structs and FStrings, the game can unexpectedly crash! The cause of this is not fully known and often depends on the function being hooked. As such, try to avoid hooking functions that return said custom types wherever possible.

The call scope object allows you to:

  • Cancel the final function execution (if the hook function returns void).

    void hook(TCallScope<...>& Scope, class* exampleClass, int exampleArg)
     scope.Cancel();
    }
  • Call the next hooks and the final function within your body. Calling the scope need to have all the same parameters as the func hook signature.

    void hook(TCallScope<int(int)>& Scope, class* exampleClass, int exampleArg)
    	// stuff before final function call
    	int result = scope(exampleClass, exampleArg); // call following hooks (final function might get called as long as following hooks don't cancel/overwrite it)
    	// stuff after final function call
    }
  • You can also override the return value before the final call (causes the final call to not occur)

    void hook(TCallScope<int(int)>& Scope, class* exampleClass, int exampleArg)
    	// final function might get called
    	scope.Override(customReturnValue);
    	// final function wont get called anymore
    }

Since you still want to make sure your hook gets called, no care about if the final function got called or not we introduce the "after" hooks. These hooks get all called after the normal hook calls and only allow you to read the parameters as well as the resulting return value. That means you can’t influence the final function call. Also, don’t use the TCallScope object, instead the first parameter of your hooks signature is the return value following by the function call parameters.

void hook(int returnValue, int exampleArg) {
	// do some stuff
}

The 2 Types of Hooks

By 'hook types' we mean the different ways of attaching a hook to a function. Each attachment method works differently under the hood, and it’s important to pay attention to the key differences between the different types of hooks.

Be aware that type of return values and parameters etc has nothing to do with each other or if it is a member function, you can use them in any way. Note that the Hook function is a std::function, which means that it can be any type a std::function can accept, such as function pointers, function pointers with bound placeholders, or even lambdas.

If your mod is not C++ only, meaning it is Blueprint and C++, you should surround your hook functions with #if !WITH_EDITOR, remembering to place #endif after the end of your hook function. Failure to do so may prevent the Unreal Editor from opening.

Type: SUBSCRIBE_METHOD

The SUBSCRIBE_METHOD-Macro attaches a hook to the given function passed by pointer. SML will take that function pointer and find the symbol name so bootstrapper can then redirect the function calls for that symbol to SML’s hook framework.

Usage goes as following:

#include "Patching/NativeHookManager.h"

class SomeClass {
public:
	int MemberFunction(int arg1);
	static void StaticFunction();
}

void registerHooks() {
	SUBSCRIBE_METHOD(SomeClass::MemberFunction, [](auto& scope, SomeClass* self, int arg1) {
		// do some nice stuff there
	});

	SUBSCRIBE_METHOD(SomeClass::StaticFunction, [](auto& scope) {
		// do some nice stuff there
	});
}

Hooking an overloaded function might not work as intended since the compiler has no clue what exact symbol you now want to hook. For that you should have an look at the SUBSCRIBE_METHOD_MANUAL-Macro which allows you to explicitly set the symbol you want to hook.

Type: SUBSCRIBE_METHOD_VIRTUAL

The SUBSCRIBE_METHOD_VIRTUAL-Macro attaches the given hook to the given function passed by pointer in the virtual table of the given class. This happens by SML reading the function symbol and class name so bootstrapper can then change the the virtual table entry to the proper function of the SML hooking framework.

That also means, you change the virtual table of only the given table, if you allow want to change the virtual table entry of other classes you need to hook them separately.

Usage goes as following:

#include "Patching/NativeHookManager.h"

class SomeClass {
public:
	virtual int MemberFunction(int arg1);
}

class SomeChild : public SomeClass {
public:
	virtual int MemberFunction(int arg1) override;
}

void registerHooks() {
	SUBSCRIBE_METHOD_VIRTUAL(SomeClass::MemberFunction, SomeClass, [](auto& scope, SomeClass* self, int arg1) {
		// do some nice stuff there
	});

	SomeClass parent;
	parent->MemberFunction(0); // hook gets called
	SomeChild c;
	c->MemberFunction(1); // hook does not get called
}

Special Cases

Depending on the type of function you are attempting to hook and what you want to do with it, you may need to make some adjustments.

Const Functions

When hooking a const function you will need to prefix the "self" pointer with const.

Non-Const Function

(auto& scope, SomeClass* self)

Const Function

(auto& scope, const SomeClass* self)

Hooking AFTER

For "after" hooks, add the _AFTER postfix to the macro names.

Be aware that the hook function signature changes accordingly and will no longer need the "scope":

Non-Virtual

SUBSCRIBE_METHOD_AFTER(SomeClass::MemberFunction, [](SomeClass* self)

Virtual

SUBSCRIBE_METHOD_VIRTUAL_AFTER(SomeClass::MemberFunction, [](SomeClass* self)

FORCEINLINE Functions

Functions that are FORCEINLINE cannot be hooked.

UFUNCTIONs

A function being a UFUNCTION or not makes no difference on whether it can be hooked.

Unhooking

Unhooking functionality has not been extensively tested. Please report issues you encounter on the Discord.

Macros will return a delegate that can be used with the UNSUBSCRIBE_METHOD or UNSUBSCRIBE_UOBJECT_METHOD macro respectively in order to unsubscribe from the function.

Blueprint-Hooking

Blueprint function hooking works by changing the instructions of a Blueprint UFunction so that first your hook gets called.

The hook function signature is void(FBlueprintHookHelper&). This helper structure provides a couple of functions allowing you to read and write data to local function (including parameters), output parameters and accessing the context pointer.

You can attach a hook with the HookBlueprintFunction-Macro which takes a pointer to the UFunction you want to attach the hook to.

Usage goes as following:

#include "Patching/BlueprintHookManager.h"

void registerHooks() {
	UClass* SomeClass = ...;
	UFunction* SomeFunc = SomeClass->FindFunctionByName(TEXT("TestFunc"));

	HookBlueprintFunction(SomeFunc, [](FBlueprintHookHelper& helper) {
		UObject* ctx = helper.GetContext(); // the object this function got called onto
		FString* localStr = helper.GetLocalVarPtr<FString>("StrVariable"); // getting the pointer to a local variable
		FString* output = helper.GetOutVariablePtr<FString>("OutValue"); // getting the pointer to a output variable
		// do some nice stuff there
	});
}

You can also provide a count of instruction as third parameter to hook as instruction based offset from the top. But we highly encourage you to not do so unless you know what you exactly do!

Protected/Private Function Hooking

If the function you are attempting to hook is protected or private to that specific class, you must use the friend declaration.

This also means that you can only hook this function from a class, not global scope.

For example, let’s assume you have a class called MyWatcher in a namespace called MyMod, and you wish to hook the function EnterChatMessage from AFGPlayerController class.

The suggested method of doing this is with Access Transformers. In your AccessTransformers.ini file you would create the entry:

Friend=(Class="AFGPlayerController", FriendClass="MyWatcher")

Alternatively, you can edit the header files directly. This is not advisable for reasons described in more detail on the Access Transformers page. You must first edit the FGPlayerController.h header and add the following block of code to it:

namespace MyMod
{
    class MyWatcher;
}

Then you have to add the friend declaration to the class itself, in result, it should look like this:

...

class FACTORYGAME_API AFGPlayerController : public AFGPlayerControllerBase
{
	GENERATED_BODY()
public:
	friend MyMod::MyWatcher;

...