Commonwealth-Online/Commonwealth-Online-Public

Files

T

andrew 8ff760ed39 Add main menu button injection guide

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.

2026-06-09 22:44:18 +12:00

2.8 KiB

Raw Blame History

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

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:

.\tools\restore-vanilla-mainmenu.ps1

How it works

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).
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.
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 — historical reference only
PATCH_MainMenu_Multiplayer.md — historical reference only

2.8 KiB Raw Blame History