# Architecture

## Current Architecture

```text
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 sends transform packets to the local Python server on
   `127.0.0.1:7777`.
3. The server assigns `playerId` values and sends `welcome` packets.
4. The plugin receives its `welcome` packet and stores its assigned `playerId`.
5. The server adds `playerId` and `serverTime` to transform packets.
6. The server broadcasts transform packets to other connected clients.
7. The plugin and `server/fake_client.py` store remote player state by `playerId`.
8. The server broadcasts `disconnect` packets when clients disconnect.
9. The plugin and fake client remove disconnected players from their remote
   player tables.

The Fallout 4 plugin still does not spawn or move 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
- Receiving server packets on a background thread
- Storing assigned and remote `playerId` state internally

Planned later:

- Applying remote player updates safely
- 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:

```text
Networking thread receives packets
Networking thread stores remote player state
Game update reads remote player state
Future game update applies actor movement
```

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 spawning or movement for a later game-thread milestone.

## Out Of Scope For Current Prototype

- Remote actor spawning
- Combat sync
- Quest sync
- Inventory sync
- Settlement sync
- Public servers or matchmaking