Commonwealth-Online/Commonwealth-Online-Public
2
0
Fork 0
Code Pull Requests Activity

Rewrite README for current project stage

Browse Source 
Restructured root README to better reflect Commonwealth Online's current state as a functional multiplayer foundation. Changes include: organized status section (working/in-progress/planned/out-of-scope), architecture summary with diagram, developer quick start, updated requirements table, honest scale limits (4 visible proxies vs 16+ design target), and aligned legal/license sections with LICENSE file. Improves clarity for both new contributors and potential users.
This commit is contained in:
andrew
2026-07-03 15:17:06 +12:00
parent 981f8891e4
commit 153dfe525c
2 changed files with 150 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+147 -70
View File
@@ -2,107 +2,184 @@
<img src="Branding/CommonwealthOnlineLogo.svg" alt="Commonwealth Online" width="600"/> <img src="Branding/CommonwealthOnlineLogo.svg" alt="Commonwealth Online" width="600"/>
</p> </p>
Commonwealth Online is an experimental Fallout 4 multiplayer mod built around a **dedicated relay server** (Minecraft-style hosting), designed for larger sessions (16+ players at near-full release). **Dedicated-server Fallout 4 multiplayer** — not campaign co-op, not an MMO.
The project has a working multiplayer foundation: connected clients can see each other as synced proxy actors, observe movement and animation, and share appearance, clothing, and weapons. Gameplay systems such as quests, inventory, settlements, and VATS are not synced yet. 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.
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 target different scales and architectures. 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.
## Project Goals **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.
### First Prototype 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.
- Load a native Fallout 4 plugin through F4SE ---
- Connect to a local test server
- Send local player position data
- Receive remote player transform data
- Represent another connected player using a placeholder actor
- Restrict all testing to a custom test cell
### Long-Term Ideas ## Project status
- Basic LAN multiplayer test mode ### Working today
- Remote player movement sync
- Basic animation state sync
- Basic chat or debug messages
- Host-controlled test cell
- Simple co-op combat arena
## Non-Goals - **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
This project is not currently trying to support: ### In progress / experimental
- Full Fallout 4 campaign co-op - **Weapon-drawn animation reliability** — draw/holster/armed locomotion on proxies; ongoing fixes and diagnostic work (see `docs/dev-log.md`)
- Quest synchronization - **Vault 109 → Commonwealth onboarding** — MQ102 auto-start on first vault exit; flow polish and testing continue
- Settlement synchronization - **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.
- Full NPC/world state synchronization
- VATS synchronization
- Public server/MMO gameplay
- Compatibility with large modlists
Those systems are extremely complex and are outside the scope of the first prototype. ### Planned direction
## Repository Layout - **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 ```text
docs/ Project documentation and research notes Fallout 4 + F4SE Plugin ←—— TCP JSON (7777) ——→ Python Relay Server ←——→ Other Clients
plugin/ Native F4SE/CommonLibF4 plugin work ↑
creation-kit/ Creation Kit plugin files, Papyrus scripts, and test cell notes UDP LAN discovery (7778)
server/ External multiplayer test server
protocol/ Network packet design and sync documentation
tools/ Helper scripts and utilities
test-data/ Example packets and test data
screenshots/ Development screenshots
``` ```
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 <repo-url>
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 ## Requirements
This project is expected to require: | 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 |
- Fallout 4 on PC All connected players should use the same game version, F4SE version, plugin build, ESP versions, and load order.
- Fallout 4 Script Extender, F4SE
- Fallout 4 Creation Kit
- Visual Studio 2022 or newer
- CMake or another supported C++ build system
- A CommonLibF4-based plugin template
- Git
- A clean Fallout 4 test profile
## Recommended Development Setup ---
Use a separate Fallout 4 installation or a dedicated modding profile for testing. ## Repository structure
Recommended setup:
```text ```text
Fallout 4 plugin/ F4SE/CommonLibF4 C++ plugin
F4SE server/ Python relay, dev GUI, fake clients
Creation Kit creation-kit/ ESP sources, Papyrus scripts, assets
Mod Organizer 2 or Vortex ui/ PrismaUI HTML/JS (server browser)
Visual Studio protocol/ Detailed packet and sync documentation
Git 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)
``` ```
Use a clean test save and avoid testing with a full personal modlist. Root batch scripts: `build-all.bat`, `deploy-all.bat`, `build.bat`, `compile-papyrus.bat`, `run-server-gui.bat`.
## Legal Notice ---
This repository does not include Fallout 4 game files, Bethesda assets, F4SE binaries, or any proprietary game code. ## Documentation
Users are responsible for owning Fallout 4 and installing required external tools themselves. | 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 |
## Status ---
Current status: ## Legal notice
```text Commonwealth Online is an **unofficial fan project**. It is not affiliated with, endorsed by, or associated with Bethesda Softworks or ZeniMax Media.
Functional multiplayer foundation
Dedicated Python relay server 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.
Remote player proxy actors (movement, appearance, apparel, weapons)
Server profiles, LAN discovery, world time/weather sync *Fallout* and related marks are trademarks of Bethesda Softworks LLC.
Quest, inventory, settlement, and combat sync not yet implemented
``` ---
## License ## License
To be decided. 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.
changelog.md
+3
View File
@@ -9,6 +9,9 @@ For testing notes, milestone summaries, known issues, and next steps, see [`docs
## [Unreleased] ## [Unreleased]
### Changed
- Rewrote root `README.md` for current project stage: structured status (working / in progress / planned / out of scope), architecture summary, developer quick start, updated repository layout and requirements, honest scale limits (4 proxies per client vs 16+ design target), and aligned license/legal sections with `LICENSE`.
### Added ### Added
- `docs/project-comparison.md` comparing Commonwealth Online with DoxyCoSync (architecture, scale, sync scope, collaboration). - `docs/project-comparison.md` comparing Commonwealth Online with DoxyCoSync (architecture, scale, sync scope, collaboration).
- Updated root `README.md` status to reflect functional multiplayer foundation (remote proxies, appearance, apparel, weapons). - Updated root `README.md` status to reflect functional multiplayer foundation (remote proxies, appearance, apparel, weapons).