Add project comparison docs

Add a public comparison of Commonwealth Online and DoxyCoSync, and update the README and changelog to reflect Commonwealth Online’s current multiplayer foundation and dedicated relay-server focus.

README.md

@@ -1,12 +1,10 @@
 # Commonwealth Online
 
-Commonwealth Online is an experimental research project exploring the possibility of adding basic multiplayer-style networking to Fallout 4.
+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).
 
-The goal is not to create a full co-op campaign mod immediately. The first goal is much smaller:
+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.
 
-> Two Fallout 4 clients in a controlled test environment, with each player visible as a synced remote actor.
+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.
-
-This project is currently in the research and prototype stage.
 
 ## Project Goals
 
@@ -96,10 +94,11 @@ Users are responsible for owning Fallout 4 and installing required external tool
 Current status:
 
 ```text
-Research phase
+Functional multiplayer foundation
-Repository structure setup
+Dedicated Python relay server
-Protocol planning
+Remote player proxy actors (movement, appearance, apparel, weapons)
-No playable multiplayer build yet
+Server profiles, LAN discovery, world time/weather sync
+Quest, inventory, settlement, and combat sync not yet implemented
 ```
 
 ## License

changelog.md

@@ -10,6 +10,8 @@ For testing notes, milestone summaries, known issues, and next steps, see [`docs
 ## [Unreleased]
 
 ### Added
+- `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).
 - Experimental proxy weapon alert forcing: while a remote player reports `weaponDrawn=true`, runtime proxies now periodically execute scoped `<proxyRef>.setalert 1` before weapon animation sync, then clear alert on holster, to test whether Fallout 4's NPC alert state is what keeps weapon-ready poses alive.
 - One-time-per-proxy diagnostic log (`Runtime proxy weapon graph DIAGNOSTIC`) reporting the loaded animation-graph and bound-channel counts when a proxy first has a weapon equipped, to help determine why weapon FSM events are being rejected by the graph.
 - Weapon animation sync for ranged guns: proxy actors now equip remote players' right-hand weapons and play armed idle/locomotion poses when `weaponDrawn=true`.

docs/dev-log.md

@@ -7,6 +7,31 @@ failed experiments, successful tests, and next steps.
 
 ---
 
+## 2026-07-02 - DoxyCoSync Comparison Documentation
+
+### Summary
+Added a public-facing comparison document explaining how Commonwealth Online and DoxyCoSync differ, that the creators collaborate, and that Commonwealth Online now has a functional multiplayer foundation (visible remote players, appearance, apparel, weapons, partial interaction) rather than research-only status. Updated root README status accordingly.
+
+### Files Changed
+- `docs/project-comparison.md`
+- `README.md`
+
+### Details
+- Documents P2P (~4 players) vs dedicated-server (16+) positioning
+- Clarifies DoxyCoSync dedicated-server roadmap as collaborative testing, not core DoxyCoSync product direction
+- Parallel shorter doc added in DoxyCoSync repo: `docs/commonwealth-online-comparison.md`
+
+### Testing
+- Documentation only; no runtime testing required
+
+### Known Issues
+- None
+
+### Next Steps
+- Share doc with Doxy for review / wording tweaks if needed
+
+---
+
 ## 2026-07-02 - Weapon Animation Sync Milestone 1 (Ranged Guns - Phase 1–4)
 
 ### Summary

docs/project-comparison.md

@@ -0,0 +1,201 @@
+# Commonwealth Online and DoxyCoSync
+
+This document explains how **Commonwealth Online** and **DoxyCoSync** relate to each other, how they differ, and why both projects exist.
+
+The creators of both mods are **collaborating**. We share research, compare approaches, and occasionally test ideas in each other's codebases — but we are building **two separate products** for different use cases, not two versions of the same mod.
+
+---
+
+## Quick comparison
+
+| | **DoxyCoSync** | **Commonwealth Online** |
+|---|---|---|
+| **Made by** | Doxy | Commonwealth Online team |
+| **Networking model** | Peer-to-peer — one player hosts, others join | Dedicated server — everyone connects to an external relay |
+| **Target group size** | Small friend groups (~4 players) | Larger sessions (16+ players at near-release) |
+| **Hosting analogy** | Host a session for friends (Hamachi / VPN / LAN) | Run a server like Minecraft (`server.jar` + clients) |
+| **Current maturity** | Playable co-op with broad gameplay sync | Functional multiplayer foundation — see other players, movement, visuals, partial interaction |
+| **Wire protocol** | Pipe-delimited messages (`EU\|`, `QS\|`, `WB\|`, …) | JSON over TCP (`transform`, `welcome`, `disconnect`, …) |
+| **Primary focus today** | Shared co-op gameplay (quests, workshop, inventory, …) | Player presence, server infrastructure, proxy representation, animation |
+
+---
+
+## What each project is for
+
+### DoxyCoSync — small-group co-op
+
+DoxyCoSync is built for **friends playing Fallout 4 together** in a small group. The typical flow is:
+
+1. One player starts hosting in-game.
+2. Friends join that host over the network (often via Hamachi or similar).
+3. The host client relays sync traffic and runs some host-only game logic.
+
+This model keeps setup simple for a handful of players and prioritization-friendly for intimate co-op sessions.
+
+**Design stance:** peer-to-peer, small groups, about **4 players**.
+
+### Commonwealth Online — server-based multiplayer
+
+Commonwealth Online is built for **dedicated server multiplayer** from the ground up. The typical flow is:
+
+1. Someone runs the Python relay server (locally or on a VPS).
+2. Every player connects to that server — no in-game host required.
+3. The server manages sessions, player IDs, discovery, and relay.
+
+This model is closer to **Minecraft**: a persistent server process that many clients join, with room to grow into admin tools, LAN discovery, and larger player counts.
+
+**Design stance:** server-based, Minecraft-style hosting, **16+ players** at near-full release.
+
+---
+
+## Current status (what actually works today)
+
+### Commonwealth Online — functional multiplayer foundation
+
+Commonwealth Online has moved **past the research-only prototype stage**. In active testing, connected clients can:
+
+- **See other players** as runtime proxy actors in the same cell
+- **Watch movement** with smoothed position updates and basic locomotion animation
+- **See appearance sync** — body morph, height, hair colours, head parts, complexion, skin tints, and facial morphs (best-effort on proxies)
+- **See clothing and armor** via equipped apparel snapshots
+- **See weapons** — right-hand weapon models and armed idle/locomotion when a remote player has their weapon drawn
+- **Join and leave sessions** with server-assigned player IDs, welcome/disconnect handling, and late-join snapshot delivery
+- **Share basic world state** — time and weather via a designated world-state host, plus optional server-admin weather/time commands
+
+Interaction is **partial** by design right now: proxies are visual representations, not full shared game actors. Combat, inventory, quests, settlements, and VATS are not synced yet. The project is actively building outward from a working “see and recognize the other player” baseline.
+
+### DoxyCoSync — playable co-op with deep sync
+
+DoxyCoSync already syncs many gameplay systems for small-group co-op, including player entities, world/cell state, quests, workshop build/destroy, inventory, loot, VATS, companions, dialog, health, outfits, and more. It is aimed at **actually playing co-op**, not just seeing another player's model.
+
+Its current networking uses **Steam GameNetworkingSockets (GNS)** with an in-game host that rebroadcasts messages. Session entry is through an ImGui overlay (“Start Hosting” / “Join Game”).
+
+---
+
+## Architecture
+
+Both projects share one important rule: **each player still runs a full local Fallout 4 instance**. Neither project simulates the Commonwealth on a headless server. The server (or host) coordinates and relays; clients apply remote state locally.
+
+### DoxyCoSync (peer-to-peer today)
+
+```text
+Client A (host)  ←—— GNS listen ——→  Client B, C, …
+       │
+       └── Relays messages + runs some host-only logic
+           (NPC world scan, loot salt, companion handling, …)
+```
+
+### Commonwealth Online (dedicated relay)
+
+```text
+Fallout 4 + Plugin  ←—— TCP JSON ——→  Python Relay Server  ←——→  Other Clients
+```
+
+Commonwealth Online also exposes **UDP LAN discovery** (port `7778`) so clients can find servers on the local network without hard-coding addresses. The relay listens on TCP port `7777` by default and is designed for `maxPlayers: 16`.
+
+---
+
+## What is synced vs out of scope
+
+| Area | DoxyCoSync | Commonwealth Online |
+|---|---|---|
+| Player movement | Yes | Yes |
+| Player appearance / clothes | Yes | Yes (proxy, best-effort) |
+| Weapons (visual / drawn state) | Yes | Yes (ranged guns, right-hand; partial) |
+| Quest progression | Yes | Not yet |
+| Workshop / settlements | Yes | Not yet |
+| Inventory / loot | Yes | Not yet |
+| VATS | Yes | Not yet |
+| NPC / world entity sync | Yes (host-driven) | Not yet |
+| Companions / dialog | Yes | Not yet |
+| Dedicated server product | Experimental testing only* | Core architecture |
+
+\* See [Note on DoxyCoSync dedicated-server docs](#note-on-doxycosync-dedicated-server-docs) below.
+
+---
+
+## Protocol and tooling
+
+The projects use **different protocols on purpose**. They are not wire-compatible and are not merging into one stack.
+
+| | DoxyCoSync | Commonwealth Online |
+|---|---|---|
+| Format | Pipe strings (`EU\|`, `QS\|`, `WB\|`, …) | JSON (`type`, `playerId`, `x`, `y`, `z`, …) |
+| Transport | GNS (P2P host/join today) | TCP relay + UDP discovery |
+| Fake / test clients | Planned (patterns adapted from CO server tooling) | `server/fake_client.py`, dev GUI server |
+| Admin / config | Explored in testing docs | Dev server GUI, world-state host, server profiles |
+
+Shared **dev tooling ideas** (relay servers, fake clients, logging GUIs) cross-pollinate, but each mod keeps its own message format and plugin architecture.
+
+---
+
+## Player representation
+
+**DoxyCoSync** uses networked player entities with deep game integration — animation behavior graphs, outfit sync, quest hooks via Papyrus, and host-authoritative world scans.
+
+**Commonwealth Online** uses **runtime proxy actors**: lightweight visual puppets spawned per remote player in the local cell. Proxies are neutralized (passive, non-combat), smoothed for movement, and driven by curated animation graph variables. They mirror appearance, equipment, and weapons so remote players are recognizable, without pretending to be full shared game actors yet.
+
+This matches each project's goal: DoxyCoSync needs partners to feel like real co-op players in a shared story; Commonwealth Online is building the **infrastructure and presence layer** first, then expanding gameplay sync over time.
+
+---
+
+## Note on DoxyCoSync dedicated-server docs
+
+The file `DoxyCoSync/docs/dedicated-server-roadmap.md` describes an **experimental path** toward a dedicated CoSync Server — largely informed by Commonwealth Online's relay-server work. That document reflects **collaborative testing and exploration**, not DoxyCoSync's core product direction.
+
+**DoxyCoSync's intended model remains P2P for small groups.** Commonwealth Online's intended model remains dedicated-server-first for larger sessions. The roadmap doc is useful history and research; it is not a promise that DoxyCoSync will ship as a Minecraft-style hosted product.
+
+---
+
+## Why two projects?
+
+Fallout 4 multiplayer has more than one valid answer:
+
+- **Small co-op with friends** benefits from simple host-and-join, deep gameplay sync, and low operational overhead — DoxyCoSync.
+- **Server-hosted sessions with many players** benefits from an external relay, discovery, session management, and scale headroom — Commonwealth Online.
+
+Competing on the same niche would duplicate effort. Collaborating on research while targeting different scales and architectures lets both projects move faster and serve different communities.
+
+```text
+  Shared research                Different products
+  ─────────────                  ────────────────
+  Animation graphs          →    DoxyCoSync:  P2P co-op, ~4 players, deep sync
+  Server relay patterns     →    Commonwealth Online: dedicated server, 16+, presence first
+  Dev tooling ideas
+  Playtesting feedback
+```
+
+---
+
+## Collaboration in practice
+
+What we share:
+
+- Technical discoveries (animation graphs + weapon behavior, relay patterns, proxy spawning lessons)
+- Honest playtest feedback across both codebases
+- Occasional experimental docs or server prototypes tested in the other repo
+
+What stays separate:
+
+- Protocol and wire format
+- Plugin architecture and sync module design
+- Release targets, player counts, and hosting model
+- Creation Kit / Papyrus content tied to each mod's gameplay scope
+
+If you are choosing a mod: pick **DoxyCoSync** for small-group co-op with quests, workshop, and inventory today; pick **Commonwealth Online** if you want dedicated-server multiplayer with visible remote players and room to grow into larger sessions.
+
+If you are contributing: check which repo matches the scale and architecture you care about, and respect that both projects are allies, not forks of each other.
+
+---
+
+## References
+
+| Resource | Location |
+|---|---|
+| Commonwealth Online architecture | [`docs/architecture.md`](./architecture.md) |
+| Commonwealth Online protocol | [`docs/protocol.md`](./protocol.md) |
+| Commonwealth Online server | [`server/README.md`](../server/README.md) |
+| DoxyCoSync docs index | `DoxyCoSync/docs/README.md` |
+| DoxyCoSync dedicated-server roadmap (experimental) | `DoxyCoSync/docs/dedicated-server-roadmap.md` |
+
+*Last updated: 2026-07-02*