---
description: Commonwealth Online project architecture and goals
alwaysApply: true
---

# Project Overview

Commonwealth Online is an experimental Fallout 4 multiplayer mod. It uses a C++ F4SE plugin, a Python relay server, fake clients for protocol testing, and project documentation in `docs/`.

The goal is to sync players across separate Fallout 4 instances by sending player transform and state data through a server, then representing remote players in-game with proxy actors.

The current sync model includes player transforms, cell/worldspace IDs, heading, and movement state such as moving, speed, sprinting, sneaking, jumping, and weapon drawn.

Preserve the existing server-authoritative relay architecture unless specifically told otherwise. The project is not trying to fully merge game worlds: each player runs their own local Fallout 4 instance, and the server distributes state updates between clients.

Important project areas:
- `plugin/src/main.cpp`: C++ F4SE plugin entry point and game integration.
- `server/server.py`: Python relay server.
- `server/fake_client.py`: fake testing client for protocol and relay checks.
- `docs/`: architecture, setup, protocol, testing, and milestone documentation.
- `changelog.md`: dated record of every code and documentation change (no testing notes).
- `docs/dev-log.md`: milestone history, testing results, discoveries, and next steps.

Cursor workflow:
- Read relevant files before editing.
- Make minimal focused changes.
- Avoid breaking already-working transform sync.
- Avoid speculative rewrites or unrelated feature work.
- Keep changes understandable for an iterative prototype.
- Explain changes after applying them and mention assumptions made.