# 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 })
```