# 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 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:

```text
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