Fallout 4 Script Extender (F4SE)

To build f4se, you must first clone and build the common dependency. The build process uses CMake to configure the projects and generate a Visual Studio solution.

1. Clone both the common and f4se repositories.
2. Build and install common into an extern directory.
3. Configure and build f4se using the extern directory for dependencies.

The resulting Visual Studio solution will be located at f4se/build/umbrella.sln.

git clone https://github.com/ianpatt/common
git clone https://github.com/ianpatt/f4se
cmake -B common/build -S common -DCMAKE_INSTALL_PREFIX=extern common
cmake --build common/build --config Release --target install
cmake -B f4se/build -S f4se -DCMAKE_INSTALL_PREFIX=extern f4se
cmake --build f4se/build --config Release

The f4se_steam_loader is a DLL designed to be injected into the Fallout 4 process (specifically the Steam version) to facilitate the loading of F4SE.

It follows this lifecycle:

1. DLL Attachment: Upon DLL_PROCESS_ATTACH, it initializes a debug log in %USERPROFILE%\Documents\My Games\Fallout4\F4SE\f4se_steam_loader.log.
2. IAT Hooking: It performs an Import Address Table (IAT) hook on __crtGetShowWindowMode from MSVCR110.dll. This is used as a trigger to execute code early in the process lifecycle.
3. Code Injection: When the hooked function is called, HookMain is triggered. This function identifies the correct F4SE DLL (either f4se_*.dll or f4se_editor_*.dll) based on whether the running executable is the game or the Creation Kit editor, and then calls LoadLibrary to load the actual F4SE runtime.

The EarlyTerminationHandler class is used to manage the lifecycle of the target process and ensure that if the loader receives a termination signal (like a console control event), the target process is also terminated.

It works by registering a HandlerWrapper with SetConsoleCtrlHandler. When a termination signal is received, the Handler method is called, which executes TerminateProcess on the managed process handle.

To use it, you call .start(HANDLE proc) to begin monitoring a process and .stop() to unregister the handler and stop monitoring.

EarlyTerminationHandler handler;
handle = OpenProcess(...);
handler.start(handle);
// ... later ...
handler.stop();

The AugmentEnvironment function prepares the environment for the target process by setting specific environment variables that the F4SE DLL will require. It takes the full path to the process (procPath) and the full path to the DLL (dllPath).

It sets the following environment variables:

• F4SE_DLL: The filename of the F4SE DLL.
• F4SE_RUNTIME: The filename of the target process executable.
• F4SE_WAITFORDEBUGGER: Set to "1" if g_options.m_waitForDebugger is true, otherwise "0".

void AugmentEnvironment(const std::string& procPath, const std::string& dllPath)

The F4SE binary includes versioning information embedded in its resource file. When inspecting the compiled DLL or component, the following metadata fields are used to identify the specific version and purpose:

• FileDescription: A component of the Fallout 4 Script Extender
• InternalName: F4SE
• ProductName: F4SE
• FileVersion: Derived from F4SE_VERSION_VERSTRING
• ProductVersion: Derived from F4SE_VERSION_VERSTRING

If you are troubleshooting version mismatches, ensure the FileVersion reported by the OS or file properties matches the expected version of your F4SE installation.

The entry point for the f4se_steam_loader DLL. It handles the DLL_PROCESS_ATTACH event to trigger the OnAttach sequence, which sets up logging and begins the IAT hooking process.

BOOL WINAPI DllMain(HANDLE procHandle, DWORD reason, LPVOID reserved)
{
	if(reason == DLL_PROCESS_ATTACH)
	{
		g_dllHandle = procHandle;
		OnAttach();
	}

	return TRUE;
}