Commonwealth-Online-Public/README.md

<p align="center">
  <img src="Branding/CommonwealthOnlineLogo.svg" alt="Commonwealth Online" width="600"/>
</p>

**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 <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

| 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.