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

Update Readme and License

Browse Source
This commit is contained in:
andrew
2026-07-26 10:03:36 +12:00
parent aefeb8b51f
commit 3778458a9b
2 changed files with 184 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
LICENSE
+19 -3
View File
@@ -1,4 +1,20 @@
To be decided.
## Licensing
This project currently has no formal open-source license.
Do not reuse, redistribute, or publish this code/assets until a license is selected.
Unless otherwise noted, original source code in this repository is licensed
under the Mozilla Public License 2.0.
This licence does not apply to game data, plugins created with the Fallout 4
Creation Kit, compiled archives, meshes, textures, materials, audio, branding,
screenshots, documentation specifically marked otherwise, or third-party
components. See `LICENSES/ASSETS.md` and `THIRD_PARTY_NOTICES.md`.
Fallout 4 Script Extender is a separately distributed dependency. Commonwealth
Online does not redistribute or provide modified versions of F4SE.
TiltedEvolution was consulted as a technical reference during research. No
TiltedEvolution source code is included in Commonwealth Online.
Fallout, Fallout 4, Bethesda Game Studios, Bethesda Softworks, ZeniMax and
related names and marks belong to their respective owners.
THIS MATERIAL IS NOT MADE, GUARANTEED OR SUPPORTED BY ZENIMAX OR ITS AFFILIATES.
README.md
+165 -71
View File
@@ -1,107 +1,201 @@
# Commonwealth Online
<p align="center">
<img src="Branding/CommonwealthOnlineLogo.svg" alt="Commonwealth Online" width="600"/>
</p>
Commonwealth Online is an experimental research project exploring the possibility of adding basic multiplayer-style networking to Fallout 4.
**Dedicated-server Fallout 4 multiplayer** — not campaign co-op, not an MMO.
The goal is not to create a full co-op campaign mod immediately. The first goal is much smaller:
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.
> Two Fallout 4 clients in a controlled test environment, with each player visible as a synced remote actor.
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.
This project is currently in the research and prototype stage.
**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.
## Project Goals
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.
### First Prototype
---
- 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
## Project status
### Long-Term Ideas
### Working today
- Basic LAN multiplayer test mode
- Remote player movement sync
- Basic animation state sync
- Basic chat or debug messages
- Host-controlled test cell
- Simple co-op combat arena
- **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
## Non-Goals
### In progress / experimental
This project is not currently trying to support:
- **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.
- Full Fallout 4 campaign co-op
- Quest synchronization
- Settlement synchronization
- Full NPC/world state synchronization
- VATS synchronization
- Public server/MMO gameplay
- Compatibility with large modlists
### Planned direction
Those systems are extremely complex and are outside the scope of the first prototype.
- **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
## Repository Layout
### 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
docs/ Project documentation and research notes
plugin/ Native F4SE/CommonLibF4 plugin work
creation-kit/ Creation Kit plugin files, Papyrus scripts, and test cell notes
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
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
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
- 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
All connected players should use the same game version, F4SE version, plugin build, ESP versions, and load order.
## Recommended Development Setup
---
Use a separate Fallout 4 installation or a dedicated modding profile for testing.
Recommended setup:
## Repository structure
```text
Fallout 4
F4SE
Creation Kit
Mod Organizer 2 or Vortex
Visual Studio
Git
plugin/ F4SE/CommonLibF4 C++ sync/networking plugin
server/ Python relay, dev GUI, fake clients
creation-kit/ ESP sources, Papyrus scripts, assets
docs/ Architecture, setup, protocol, dev notes, roadmap
docs/protocol/ Detailed packet and sync field reference
ThirdParty/ Vendored submodules (CommonwealthOnlineUI, networking, etc.)
Branding/ Project logos
tools/ Helper utilities and build scripts
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.
UI lives in the `ThirdParty/CommonwealthOnlineUI` submodule (`CommonwealthOnlineUI.dll` + PrismaUI/HTML).
## Legal Notice
Root batch scripts: `build-all.bat`, `deploy-all.bat`, `build.bat`, `compile-papyrus.bat`, `run-server-gui.bat`. Build Prisma/UI in `ThirdParty/CommonwealthOnlineUI`.
This repository does not include Fallout 4 game files, Bethesda assets, F4SE binaries, or any proprietary game code.
---
Users are responsible for owning Fallout 4 and installing required external tools themselves.
## Documentation
## Status
| 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/protocol/`](docs/protocol/) | Detailed packet field reference |
| [`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 |
| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Vertical-slice roadmap and milestones |
| [`changelog.md`](changelog.md) | Record of code and documentation changes |
| [`docs/dev-log.md`](docs/dev-log.md) | Milestones, testing notes, next steps |
Current status:
---
```text
Research phase
Repository structure setup
Protocol planning
No playable multiplayer build yet
```
## AI use statement
This project uses AI-assisted development tools, including Cursor, ChatGPT, and GitHub Copilot, as learning aids and everyday development tools. They may be used to draft boilerplate, explore APIs, investigate errors, review code, and assist with features such as networking, UI development, proxy appearance synchronisation, server tooling, and remote weapon display.
AI is also used for routine project maintenance, such as turning development notes into structured [`changelog.md`](changelog.md) entries, [`docs/dev-log.md`](docs/dev-log.md) milestones, and detailed commit messages. The maintainer determines what changed, what is significant, and what should be recorded. AI primarily helps organise and phrase that information consistently with the repository's conventions.
AI output is not treated as authoritative, particularly when working with undocumented Fallout 4 engine behaviour. For example, early AI-assisted animation-sync experiments produced plausible animation variable and event names that did not exist in the game's actual behaviour graphs and therefore failed silently at runtime.
Progress was made through human guidance from `.doxr` on Discord, who recommended decompiling the relevant `.hkx` behaviour files and examining their unpacked graph XML. This research, documented through the `F4-Animation-Research` work involving files such as `MTBehavior.hkx` and `RaiderRootBehavior`, revealed the correct variables, types, and weapon-behaviour paths required by the plugin. Weapon display and partial animation synchronisation also depended on repeated in-game testing, runtime logs, and targeted community research.
AI-assisted code and documentation should therefore be treated as a starting point rather than a source of truth. Contributors are responsible for reviewing and testing anything they submit. Behaviour should be verified against the game, project documentation such as [`docs/protocol.md`](docs/protocol.md), runtime evidence, and relevant community research before it is considered correct.
---
## 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
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.