Commonwealth-Online-Public/README.md

Dedicated-server Fallout 4 multiplayer — not campaign co-op, not an MMO.

Commonwealth Online is an active Fallout 4 multiplayer mod built around an external Python relay server (Minecraft-style hosting: run the server, clients connect). Each player still runs a full local Fallout 4 instance; the server coordinates and relays state — it does not simulate the Commonwealth.

The project has moved past the initial research prototype. Connected clients can see other players as runtime proxy actors in the same cell, with movement, locomotion animation, appearance, apparel, and partial weapon visuals. Gameplay systems (combat, inventory, quests, settlements, VATS, NPC/world sync) are not synced yet. This is a working presence and infrastructure foundation, not a playable co-op mod today.

Design target: larger dedicated-server sessions (16+ players near full release). Current limit: up to four visible proxy actors per client (kMaxRuntimeProxyActors); remote players must be in the same loaded cell to appear.

For how this project relates to DoxyCoSync (peer-to-peer co-op for small groups), see docs/project-comparison.md. The creators collaborate on research; the mods are separate products for different scales and architectures.

---

Project status

Working today

• Dedicated Python relay server — TCP JSON on port 7777 (server/server.py, reusable server_core.py)
• UDP LAN discovery — port 7778; clients can find local servers without hard-coded addresses
• Developer server GUI — PySide6 app with live logs, stats, connected clients, fake-client tooling, and admin weather/time controls (server/dev_server_app.py)
• Protocol lifecycle — welcome, transform, disconnect, late-join snapshot replay, optional worldState / serverWorldState
• Transform sync — position, heading, cell/worldspace, movement fields (isMoving, sprint, sneak, jump, weaponDrawn, speed); ~10 Hz while moving
• Runtime proxy actors — PlaceAtMe-backed visual puppets per remote playerId; movement smoothing; passive/neutralized (not shared combat actors)
• Locomotion animation — curated animation-graph variables and transition events from remote movement state
• Appearance sync — height, body morph, hair colours, head parts, morph sliders, tints, complexion (best-effort on proxies; gender/race switching deferred)
• Visible apparel sync — equipped clothing, armor, hats, eyewear via equippedItems
• Weapon visuals (partial) — right-hand weapon model sync and weapon-drawn animation path for ranged guns; reliability still being tested in-game
• Shared time and weather — designated world-state host relays time/weather; dev GUI can broadcast admin weather/time commands
• Session onboarding — first-time join via custom COVault109 cell (solo during character creation), Looks/SPECIAL flow, server profile ↔ save binding, reconnect handling
• Main-menu multiplayer UI — runtime Multiplayer row injection (no patched MainMenu.swf); PrismaUI server browser with keyboard and gamepad support
• LAN server browser tab — discovers real relays on the local network
• Dev tooling — server/fake_client.py, GUI fake clients, build/deploy batch scripts

In progress / experimental

• Weapon-drawn animation reliability — draw/holster/armed locomotion on proxies; ongoing fixes and diagnostic work (see docs/dev-log.md)
• Vault 109 → Commonwealth onboarding — MQ102 auto-start on first vault exit; flow polish and testing continue
• Server browser (Browse tab) — UI uses mock server entries for layout/dev; real listings require future master-server or internet discovery work (TODO M6 in plugin code). Local tab is the real discovery path today.

Planned direction

• Playable vertical slice — onboarding into shared-world presence, then expanding gameplay sync over time
• Scale toward 16+ player sessions — protocol and server default to 16 max players; not load-tested at that scale yet
• Increase visible proxy cap beyond four per client
• Weapon sync phase 2 — melee, fire events, ADS (see docs/weapon-animation-sync.md)
• Power armor and fuller weapon state
• Public server browser / master server — beyond LAN discovery
• Chat or player communication — under consideration
• Authentication, persistence, anti-cheat — listed in server roadmap; not started

Possible future direction

• Public testing or beta (no committed schedule documented yet)
• Simple co-op combat arena or map-focused session modes
• Broader mod compatibility (clean load order required today)
• GOG support (Steam is the primary tested platform)

Out of scope (current stage)

• Full Fallout 4 campaign co-op
• Quest, settlement/workshop, inventory/loot, NPC/world entity, VATS, combat/damage, companion, and dialogue synchronization
• Headless server-hosted Fallout simulation (each client owns its own world)
• MMO-scale public matchmaking or persistent MMO gameplay
• Microsoft Store / Game Pass and console
• Large modlist compatibility

---

Architecture at a glance

Fallout 4 + F4SE Plugin  ←—— TCP JSON (7777) ——→  Python Relay Server  ←——→  Other Clients
                                    ↑
                           UDP LAN discovery (7778)

1. The plugin reads local player transform and optional appearance/equipment snapshots.
2. The relay assigns playerId, timestamps packets, and broadcasts to other clients.
3. Each client spawns local runtime proxies for remote players in the same cell — visual mirrors, not full networked player entities.

Details: docs/architecture.md · Protocol: docs/protocol.md · Server: server/README.md

---

Quick start (developers)

git clone <repo-url>
cd Commonwealth-Online
git submodule update --init --recursive
build-all.bat

Start the dev server:

run-server-gui.bat
REM or: cd server && python dev_server_app.py

Deploy into a Fallout 4 install (prompts for path on first run):

deploy-all.bat

Launch Fallout 4 through F4SE → main menu → Multiplayer → Local tab (scan for LAN server) or connect to 127.0.0.1:7777.

Full setup, version pins, and troubleshooting: docs/setup.md

---

Requirements

Requirement	Notes
Fallout 4 (Steam)	Primary target: 1.11.221.0 (docs/version-targets.md)
F4SE	Matching 1.11.221.0
Visual Studio 2022+	C++ plugin build
Git	Including submodule support
Python 3	Relay server; pip install -r server/requirements.txt for dev GUI
Creation Kit	Papyrus compile (compile-papyrus.bat)
Mod manager (optional)	MO2 or Vortex; clean test profile strongly recommended

All connected players should use the same game version, F4SE version, plugin build, ESP versions, and load order.

---

Repository structure

plugin/           F4SE/CommonLibF4 C++ plugin
server/           Python relay, dev GUI, fake clients
creation-kit/     ESP sources, Papyrus scripts, assets
ui/               PrismaUI HTML/JS (server browser)
protocol/         Detailed packet and sync documentation
docs/             Architecture, setup, protocol overview, dev notes
ThirdParty/       Vendored submodules (CommonLibF4/PrismaUI, Ultralight, etc.)
Branding/         Project logos
tools/            Helper utilities
scripts/          Build/deploy helpers
test-data/        Example packets
screenshots/      Development screenshots
build/            Staged mod output (generated by build-all.bat)

Root batch scripts: build-all.bat, deploy-all.bat, build.bat, compile-papyrus.bat, run-server-gui.bat.

---

Documentation

Document	Purpose
docs/setup.md	Build, deploy, submodules, main-menu notes
docs/architecture.md	Plugin, server, proxy, threading model
docs/protocol.md	Message types and LAN discovery
docs/limitations.md	Technical limits and unsupported systems
docs/version-targets.md	Supported game/F4SE versions
docs/project-comparison.md	Commonwealth Online vs DoxyCoSync
changelog.md	Record of code and documentation changes
docs/dev-log.md	Milestones, testing notes, next steps

---

Legal notice

Commonwealth Online is an unofficial fan project. It is not affiliated with, endorsed by, or associated with Bethesda Softworks or ZeniMax Media.

This repository does not include Fallout 4 game files, Bethesda assets, F4SE binaries, Creation Kit binaries, or any proprietary game code. Users must own Fallout 4 and install F4SE, the Creation Kit, and other required tools themselves.

Fallout and related marks are trademarks of Bethesda Softworks LLC.

---

License

No formal open-source license has been selected. See LICENSE:

Do not reuse, redistribute, or publish this code/assets until a license is selected.

Third-party dependencies under ThirdParty/ retain their own licenses.