# Packet Types

This document describes the currently implemented local prototype packet types
for Commonwealth Online.

The current protocol is newline-separated JSON over a local TCP connection to
`127.0.0.1:7777`.

Implemented packet types:

- `welcome`
- `transform`
- `disconnect`

The current system is still a local networking prototype. It is not playable
multiplayer yet.

## Implemented

### Welcome Packet

Sent from the server to a newly connected client after the server assigns a
`playerId`.

Example:

```json
{
  "type": "welcome",
  "playerId": 1,
  "serverTime": 1780212098.457079
}
```

Fields:

```text
type        Packet type. Always "welcome".
playerId    Server-assigned player ID for this connection.
serverTime  Server timestamp when the welcome packet was created.
```

The Fallout 4 plugin and `server/fake_client.py` receive this packet. The plugin
stores the assigned `playerId` for filtering its own future transform echoes.

### Transform Packet

Sent by the Fallout 4 plugin to the local server when the local player's
transform changes. The server adds `playerId` and `serverTime`, then broadcasts
the processed packet to other connected clients.

Example after server processing:

```json
{
  "type": "transform",
  "playerId": 2,
  "x": -81781.26,
  "y": 87962.61,
  "z": 7696.05,
  "angleZ": 3.20,
  "movementType": "normal",
  "cellId": "0000DD60",
  "worldspaceId": "0000003C",
  "clientTime": 1780212128.301,
  "isMoving": true,
  "isSprinting": false,
  "isSneaking": false,
  "isJumping": false,
  "weaponDrawn": false,
  "movementSpeed": 186.4,
  "serverTime": 1780212128.3011043
}
```

Fields:

```text
type          Packet type. Always "transform".
playerId      Server-assigned player ID for the sender.
x             Local player X position.
y             Local player Y position.
z             Local player Z position.
angleZ        Local player Z rotation angle.
movementType  Movement classification for this transform update.
cellId        Current cell form ID as a string.
worldspaceId  Current worldspace form ID as a string.
clientTime    Timestamp generated by the sending plugin.
isMoving      Optional movement-state flag; defaults to false when missing.
isSprinting   Optional movement-state flag; defaults to false when missing.
isSneaking    Optional movement-state flag; defaults to false when missing.
isJumping     Optional movement-state flag; defaults to false when missing.
weaponDrawn   Optional weapon drawn state; defaults to false when missing.
movementSpeed Optional derived movement speed in game units per second; defaults to 0.0 when missing.
serverTime    Timestamp added by the server before broadcast.
```

Possible `movementType` values:

```text
normal
cell_change
worldspace_change
teleport
```

`cell_change` and `worldspace_change` are currently represented through
`movementType` inside transform packets. They are not separate packet types yet.

Movement state fields are data-only for now. Receivers must treat them as
optional and must not reject older transform packets when they are absent.

### Disconnect Packet

Sent by the server to remaining connected clients when a client disconnects.

Example:

```json
{
  "type": "disconnect",
  "playerId": 2,
  "serverTime": 1780212134.0
}
```

Fields:

```text
type        Packet type. Always "disconnect".
playerId    Server-assigned player ID that disconnected.
serverTime  Server timestamp when the disconnect packet was created.
```

The Fallout 4 plugin and `server/fake_client.py` use this packet to remove
remote players from their in-memory state tables.

## Receiver Behavior

The Fallout 4 plugin and fake client both receive:

```text
welcome
transform
disconnect
```

The plugin receive loop runs on a background networking thread. It stores plain
remote-player state only and does not spawn actors or touch Fallout 4 game
objects.

## Planned Later

- Remote actor spawning.
- Gameplay synchronization.