Fallout4F4SEModTemplate/README.md

F4SEPluginTemplate

Minimal reusable Fallout 4 F4SE plugin template using CommonLibF4.

This template is intentionally lightweight. Add project-specific dependencies such as Ultralight, GameNetworkingSockets, ImGui, or custom SDKs inside each actual mod repo instead of adding them here.

Requirements

• Windows
• Visual Studio 2022 with C++ tools, or another MSVC/Clang-CL C++23 toolchain
• xmake 3.0.0 or newer
• Git
• Fallout 4 Script Extender installed for testing

Create a new mod repo from this template

git clone <your-template-repo-url> MyNewF4SEMod
cd MyNewF4SEMod
git submodule update --init --recursive
.\scripts\rename-template.ps1 -NewName "MyNewF4SEMod" -Author "YourName"

Then commit the renamed version as the starting point for the new mod.

Build

xmake build

The built plugin is copied to:

package/F4SE/Plugins/

Generate Visual Studio project

xmake project -k vsxmake

Package for mod managers

.\scripts\package.ps1 -OutputName "MyNewF4SEMod"

This creates a zip with the expected layout:

F4SE/Plugins/MyNewF4SEMod.dll
F4SE/Plugins/MyNewF4SEMod.pdb

Dev install to Fallout 4

.\scripts\install-dev.ps1 -Fallout4Path "C:\Program Files (x86)\Steam\steamapps\common\Fallout 4"

Repo layout

src/                  C++ plugin source
include/              Public/internal headers
ThirdParty/CommonLibF4/      CommonLibF4 submodule
package/              Staged mod-manager package output
scripts/              Helper scripts

Optional Modules

This template intentionally keeps the base plugin minimal. Only add extra third-party modules when a specific mod needs them.

The recommended convention is to place optional dependencies in ThirdParty/:

ThirdParty/
├─ CommonLibF4/
├─ xbyak/
├─ Ultralight-SDK/
├─ framework-F4-Conversion/
├─ spdlog/
└─ tomlplusplus/

Xbyak

Use Xbyak when the plugin needs low-level hook helpers, runtime assembly generation, trampoline work, or custom patching logic. Xbyak is a header-only x86/x64 JIT assembler library.

git submodule add https://github.com/herumi/xbyak.git ThirdParty/xbyak
git submodule update --init --recursive

Example xmake.lua include:

add_includedirs("ThirdParty/xbyak", { public = true })

Ultralight SDK

Use Ultralight when the mod needs HTML/CSS/JavaScript-driven UI, such as a custom browser, server browser, launcher-like interface, or rich overlay. Ultralight is a GPU-accelerated HTML renderer with C and C++ support.

git submodule add <your-ultralight-sdk-repo-url> ThirdParty/Ultralight-SDK
git submodule update --init --recursive

Example xmake.lua include:

add_includedirs("ThirdParty/Ultralight-SDK/include", { public = true })

Linking Ultralight usually requires additional .lib files and runtime .dll files. Keep those project-specific rather than adding them to the base template.

framework-F4-Conversion

Use framework-F4-Conversion only for mods that depend on NomadsReach's Fallout 4 conversion/UI framework. This should not be required for normal F4SE plugins.

git submodule add https://github.com/NomadsReach/framework-F4-Conversion.git ThirdParty/framework-F4-Conversion
git submodule update --init --recursive

Example xmake.lua include:

add_includedirs("ThirdParty/framework-F4-Conversion/include", { public = true })

Only wire this into the build once the mod actually uses it.

spdlog

Use spdlog if the plugin needs more advanced logging than the default template logging setup, such as rotating logs, multiple sinks, custom formatting, or async logging.

git submodule add https://github.com/gabime/spdlog.git ThirdParty/spdlog
git submodule update --init --recursive

Example xmake.lua include:

add_includedirs("ThirdParty/spdlog/include", { public = true })

toml++

Use toml++ if the plugin needs structured configuration files, for example:

Data/F4SE/Plugins/MyPlugin.toml

git submodule add https://github.com/marzer/tomlplusplus.git ThirdParty/tomlplusplus
git submodule update --init --recursive

Example xmake.lua include:

add_includedirs("ThirdParty/tomlplusplus/include", { public = true })

SimpleIni

Use SimpleIni for very small .ini configuration files. This is useful when the plugin only needs a few basic settings and a TOML parser would be overkill.

git submodule add https://github.com/brofield/simpleini.git ThirdParty/SimpleIni
git submodule update --init --recursive

Example xmake.lua include:

add_includedirs("ThirdParty/SimpleIni", { public = true })

fmt

Use fmt if the plugin needs standalone formatting utilities. Some logging libraries already include or depend on fmt, so avoid adding it separately unless the project directly needs it.

git submodule add https://github.com/fmtlib/fmt.git ThirdParty/fmt
git submodule update --init --recursive

Example xmake.lua include:

add_includedirs("ThirdParty/fmt/include", { public = true })