andrew
9dbcc7d926
Create a minimal Fallout 4 F4SE/CommonLibF4 starter repo with build, packaging, install, and rename scripts, plus initial plugin source, headers, and xmake configuration.
200 lines
5.1 KiB
Markdown
200 lines
5.1 KiB
Markdown
# 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
|
|
|
|
```powershell
|
|
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
|
|
|
|
```powershell
|
|
xmake build
|
|
```
|
|
|
|
The built plugin is copied to:
|
|
|
|
```text
|
|
package/F4SE/Plugins/
|
|
```
|
|
|
|
## Generate Visual Studio project
|
|
|
|
```powershell
|
|
xmake project -k vsxmake
|
|
```
|
|
|
|
## Package for mod managers
|
|
|
|
```powershell
|
|
.\scripts\package.ps1 -OutputName "MyNewF4SEMod"
|
|
```
|
|
|
|
This creates a zip with the expected layout:
|
|
|
|
```text
|
|
F4SE/Plugins/MyNewF4SEMod.dll
|
|
F4SE/Plugins/MyNewF4SEMod.pdb
|
|
```
|
|
|
|
## Dev install to Fallout 4
|
|
|
|
```powershell
|
|
.\scripts\install-dev.ps1 -Fallout4Path "C:\Program Files (x86)\Steam\steamapps\common\Fallout 4"
|
|
```
|
|
|
|
## Repo layout
|
|
|
|
```text
|
|
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/`:
|
|
|
|
```text
|
|
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.
|
|
|
|
```powershell
|
|
git submodule add https://github.com/herumi/xbyak.git ThirdParty/xbyak
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
Example `xmake.lua` include:
|
|
|
|
```lua
|
|
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.
|
|
|
|
```powershell
|
|
git submodule add <your-ultralight-sdk-repo-url> ThirdParty/Ultralight-SDK
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
Example `xmake.lua` include:
|
|
|
|
```lua
|
|
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.
|
|
|
|
```powershell
|
|
git submodule add https://github.com/NomadsReach/framework-F4-Conversion.git ThirdParty/framework-F4-Conversion
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
Example `xmake.lua` include:
|
|
|
|
```lua
|
|
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.
|
|
|
|
```powershell
|
|
git submodule add https://github.com/gabime/spdlog.git ThirdParty/spdlog
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
Example `xmake.lua` include:
|
|
|
|
```lua
|
|
add_includedirs("ThirdParty/spdlog/include", { public = true })
|
|
```
|
|
|
|
### toml++
|
|
|
|
Use `toml++` if the plugin needs structured configuration files, for example:
|
|
|
|
```text
|
|
Data/F4SE/Plugins/MyPlugin.toml
|
|
```
|
|
|
|
```powershell
|
|
git submodule add https://github.com/marzer/tomlplusplus.git ThirdParty/tomlplusplus
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
Example `xmake.lua` include:
|
|
|
|
```lua
|
|
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.
|
|
|
|
```powershell
|
|
git submodule add https://github.com/brofield/simpleini.git ThirdParty/SimpleIni
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
Example `xmake.lua` include:
|
|
|
|
```lua
|
|
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.
|
|
|
|
```powershell
|
|
git submodule add https://github.com/fmtlib/fmt.git ThirdParty/fmt
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
Example `xmake.lua` include:
|
|
|
|
```lua
|
|
add_includedirs("ThirdParty/fmt/include", { public = true })
|
|
```
|