Document local networking prototype and protocol

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.

docs/architecture.md

@@ -1,5 +1,30 @@
 # Architecture
 
+## Current Architecture
+
+```text
+Fallout 4 Plugin
+        ↓
+Local Python Server
+        ↓
+Fake Client Remote Player State
+```
+
+The current system is one-way from the Fallout 4 plugin to the fake client:
+
+1. The Fallout 4 plugin reads local player transform data.
+2. The plugin sends transform packets to the local Python server on
+   `127.0.0.1:7777`.
+3. The server assigns `playerId` values and sends `welcome` packets.
+4. The server adds `playerId` and `serverTime` to transform packets.
+5. The server broadcasts transform packets to other connected clients.
+6. `server/fake_client.py` stores remote player state by `playerId`.
+7. The server broadcasts `disconnect` packets when clients disconnect.
+8. The fake client removes disconnected players from its remote player table.
+
+The Fallout 4 plugin does not yet receive remote transforms from the server.
+There is no plugin receive loop and no remote actor spawning yet.
+
 ## Main Components
 
 ### F4SE Plugin
@@ -9,8 +34,13 @@ The native plugin is responsible for:
 - Loading into Fallout 4
 - Reading local player state
 - Sending local player data to the server
+
+Planned later:
+
 - Receiving remote player data
+- Storing remote player state inside the plugin
 - Applying remote player updates safely
+- Spawning or moving remote actors
 
 ### External Server
 
@@ -18,13 +48,28 @@ 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 responsible for:
+The Creation Kit side is planned later and may be responsible for:
 
 - Test cells
 - Placeholder actors
@@ -34,6 +79,8 @@ The Creation Kit side is responsible for:
 
 ## Threading Model
 
+This is planned for the Fallout 4 receiving client. It is not implemented yet.
+
 Networking should run separately from game update logic.
 
 Recommended approach:
@@ -46,3 +93,13 @@ Game update applies actor movement
 ```
 
 The networking thread should avoid directly modifying Fallout 4 game objects unless the operation is known to be safe.
+
+## Out Of Scope For Current Prototype
+
+- Fallout 4 receive-loop processing
+- Remote actor spawning
+- Combat sync
+- Quest sync
+- Inventory sync
+- Settlement sync
+- Public servers or matchmaking

docs/dev-log.md

@@ -1,19 +1,20 @@
 # Development Log
 
-This file tracks the development progress of Fallout 4 Together.
+This file tracks development progress for Fallout 4 Together.
 
-Use this log to record setup decisions, tool versions, technical discoveries, failed experiments, and successful tests.
+Use this log to record setup decisions, tool versions, technical discoveries,
+failed experiments, successful tests, and next steps.
 
 ---
 
-## 2026-05-30
+## 2026-05-30 - Repository Setup
 
-### Repo Setup
+### What Changed
 
-* Created the Fallout 4 Together repository.
+- Created the Fallout 4 Together repository.
-* Added the initial repository folder structure.
+- Added the initial repository folder structure.
-* Added starter Markdown documentation files.
+- Added starter Markdown documentation files.
-* Added project roadmap, disclaimer, setup notes, protocol notes, and plugin planning documents.
+- Added project roadmap, disclaimer, setup notes, protocol notes, and plugin planning documents.
 
 ### Current Focus
 
@@ -21,21 +22,21 @@ The current focus is setting up the early development environment before writing
 
 The immediate priority is to make sure the project has:
 
-* A documented target Fallout 4 version
+- A documented target Fallout 4 version
-* A documented F4SE version
+- A documented F4SE version
-* A chosen CommonLibF4 plugin template
+- A chosen CommonLibF4 plugin template
-* A clean Fallout 4 test profile
+- A clean Fallout 4 test profile
-* A basic native plugin that can load through F4SE
+- A basic native plugin that can load through F4SE
 
 ### Decisions Made
 
-* Project name: Fallout 4 Together
+- Project name: Fallout 4 Together
-* Internal prefix: F4T
+- Internal prefix: F4T
-* Primary target platform: Steam Fallout 4
+- Primary target platform: Steam Fallout 4
-* First prototype goal: two clients in a controlled test cell, with each player visible as a synced remote actor
+- First prototype goal: two clients in a controlled test cell, with each player visible as a synced remote actor
-* Early test cell name: F4TTestCell01
+- Early test cell name: F4TTestCell01
-* Early test ESP name: Fallout4Together_Test.esp
+- Early test ESP name: Fallout4Together_Test.esp
-* Early plugin DLL name: Fallout4Together.dll
+- Early plugin DLL name: Fallout4Together.dll
 
 ### Current Status
 
@@ -50,46 +51,19 @@ No Creation Kit test cell yet
 
 ### Next Steps
 
-* Add `docs/version-targets.md` to the repository.
+- Add `docs/version-targets.md` to the repository.
-* Fill in the exact installed Fallout 4 version.
+- Fill in the exact installed Fallout 4 version.
-* Fill in the exact installed F4SE version.
+- Fill in the exact installed F4SE version.
-* Choose a CommonLibF4 plugin template.
+- Choose a CommonLibF4 plugin template.
-* Create the first GitHub milestones.
+- Create the first GitHub milestones.
-* Create the first GitHub issues.
+- Create the first GitHub issues.
-* Set up a clean Fallout 4 test profile.
+- Set up a clean Fallout 4 test profile.
-* Build an empty F4SE plugin.
+- Build an empty F4SE plugin.
-* Confirm the empty plugin loads in Fallout 4.
+- Confirm the empty plugin loads in Fallout 4.
 
 ---
 
-## Template Entry
+## 2026-05-31 - Initial DLL Load
-
-Use this format for future updates:
-
-```markdown
-## YYYY-MM-DD
-
-### What Changed
-
-- 
-
-### What Worked
-
-- 
-
-### What Broke
-
-- 
-
-### Notes
-
-- 
-
-### Next Steps
-
-- 
-```
-## 2026-05-31
 
 ### What Changed
 
@@ -120,8 +94,9 @@ Use this format for future updates:
 - Launch through F4SE again.
 - Confirm `Fallout4Together.log` is created.
 
+---
 
-## 2026-05-31
+## 2026-05-31 - Plugin Identity Renamed
 
 ### What Changed
 
@@ -151,7 +126,9 @@ Use this format for future updates:
 - Confirm the updated message appears in `Fallout4Together.log`.
 - Begin testing local player position readout.
 
-## 2026-05-31
+---
+
+## 2026-05-31 - Local Player Position Readout
 
 ### What Changed
 
@@ -174,10 +151,14 @@ Use this format for future updates:
 ### Notes
 
 - The first successful player position log was:
+
+```text
 Player position: X=2048.00, Y=2048.00, Z=0.00, AngleZ=0.00
+```
 
+---
 
-## 2026-05-31
+## 2026-05-31 - Movement Logging Throttled
 
 ### What Changed
 
@@ -207,7 +188,9 @@ Player position: X=2048.00, Y=2048.00, Z=0.00, AngleZ=0.00
 - Send player transform data from the plugin to the server.
 - Keep the first network test local-only.
 
-## 2026-05-31
+---
+
+## 2026-05-31 - Local Server Connection
 
 ### What Changed
 
@@ -243,7 +226,9 @@ Player position: X=2048.00, Y=2048.00, Z=0.00, AngleZ=0.00
 - Have the server echo/broadcast transform packets to connected clients.
 - Add a fake test client before attempting a second Fallout 4 client.
 
-## 2026-05-31
+---
+
+## 2026-05-31 - Transform Metadata Added
 
 ### What Changed
 
@@ -278,7 +263,10 @@ Player position: X=2048.00, Y=2048.00, Z=0.00, AngleZ=0.00
 - Add server-side client IDs.
 - Make the server broadcast transform packets to other connected clients.
 - Create a fake client to receive broadcast packets.
-## 2026-05-31
+
+---
+
+## 2026-05-31 - Server Broadcast And Fake Client
 
 ### What Changed
 
@@ -317,7 +305,9 @@ Player position: X=2048.00, Y=2048.00, Z=0.00, AngleZ=0.00
 - Add protocol documentation for `playerId`, `clientTime`, and `serverTime`.
 - Begin planning remote player state storage on the receiving client.
 
-## 2026-05-31
+---
+
+## 2026-05-31 - Full Broadcast Flow Tested
 
 ### What Changed
 
@@ -355,7 +345,9 @@ Player position: X=2048.00, Y=2048.00, Z=0.00, AngleZ=0.00
 - Store position, rotation, cellId, worldspaceId, movementType, and last update time.
 - Print a readable remote player state table.
 
-## 2026-05-31
+---
+
+## 2026-05-31 - Fake Client Remote State
 
 ### What Changed
 
@@ -388,7 +380,9 @@ Player position: X=2048.00, Y=2048.00, Z=0.00, AngleZ=0.00
 - Add disconnect packet broadcasting so fake clients can remove disconnected remote players.
 - Then begin planning a plugin receive loop for server messages.
 
-## 2026-05-31
+---
+
+## 2026-05-31 - Client Time Fixed
 
 ### What Changed
 
@@ -418,7 +412,9 @@ Player position: X=2048.00, Y=2048.00, Z=0.00, AngleZ=0.00
 - Add disconnect packets when a client leaves.
 - Have fake clients remove remote players when disconnect packets are received.
 
-## 2026-05-31
+---
+
+## 2026-05-31 - Disconnect Lifecycle
 
 ### What Changed
 
@@ -449,4 +445,68 @@ Player position: X=2048.00, Y=2048.00, Z=0.00, AngleZ=0.00
 
 - Add protocol documentation for welcome, transform, and disconnect packets.
 - Begin planning a Fallout 4 plugin receive loop.
-- Store remote player state inside the plugin, without spawning actors yet.
+- Store remote player state inside the plugin, without spawning actors yet.
+
+---
+
+## 2026-05-31 - Protocol Documentation Updated
+
+### What Changed
+
+- Documented the current networking protocol.
+- Documented welcome, transform, and disconnect packets.
+- Documented the fake client remote player state model.
+- Documented the current server and fake client test flow.
+
+### What Worked
+
+- The networking lifecycle now includes connect, welcome, transform broadcast, disconnect broadcast, and remote-player cleanup.
+- `clientTime` and `serverTime` are both present in transform packets.
+- The fake client can store and remove remote player state.
+
+### What Broke
+
+- Nothing recorded.
+
+### Notes
+
+- The Fallout 4 plugin does not yet receive server packets.
+- The current receiver is `server/fake_client.py`.
+- The next technical milestone is a Fallout 4 plugin receive loop that stores remote player state internally.
+
+### Next Steps
+
+- Add a plugin receive loop.
+- Parse welcome, transform, and disconnect packets in the plugin.
+- Store remote player state inside the plugin.
+- Do not spawn remote actors yet.
+
+---
+
+## Entry Template
+
+Use this format for future updates:
+
+```markdown
+## YYYY-MM-DD - Milestone Title
+
+### What Changed
+
+- ...
+
+### What Worked
+
+- ...
+
+### What Broke
+
+- ...
+
+### Notes
+
+- ...
+
+### Next Steps
+
+- ...
+```

protocol/message-types.md

@@ -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
+Remote actor spawning, combat, inventory, quest, settlement, and broader
-debug_log
+gameplay sync are planned later and are outside the current local prototype.
-debug_marker
-debug_error
-```
 
 ## Naming Rules
 

protocol/packets.md

@@ -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
+type        Packet type. Always "welcome".
-playerId
+playerId    Server-assigned player ID for this connection.
-serverTime
+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
+type          Packet type. Always "transform".
-playerId
+playerId      Server-assigned player ID for the sender.
-cellId
+x             Local player X position.
-worldspaceId
+y             Local player Y position.
-x
+z             Local player Z position.
-y
+angleZ        Local player Z rotation angle.
-z
+movementType  Movement classification for this transform update.
-pitch
+cellId        Current cell form ID as a string.
-yaw
+worldspaceId  Current worldspace form ID as a string.
-roll
+clientTime    Timestamp generated by the sending plugin.
-timestamp
+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
+type        Packet type. Always "disconnect".
-playerId
+playerId    Server-assigned player ID that disconnected.
-movementState
+serverTime  Server timestamp when the disconnect packet was created.
-weaponDrawn
-isCrouching
-isSprinting
-isAiming
-isFiring
 ```
 
-## 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
+## Planned Later
-type
+
-playerId
+- Fallout 4 plugin receive loop.
-reason
+- Plugin-side parsing of `welcome`, `transform`, and `disconnect` packets.
-```
+- Plugin-side remote player state storage.
+- Remote actor spawning.
+- Gameplay synchronization.

protocol/player-sync.md

@@ -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
+The Fallout 4 plugin does not yet receive remote transforms from the server.
-- Rotation
+The current receiver is `server/fake_client.py`.
-- Cell ID
-- Basic connection state
 
-## 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
-
+- Public networking or matchmaking
-## 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.

server/README.md

@@ -4,8 +4,13 @@ This folder is for the external multiplayer test server.
 
 The current server is a tiny local-only TCP test server. It listens on
 `127.0.0.1:7777`, accepts one or more clients, reads newline-separated JSON
-packets, prints received player transform packets, and broadcasts transform
+packets, assigns incrementing `playerId` values, sends `welcome` packets, adds
-packets to every other connected client.
+`playerId` and `serverTime` to transform packets, broadcasts transform packets
+to every other connected client, and broadcasts disconnect packets when clients
+disconnect.
+
+This is still a local prototype. It does not make Fallout 4 multiplayer
+playable yet.
 
 ## Run
 
@@ -14,14 +19,14 @@ cd server
 python server.py
 ```
 
-Then launch Fallout 4 through F4SE and move the player. The plugin should keep
+Then launch Fallout 4 through F4SE and move the player. The plugin should send
-logging player position changes to `Fallout4Together.log`, and this server
+local player transform packets, and this server should print matching
-should print matching `transform` packets.
+`transform` packets.
 
 If the server is not running, the plugin should log a warning and Fallout 4
 should continue launching normally.
 
-## Broadcast Test
+## Current Test Flow
 
 Terminal 1:
 
@@ -39,39 +44,51 @@ python fake_client.py
 
 Then launch Fallout 4 through F4SE and move the player.
 
-Expected result:
+Expected behavior:
 
 - The server assigns a `playerId` to each connected client and sends each client
   a `welcome` packet.
-- The fake client prints its `welcome` packet.
+- The server receives transforms from the Fallout 4 plugin.
-- The server prints transform packets received from Fallout 4.
+- The server adds `playerId` and `serverTime` to each transform packet before
-- The server adds `playerId` and `serverTime` to each transform packet.
+  broadcast.
 - The server broadcasts those transform packets to connected clients except the
   sender.
-- `fake_client.py` receives and prints the broadcast transform packets.
+- `fake_client.py` receives broadcast transform packets.
-- `fake_client.py` stores the latest remote player state for each `playerId`
+- `fake_client.py` stores remote player state by `playerId`.
-  in memory and prints a readable state summary after each transform update.
 - When a client disconnects, the server removes that client and broadcasts a
   `disconnect` packet with the departed `playerId` to the remaining clients.
 - `fake_client.py` removes disconnected players from its in-memory
-  `remote_players` table and prints the remaining tracked players.
+  `remote_players` table.
 
 The fake client exists so broadcast behavior can be tested before coordinating a
 second Fallout 4/F4SE instance. It stores remote player transform state only; it
 does not spawn remote actors or send movement.
 
-## Current Server Goals
+## Implemented
 
 - Start local server
 - Accept client connections
-- Receive transform packets
 - Assign server-owned player IDs
+- Send welcome packets
+- Receive transform packets
 - Add server timestamps
 - Broadcast transforms to other connected clients
-- Handle disconnects
+- Broadcast disconnect packets
+- Handle disconnect cleanup
 
-## Not Planned Yet
+## Working In Fake Client Only
 
+- Receiving welcome packets
+- Receiving transform broadcasts
+- Storing remote player state
+- Removing disconnected remote players
+
+The Fallout 4 plugin does not yet receive remote transforms from the server.
+
+## Planned Later
+
+- Fallout 4 plugin receive loop
+- Plugin-side remote player state storage
 - Remote actor spawning
 - Gameplay synchronization
 - Authentication