Commonwealth-Online-Public/protocol/packets.md

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:

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

Fields:

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:

{
  "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:

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:

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:

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

Fields:

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:

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.