andrew
8ff760ed39
Add a comprehensive step-by-step guide for injecting a custom main-menu button from an F4SE C++ plugin (docs/MainMenu_Button_Injection_Guide.md). Update existing docs to reference the new guide: add link in docs/MainMenu_Injection.md and expand the setup note in docs/setup.md to point to the full how-to and project-specific notes.
64 lines
2.8 KiB
Markdown
64 lines
2.8 KiB
Markdown
# 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
|