Commonwealth-Online-Public/docs/architecture.md

Architecture

Current Architecture

Fallout 4 Plugin ↔ Local Python Server ↔ Other Clients
        ↓
Plugin Remote Player State

The current system is still a local prototype, but the Fallout 4 plugin now has both send and receive paths:

1. The Fallout 4 plugin reads local player transform data.
2. The plugin derives basic movement state on the game-thread polling path and sends it as optional data on transform packets.
3. The plugin sends transform packets to the local Python server on 127.0.0.1:7777. Normal movement sends are throttled separately from movement logs, targeting roughly 10 Hz while the player is moving.
4. The server assigns playerId values and sends welcome packets.
5. The plugin receives its welcome packet and stores its assigned playerId.
6. The server adds playerId and serverTime to transform packets.
7. The server broadcasts transform packets to other connected clients.
8. The plugin and server/fake_client.py store remote player state by playerId.
9. The server broadcasts disconnect packets when clients disconnect.
10. The plugin and fake client remove disconnected players from their remote player tables.
11. On the game-thread update path, the plugin reads a copied remote-player snapshot and moves the single placed proxy actor in F4TTestCell01. Proxy visual updates are independent from local movement log throttling: normal movement is smoothed toward the latest target, while cell changes, worldspace changes, and teleports snap directly.

The Fallout 4 plugin still does not dynamically spawn remote actors.

Main Components

F4SE Plugin

The native plugin is responsible for:

• Loading into Fallout 4
• Reading local player state
• Sending local player data to the server
• Adding basic data-only movement state to transform packets
• Throttling normal transform sends separately from readable local movement logs
• Receiving server packets on a background thread
• Storing assigned and remote playerId state internally
• Moving the single placed test proxy actor from remote-player state on the game thread

Planned later:

• Spawning or moving remote actors

External Server

The server is responsible for:

• Accepting client connections
• Assigning player IDs
• Sending welcome packets
• Receiving player state
• Broadcasting player state
• Tracking disconnects
• Broadcasting disconnect packets

Fake Client

The fake client is responsible for:

• Connecting to the local server
• Receiving welcome packets
• Receiving broadcast transform packets
• Storing remote player state by playerId
• Removing remote players when disconnect packets arrive

The fake client is a temporary receiver for testing the networking lifecycle. It does not spawn remote actors or represent playable multiplayer.

Creation Kit Plugin

The Creation Kit side is planned later and may be responsible for:

• Test cells
• Placeholder actors
• Optional Papyrus helper scripts
• Debug objects
• Controlled test environments

Threading Model

Networking should run separately from game update logic.

Current approach:

Game update reads local player transform
Game update derives basic movement state
Game update sends thresholded transform packets around 10 Hz while moving
Game update logs local movement around 1 Hz
Networking thread receives packets
Networking thread stores remote player state
Game update reads a copied remote player snapshot
Game update moves the placed test proxy actor

The networking receive thread does not directly modify Fallout 4 actors or game objects. It parses newline-separated JSON, updates plain C++ remote-player state, and leaves actor access to F4TProxyActorController on the game-thread update path.

Out Of Scope For Current Prototype

• Remote actor spawning
• Multiple proxy actors
• Animation graph sync or animation application
• Combat sync
• Quest sync
• Inventory sync
• Settlement sync
• Public servers or matchmaking