Add plugin receive loop & remote player state

Add a networking receive loop and in-plugin remote-player storage. Introduces F4TRemotePlayerState (header + implementation) to track assigned playerId and remote player snapshots with thread-safe access. Expands F4TNetworking to start/stop a background receive thread, parse newline-separated JSON packets (welcome, transform, disconnect), validate fields, update remote state, throttle logs, and handle socket/thread synchronization. Add nlohmann_json to xmake and plugin build. Update docs and dev log to reflect the new receive behavior and current prototype scope.

docs/architecture.md

@@ -3,27 +3,27 @@
 ## Current Architecture
 
 ```text
-Fallout 4 Plugin
+Fallout 4 Plugin ↔ Local Python Server ↔ Other Clients
         ↓
-Local Python Server
-        ↓
-Fake Client Remote Player State
+Plugin Remote Player State
 ```
 
-The current system is one-way from the Fallout 4 plugin to the fake client:
+The current system is still a local prototype, but the Fallout 4 plugin now has
+both send and receive paths:
 
 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.
+4. The plugin receives its `welcome` packet and stores its assigned `playerId`.
+5. The server adds `playerId` and `serverTime` to transform packets.
+6. The server broadcasts transform packets to other connected clients.
+7. The plugin and `server/fake_client.py` store remote player state by `playerId`.
+8. The server broadcasts `disconnect` packets when clients disconnect.
+9. The plugin and fake client remove disconnected players from their remote
+   player tables.
 
-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.
+The Fallout 4 plugin still does not spawn or move remote actors.
 
 ## Main Components
 
@@ -34,11 +34,11 @@ The native plugin is responsible for:
 - Loading into Fallout 4
 - Reading local player state
 - Sending local player data to the server
+- Receiving server packets on a background thread
+- Storing assigned and remote `playerId` state internally
 
 Planned later:
 
-- Receiving remote player data
-- Storing remote player state inside the plugin
 - Applying remote player updates safely
 - Spawning or moving remote actors
 
@@ -79,24 +79,23 @@ The Creation Kit side is planned later and may be 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:
+Current approach:
 
 ```text
 Networking thread receives packets
 Networking thread stores remote player state
 Game update reads remote player state
-Game update applies actor movement
+Future game update applies actor movement
 ```
 
-The networking thread should avoid directly modifying Fallout 4 game objects unless the operation is known to be safe.
+The networking receive thread does not directly modify Fallout 4 actors or game
+objects. It parses newline-separated JSON, updates plain C++ remote-player
+state, and leaves actor spawning or movement for a later game-thread milestone.
 
 ## Out Of Scope For Current Prototype
 
-- Fallout 4 receive-loop processing
 - Remote actor spawning
 - Combat sync
 - Quest sync

docs/dev-log.md

@@ -483,6 +483,39 @@ Player position: X=2048.00, Y=2048.00, Z=0.00, AngleZ=0.00
 
 ---
 
+## 2026-05-31 - Plugin Receive State Implemented
+
+### What Changed
+
+- Added plugin-side receiving for server `welcome`, `transform`, and `disconnect` packets.
+- Added internal remote player state storage keyed by server-assigned `playerId`.
+- Added defensive packet parsing so malformed or unknown packets are ignored without crashing the plugin.
+- Kept remote actor spawning and movement out of scope.
+
+### What Worked
+
+- The plugin now stores its assigned server `playerId`.
+- Remote transforms can be stored internally without touching Fallout 4 actors or game objects.
+- Disconnect packets remove remote player state.
+- `xmake build` succeeds.
+
+### What Broke
+
+- Nothing recorded.
+
+### Notes
+
+- The receive loop runs on a background networking thread.
+- Remote transform logging is throttled so `Fallout4Together.log` remains readable.
+- Actor spawning, actor movement, animation sync, combat sync, inventory sync, quest sync, and settlement sync remain planned later.
+
+### Next Steps
+
+- Test with Fallout 4 launched through F4SE against `server/server.py`.
+- Add a controlled game-thread reader for remote player snapshots before any actor spawning work.
+
+---
+
 ## Entry Template
 
 Use this format for future updates: