Commonwealth-Online-Public/plugin/setup.md

# Plugin Setup

The Commonwealth Online native plugin is based on `Fallout4Together`.

## Selected Template

```text
Template: Fallout4Together
Template URL: https://github.com/libxse/Fallout4Together
Use: Copied into plugin/ as the starting plugin scaffold
Forked: No
```

## Build Target

```text
Project Name: CommonwealthOnline
Output DLL: CommonwealthOnline.dll
Expected Install Path: Data/F4SE/Plugins/CommonwealthOnline.dll
```

## Current Goal

The current goal is to build the F4SE plugin, confirm it loads through F4SE, and
verify the local networking prototype against `server/server.py`.

This means the plugin should be able to:

* Build successfully
* Output `CommonwealthOnline.dll`
* Be copied into `Data/F4SE/Plugins/`
* Load when Fallout 4 is launched through F4SE
* Create or write to a `CommonwealthOnline.log` file
* Prefix multiplayer/networking log lines with `[LocalPlayerId=unassigned]` before the server welcome packet and `[LocalPlayerId=N]` after assignment
* Connect to the local server on `127.0.0.1:7777`
* Send local transform packets
* Receive `welcome`, `transform`, and `disconnect` packets
* Store remote player state internally
* Move the single placed test proxy actor from remote player state on the game
  thread without dynamically spawning actors
* Smooth normal proxy movement and snap cell changes, worldspace changes, and
  teleports safely

## Not Included Yet

The plugin does not currently include:

* Dynamic actor spawning
* Multiple proxy actors
* Remote player spawning
* Combat sync
* Quest sync

## PrismaUI HTML Server Browser

Commonwealth Online renders an HTML server browser through [PrismaUI_F4](https://github.com/NomadsReach/framework-F4-Conversion), vendored as:

```text
ThirdParty/framework-F4-Conversion
```

Ultralight SDK setup:

* Vendored as a git submodule at `ThirdParty/Ultralight-SDK` (tracks the `Windows` branch)
* Initialize with: `git submodule update --init --recursive ThirdParty/Ultralight-SDK`
* Override with environment variable: `ULTRALIGHT_SDK_PATH`

Build PrismaUI_F4:

```bat
build-prismaui.bat
```

Build and deploy everything:

```bat
build.bat
build-prismaui.bat
deploy-all.bat
```

Or use `build-all.bat` to build and deploy in one step.

`deploy-all.bat` and `deploy-ui.bat` prompt for your Fallout 4 install folder on first use (or when the saved path is missing). The choice is stored locally in `.fallout4-path` (gitignored). You can still pass a path on the command line:

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

`deploy-all.bat` installs:

* `Data/F4SE/Plugins/PrismaUI_F4.dll`
* `Data/F4SE/Plugins/CommonwealthOnline.dll`
* `Data/PrismaUI_F4/libs/*.dll`
* `Data/PrismaUI_F4/resources/*`
* `Data/PrismaUI_F4/views/CommonwealthOnline/browser/index.html`

In-game controls:

* Main Menu > Multiplayer opens the server browser
* Press **F9** to toggle the browser
* Use the server list to browse, filter, and join servers
* **Local Relay (Dev)** connects to `127.0.0.1:7777` — start `server/server.py` first

If PrismaUI_F4 is missing, the plugin still loads and networking continues to work; only the HTML UI is skipped.

## Required Tools

The plugin setup is expected to require:

* Fallout 4 on Steam
* Fallout 4 Script Extender, F4SE
* Visual Studio 2022
* MSVC C++ compiler
* Windows SDK
* XMake
* Git

## Recommended Folder Layout

```text
plugin/
├─ xmake.lua
├─ src/
├─ include/
├─ external/
├─ build/
├─ README.md
└─ SETUP.md
```

## Build Steps

From the repository root:

```bash
cd plugin
xmake
xmake build
```

If the build succeeds, look for the compiled DLL in the output folder created by XMake.

## Install Location

For manual testing, the compiled plugin DLL should eventually be copied to:

```text
Fallout 4/Data/F4SE/Plugins/CommonwealthOnline.dll
```

If the `F4SE/Plugins/` folder does not exist inside `Data/`, create it manually.

## Testing Checklist

Use this checklist for the first plugin test:

* [ ] Fallout 4 launches normally without the plugin
* [ ] Fallout 4 launches through F4SE without the plugin
* [ ] `CommonwealthOnline.dll` builds successfully
* [ ] `CommonwealthOnline.dll` is copied to `Data/F4SE/Plugins/`
* [ ] Fallout 4 launches through F4SE with the plugin installed
* [ ] Game reaches the main menu without crashing
* [ ] Plugin log file is created
* [ ] Plugin log confirms that the plugin loaded
* [ ] Local server is running before gameplay networking tests
* [ ] Plugin log shows `[LocalPlayerId=unassigned]` before assignment
* [ ] Plugin log shows `[LocalPlayerId=N] Assigned server playerId: N`
* [ ] Plugin logs prefixed remote player updates from another connected client
* [ ] Plugin logs prefixed remote player removal after a disconnect
* [ ] `CommonwealthOnline.esp` is enabled (provides `COPlayerProxy` actor base, local FormID `002666`)
* [ ] With two Fallout 4 instances in the same cell, each instance spawns a dynamic
      proxy at the other player's networked position
* [ ] Optional regression: `coc F4TTestCell01` with `kEnablePrePlacedProxyPool` enabled
* [ ] Optional regression: `F4TProxyRemotePlayer01REF` resolves when placed fallback flag is on

### Global dynamic spawn validation

* [ ] Two clients in the same vanilla interior (e.g. Sanctuary house) see each other's proxies
* [ ] Two clients in the Commonwealth exterior in the same loaded area see proxies
* [ ] Remote player in a different cell: proxy held hidden, not visible
* [ ] Local player walks into remote player's cell: proxy spawns at remote position
* [ ] Local player leaves a cell with active proxies: no orphaned actors remain in prior cell

## Notes

Remote actors are dynamically spawned at runtime in the local player's current
cell. The game-thread proxy actor controller consumes a copied remote-player
snapshot to spawn, move, and hold proxy actors per remote `playerId`.