# MainMenu Multiplayer — C++ runtime injection

Commonwealth Online adds a **Multiplayer** row to the Fallout 4 title-screen main menu at runtime. No SWF patching is required.

> **Full step-by-step guide for mod authors:** [`MainMenu_Button_Injection_Guide.md`](MainMenu_Button_Injection_Guide.md)

## Requirements

- Fallout 4 launched via **F4SE**
- `CommonwealthOnline.dll` in `Data/F4SE/Plugins/`
- **PrismaUI_F4** and the server browser HTML view installed (for the overlay)
- **Vanilla** `MainMenu.swf` — or no loose override at all (game loads from `Fallout4 - Interface.ba2`)

## Do not ship a patched SWF

| Do | Don't |
|----|--------|
| Use vanilla `MainMenu.swf` (61,959 bytes) or no loose file | Deploy an FFDec-patched `Interface/MainMenu.swf` |
| Let the plugin inject the row and handle clicks | Re-import the full `MainMenu.as` script in FFDec |

A patched SWF can break **Settings → Gameplay / Display / Audio**. The C++ injection path keeps vanilla bytecode intact.

To restore vanilla from the game archive:

```powershell
.\tools\restore-vanilla-mainmenu.ps1
```

## How it works

1. **List injection** — After `StartMenuBase::InitMainList` builds the menu, the plugin inserts `{ text: "Multiplayer", index: 15 }` after the **Load** row (index 4). A fallback task re-injects if ActionScript rebuilds the list without calling the native hook (for example after deleting the last save).
2. **Selection handling** — A Scaleform `ITEM_PRESS` listener intercepts index `15` on the title screen (`MAIN_STATE`, not pause menu) and opens the PrismaUI server browser. Vanilla `onMainListItemPress` is not run for that row.
3. **Browser lifecycle** — Existing `WatchMainMenuState` hides the browser when leaving `MAIN_STATE`. **F9** still toggles the browser.

## Test checklist

| Case | Expected |
|------|----------|
| Title screen main list | **Multiplayer** appears after **Load** |
| Pause menu | No Multiplayer row |
| Click Multiplayer | Server browser opens; no SaveLoad panel flicker |
| Accept / gamepad A on Multiplayer | Same |
| Settings → Gameplay / Display / Audio | No crash |
| Settings → Controls | Works |
| Open Multiplayer → Settings | Browser closes immediately |
| Delete last save / list rebuild | Multiplayer row reappears |
| F9 | Still toggles browser |
| No loose `MainMenu.swf` | Still works (BA2 vanilla) |

## Log checks

In `CommonwealthOnline.log`, look for `[MainMenuInject]` lines:

- `InitMainList hook and MainMenu injection tasks installed.`
- `Injected Multiplayer row after Load.`
- `Registered ITEM_PRESS listener ('…').`

## Deprecated approach

The FFDec SWF patch guide is superseded by this document:

- [`FFDEC_MainMenu_Multiplayer_Guide.md`](FFDEC_MainMenu_Multiplayer_Guide.md) — historical reference only
- [`PATCH_MainMenu_Multiplayer.md`](../Interface/exported/PATCH_MainMenu_Multiplayer.md) — historical reference only