**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`](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 ```text 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`](docs/architecture.md) · Protocol: [`docs/protocol.md`](docs/protocol.md) · Server: [`server/README.md`](server/README.md) --- ## Quick start (developers) ```bat git clone cd Commonwealth-Online git submodule update --init --recursive build-all.bat ``` Start the dev server: ```bat 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): ```bat 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`](docs/setup.md) --- ## Requirements | Requirement | Notes | |---|---| | Fallout 4 (Steam) | Primary target: **1.11.221.0** ([`docs/version-targets.md`](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 ```text 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`](docs/setup.md) | Build, deploy, submodules, main-menu notes | | [`docs/architecture.md`](docs/architecture.md) | Plugin, server, proxy, threading model | | [`docs/protocol.md`](docs/protocol.md) | Message types and LAN discovery | | [`docs/limitations.md`](docs/limitations.md) | Technical limits and unsupported systems | | [`docs/version-targets.md`](docs/version-targets.md) | Supported game/F4SE versions | | [`docs/project-comparison.md`](docs/project-comparison.md) | Commonwealth Online vs DoxyCoSync | | [`changelog.md`](changelog.md) | Record of code and documentation changes | | [`docs/dev-log.md`](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`](LICENSE): > Do not reuse, redistribute, or publish this code/assets until a license is selected. Third-party dependencies under `ThirdParty/` retain their own licenses.