# Development Setup

## Required Tools

- Fallout 4 on PC
- Fallout 4 Script Extender, F4SE
- Fallout 4 Creation Kit, including the Papyrus compiler
- Visual Studio 2022 or newer
- Git
- CMake or another build system required by the selected plugin template
- Mod Organizer 2 or Vortex

## Recommended Fallout 4 Setup

Use a clean test profile.

Recommended:

```text
Fallout 4
F4SE
Commonwealth Online test plugin
No other gameplay mods
Dedicated test save
```

Avoid testing with a full modlist while developing the core systems.

## Main menu

Do **not** deploy a patched `Interface/MainMenu.swf`. Commonwealth Online injects the **Multiplayer** row at runtime via the F4SE plugin. Use vanilla `MainMenu.swf` or no loose override. See [`MainMenu_Button_Injection_Guide.md`](MainMenu_Button_Injection_Guide.md) (full how-to) and [`MainMenu_Injection.md`](MainMenu_Injection.md) (project-specific notes).

## Version Tracking

Record the exact versions used:

```text
Fallout 4 version:
F4SE version:
Creation Kit version:
CommonLibF4 template:
Windows version:
Compiler version:
```

## Git Submodules

After cloning, initialize vendored dependencies:

```bat
git submodule update --init --recursive
```

This includes:

* `ThirdParty/framework-F4-Conversion` — PrismaUI_F4 HTML overlay framework
* `ThirdParty/Ultralight-SDK` — Ultralight SDK (`Windows` branch) for PrismaUI_F4 builds
* `ThirdParty/GameNetworkingSockets-src` — networking library
* `ThirdParty/xbyak` — assembler dependency

`build-prismaui.bat` links the Ultralight SDK submodule into the PrismaUI build tree automatically. Override the SDK location with `ULTRALIGHT_SDK_PATH` if needed.

## Build and Install

From the repository root:

```bat
build-all.bat
```

This builds the plugin, PrismaUI_F4, compiles active Papyrus sources from `creation-kit/scripts/source` into `creation-kit/scripts/compiled`, and stages a complete mod package into `build/Fallout 4/Data` at the repo root. The build step does not copy files into the real Fallout 4 install. Reference-only `CoSync*.psc` files are skipped. If a Papyrus script fails to compile, `build-all.bat` still stages the repo build folder for inspection, then exits with an error so the failed script is not missed.

`build-all.bat` uses the same Fallout 4 path resolver as `deploy-all.bat`: it accepts an explicit path, checks `FALLOUT4_PATH`, uses the saved `.fallout4-path`, checks common Steam install paths, and prompts/saves the path when needed. You can also pass the game path explicitly:

```bat
build-all.bat "D:\SteamLibrary\steamapps\common\Fallout 4"
```

```text
build/
└─ Fallout 4/
   └─ Data/
      ├─ CommonwealthOnline.esp
      ├─ CommonwealthOnline_Vault109.esp
      ├─ F4SE/
      │  └─ Plugins/
      │     ├─ CommonwealthOnline.dll
      │     └─ PrismaUI_F4.dll
      ├─ Materials/       (from creation-kit/assets)
      ├─ Meshes/          (from creation-kit/assets)
      ├─ Textures/        (from creation-kit/assets)
      ├─ Scripts/
      │  ├─ *.pex         (compiled from creation-kit/scripts/source)
      │  └─ Source/
      │     └─ User/
      │        └─ *.psc   (from creation-kit/scripts/source)
      └─ PrismaUI_F4/
         ├─ libs/          (Ultralight runtime DLLs)
         ├─ resources/     (Ultralight assets)
         ├─ misc/
         │  └─ cursor.png
         └─ views/
            └─ CommonwealthOnline/
               └─ browser/
                  └─ index.html
```

Merge `build\Fallout 4` into your game install directory, or copy the contents of `build\Fallout 4\Data` into `Data\`. Mod managers can point at `build\Fallout 4` as the mod root.

To install directly into a Fallout 4 install:

```bat
deploy-all.bat
deploy-all.bat "D:\SteamLibrary\steamapps\common\Fallout 4"
```

`deploy-all.bat` resolves the Fallout 4 install path, compiles Papyrus scripts, re-stages `build/Fallout 4/Data`, then copies that staged repo build into the game's `Data` folder. On first use it prompts for the install path and saves it in `.fallout4-path` (gitignored).

Individual steps:

```bat
build.bat              REM CommonwealthOnline.dll only
build-prismaui.bat     REM PrismaUI_F4.dll only
compile-papyrus.bat    REM Papyrus .psc to .pex only
stage-mod.bat          REM assemble build/ from existing DLL outputs
deploy-ui.bat          REM HTML views only (requires PrismaUI_F4 installed separately)
```

See also `plugin/setup.md` for plugin-specific build notes.

## Folder Notes

Do not copy Fallout 4 game files into this repository.

Do not copy F4SE binaries into this repository.

Use the `plugin/external/README.md` file to document where external dependencies should be installed.