# Player Sync

Player synchronization is the first major technical goal for Fallout 4 Together.
The current implementation is still a local networking prototype.

## Current Implemented Flow

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

The Fallout 4 plugin currently reads the local player's transform and sends it
to the local Python server. The server assigns a `playerId`, adds `serverTime`,
and broadcasts transform packets to other connected clients.

The Fallout 4 plugin also receives server packets on a background networking
thread. It stores its assigned `playerId`, stores remote transform state by
remote `playerId`, and removes remote state when disconnect packets arrive.
`server/fake_client.py` remains a lightweight test receiver for the same packet
lifecycle.

## Current Remote Player State Model

The plugin and fake client store remote players by `playerId`.

Each remote player state entry tracks:

```text
playerId
x
y
z
angleZ
movementType
cellId
worldspaceId
clientTime
serverTime
lastReceivedLocalTime
```

This model proves the data shape and lifecycle before spawning remote actors.

## Implemented

- The plugin sends local player transform packets.
- The plugin receives `welcome` packets and stores its assigned `playerId`.
- The plugin receives broadcast transform packets.
- The plugin ignores transform packets for its own assigned `playerId`.
- The plugin stores remote player state by `playerId`.
- The plugin receives `disconnect` packets and removes remote player state.
- The server assigns incrementing `playerId` values.
- The server sends `welcome` packets.
- The server adds `playerId` and `serverTime` to transform packets.
- The server broadcasts transform packets to other connected clients.
- The fake client stores remote player state by `playerId`.
- The server broadcasts `disconnect` packets.
- The fake client removes disconnected remote players from its state table.

No Fallout 4 remote actor is spawned yet.

## Planned Later

- Add interpolation or smoothing after plugin-side state exists.
- Spawn and move remote actors only after the receive loop is stable.

## Not Required Yet

- Full animation graph sync
- Combat sync
- Inventory sync
- Quest sync
- Dialogue sync
- Settlement sync
- Accurate physics sync
- Public networking or matchmaking