Commonwealth-Online/Commonwealth-Online-Public
3
0
Fork 0
Code Pull Requests Activity

Document local networking prototype and protocol

Browse Source 
Expand documentation to describe the current local networking prototype and its protocol. Adds a Current Architecture section and Fake Client responsibilities, clarifies that the Fallout 4 plugin currently only sends transforms (no receive loop yet), and documents implemented message types (welcome, transform, disconnect) with packet field descriptions and examples. Update player-sync and packets docs to reflect movementType, server/client timestamps, and the in-memory remote player state model used by server/fake_client.py. Flesh out server/README with run/test flow and implemented behavior. Revise dev-log with milestone entries, testing notes, and an entry template for future updates.
This commit is contained in:
andrew
2026-05-31 19:28:58 +12:00
parent 52d934dab0
commit d724d7404c
6 changed files with 435 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files
protocol/message-types.md
+38 -13
View File
@@ -1,37 +1,62 @@
# Message Types
This file tracks planned message type names for the Fallout 4 Together protocol.
This file tracks current and planned message type names for the Fallout 4
Together local networking prototype.
## Core Messages
## Implemented
These message types are currently implemented:
```text
welcome
transform
disconnect
ping
pong
```
## Planned Gameplay Messages
Current behavior:
- `welcome` is sent by the server after assigning a `playerId`.
- `transform` is sent by the Fallout 4 plugin, processed by the server, and
broadcast to other connected clients.
- `disconnect` is sent by the server when a client disconnects.
The Fallout 4 plugin currently sends transform packets only. It does not yet
receive or process server packets.
## Working In Fake Client Only
`server/fake_client.py` currently receives:
```text
welcome
transform
disconnect
```
The fake client stores broadcast transform packets in an in-memory remote player
state table and removes entries when disconnect packets arrive.
## Planned Later
These message types are planned but not implemented yet:
```text
ping
pong
chat_message
animation_state
weapon_fire
weapon_reload
health_update
chat_message
cell_change
actor_spawn
actor_remove
```
## Debug Messages
`cell_change` is currently represented through the `movementType` field inside
`transform` packets. It is not its own packet type yet.
```text
debug_log
debug_marker
debug_error
```
Remote actor spawning, combat, inventory, quest, settlement, and broader
gameplay sync are planned later and are outside the current local prototype.
## Naming Rules
protocol/packets.md
+109 -37
View File
@@ -1,64 +1,136 @@
# Packet Types
This document describes planned packet types for the multiplayer prototype.
This document describes the currently implemented local prototype packet types
for Fallout 4 Together.
## Welcome Packet
The current protocol is newline-separated JSON over a local TCP connection to
`127.0.0.1:7777`.
Sent from server to client after connection.
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
playerId
serverTime
type Packet type. Always "welcome".
playerId Server-assigned player ID for this connection.
serverTime Server timestamp when the welcome packet was created.
```
## Transform Packet
The Fallout 4 plugin does not yet read this packet. `server/fake_client.py`
currently receives and prints it.
Sent from client to server and broadcast to other clients.
### 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,
"serverTime": 1780212128.3011043
}
```
Fields:
```text
type
playerId
cellId
worldspaceId
x
y
z
pitch
yaw
roll
timestamp
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.
serverTime Timestamp added by the server before broadcast.
```
## Animation State Packet
Possible `movementType` values:
Planned later.
```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.
### 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
playerId
movementState
weaponDrawn
isCrouching
isSprinting
isAiming
isFiring
type Packet type. Always "disconnect".
playerId Server-assigned player ID that disconnected.
serverTime Server timestamp when the disconnect packet was created.
```
## Disconnect Packet
`server/fake_client.py` currently uses this packet to remove remote players from
its in-memory state table.
Sent when a player leaves.
## Working In Fake Client Only
Fields:
- Receiving `welcome` packets.
- Receiving broadcast `transform` packets from other clients.
- Storing remote player state by `playerId`.
- Removing remote player state when `disconnect` packets arrive.
```text
type
playerId
reason
```
## Planned Later
- Fallout 4 plugin receive loop.
- Plugin-side parsing of `welcome`, `transform`, and `disconnect` packets.
- Plugin-side remote player state storage.
- Remote actor spawning.
- Gameplay synchronization.
protocol/player-sync.md
+67 -35
View File
@@ -1,51 +1,83 @@
# Player Sync
Player synchronization is the first major technical goal for Fallout 4 Together.
The current implementation is still a local networking prototype.
## First Goal
## Current Implemented Flow
The first goal is to represent remote players as placeholder actors in a controlled test cell.
```text
Fallout 4 Plugin
↓
Local Python Server
↓
Fake Client Remote Player State
```
The first version only needs to sync:
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.
- Position
- Rotation
- Cell ID
- Basic connection state
The Fallout 4 plugin does not yet receive remote transforms from the server.
The current receiver is `server/fake_client.py`.
## Not Required at First
## Current Remote Player State Model
The first version does not need:
The fake client stores remote players by `playerId`.
Each remote player state entry tracks:
```text
playerId
x
y
z
angleZ
movementType
cellId
worldspaceId
clientTime
serverTime
lastReceivedLocalTime
```
This model is a prototype for the eventual Fallout 4 receiving client. The goal
is to prove the data shape and lifecycle before adding a plugin receive loop or
spawning remote actors.
## Implemented
- The plugin sends local player transform packets.
- 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.
## Working In Fake Client Only
- Receiving broadcast transform packets.
- Tracking remote player state.
- Handling disconnect cleanup.
No Fallout 4 remote actor is spawned yet.
## Planned Later
- Add a Fallout 4 plugin receive loop.
- Parse `welcome`, `transform`, and `disconnect` packets in the plugin.
- Store remote player state inside the plugin.
- 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
## Transform Sync
Each client should send its local player transform to the server.
The server should broadcast that transform to other clients.
Remote clients should move placeholder actors based on the received transform.
## Smoothing
Remote players should not snap instantly to every received transform.
Instead, remote actors should interpolate toward the latest received position.
Basic idea:
```text
current actor position + latest network position = smoothed visual position
```
## Same-Cell Restriction
Early prototypes should require all players to remain in the same test cell.
Cell transitions should not be supported until basic player sync is stable.
- Public networking or matchmaking