Update Readme and License
This commit is contained in:
@@ -1,4 +1,20 @@
|
|||||||
To be decided.
|
## Licensing
|
||||||
|
|
||||||
This project currently has no formal open-source license.
|
Unless otherwise noted, original source code in this repository is licensed
|
||||||
Do not reuse, redistribute, or publish this code/assets until a license is selected.
|
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.
|
||||||
@@ -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
|
## Project status
|
||||||
- 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
|
### Working today
|
||||||
|
|
||||||
- Basic LAN multiplayer test mode
|
- **Dedicated Python relay server** — TCP JSON on port `7777` (`server/server.py`, reusable `server_core.py`)
|
||||||
- Remote player movement sync
|
- **UDP LAN discovery** — port `7778`; clients can find local servers without hard-coded addresses
|
||||||
- Basic animation state sync
|
- **Developer server GUI** — PySide6 app with live logs, stats, connected clients, fake-client tooling, and admin weather/time controls (`server/dev_server_app.py`)
|
||||||
- Basic chat or debug messages
|
- **Protocol lifecycle** — `welcome`, `transform`, `disconnect`, late-join snapshot replay, optional `worldState` / `serverWorldState`
|
||||||
- Host-controlled test cell
|
- **Transform sync** — position, heading, cell/worldspace, movement fields (`isMoving`, sprint, sneak, jump, `weaponDrawn`, speed); ~10 Hz while moving
|
||||||
- Simple co-op combat arena
|
- **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
|
### Planned direction
|
||||||
- Quest synchronization
|
|
||||||
- Settlement synchronization
|
|
||||||
- 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.
|
- **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
|
```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++ sync/networking plugin
|
||||||
F4SE
|
server/ Python relay, dev GUI, fake clients
|
||||||
Creation Kit
|
creation-kit/ ESP sources, Papyrus scripts, assets
|
||||||
Mod Organizer 2 or Vortex
|
docs/ Architecture, setup, protocol, dev notes, roadmap
|
||||||
Visual Studio
|
docs/protocol/ Detailed packet and sync field reference
|
||||||
Git
|
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
|
## AI use statement
|
||||||
Research phase
|
|
||||||
Repository structure setup
|
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.
|
||||||
Protocol planning
|
|
||||||
No playable multiplayer build yet
|
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
|
## 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.
|
||||||
|
|||||||
Reference in New Issue
Block a user