shadow-over-bishkek001/WEBSOCKET_NETWORKING.md

WebSocket Networking: First Iteration

Scope

The first networking iteration adds a Windows-only WebSocket transport using Boost.Asio and Boost.Beast.

The goal of this iteration is connection and replication stability. It does not yet implement multiplayer commands, authentication, per-connection players, state deltas, or presentation-event replication.

Runtime Architecture

Server

WebsocketGameServer wraps the headless InternalGameServer.

• It accepts any WebSocket connection.
• It sends the current complete game state immediately after connection.
• It broadcasts the current complete state every five seconds.
• Incoming WebSocket messages are read and discarded.
• The authoritative simulation remains on the main server thread.
• Network sessions only receive serialized state and never access InternalGameServer directly.

The standalone server creates the existing fixed player ID "player" and does not enable the battle-zone test bot.

Client

WebsocketGameClient implements IGameServer.

• It connects asynchronously to ws://127.0.0.1:8080/.
• Received messages are queued by the network thread and applied on the game thread from update().
• It maintains an internal InternalGameServer replica so existing snapshot consumers and transitional runtime-state bindings continue to work.
• Camera orientation lives in host-owned LocationLocalState, so incoming authoritative snapshots cannot overwrite camera movement.
• submit() intentionally discards all commands.
• drainEvents() returns no events.
• Client-side save and load calls are ignored because persistence remains server-side.

RemoteGameServerHost prepares local presentation resources and runtime locations against the replicated state. It does not advance authoritative simulation or write Lua/dialogue auxiliary state back to the server.

Campaign Routing

The graphical game uses stable router objects for IGameServer and IGameServerHost, allowing existing UI and runtime references to remain valid.

When NETWORK is defined:

• battle_zone_multiplayer uses WebsocketGameClient and RemoteGameServerHost.
• main, battle_zone, and every other campaign use InternalGameServer and LocalGameServerHost.

The WebSocket client is created only when battle_zone_multiplayer is selected and is destroyed when that campaign is unloaded. The single-player and multiplayer Battle Zone entries share location content and the start-state path, so the state can be regenerated through the single-player entry. At startup, the standalone server loads the authoritative half of that shared save and rewrites its campaign ID to battle_zone_multiplayer; each remote client restores only the local presentation half.

If DNS resolution, TCP connection, the WebSocket handshake, or the active socket fails, the client unloads the remote campaign and returns to the campaign selection screen.

JSON Protocol

Messages use a versioned JSON envelope:

{
  "protocolVersion": 1,
  "type": "state",
  "payload": {
    "schemaVersion": 2
  }
}

The payload uses the authoritative GameState::save() representation and excludes the client-local location map, including camera orientation. The client applies it through InternalGameServer::load().

Malformed JSON, unsupported protocol versions, unsupported message types, and invalid state payloads are logged and ignored.

Single-player persistence uses a separate envelope that combines this authoritative document with client-local location state. The temporary full-state network format is still expected to be replaced by a dedicated replication schema or deltas as command handling and production replication are implemented.

Build Configuration

Networking is enabled only for Windows:

• proj-windows/CMakeLists.txt defines NETWORK, compiles the WebSocket client and remote host, and links ws2_32 and mswsock.
• server/CMakeLists.txt defines NETWORK for the Windows GameServer, compiles the WebSocket server, and links the Windows socket libraries.
• Linux, Android, and Web builds do not define NETWORK and do not compile the network transport.

The previous Web-build NETWORK definition was removed.

Running

Build the server:

cmake -S server -B server/build
cmake --build server/build --config Debug --target GameServer

Run it from the repository root:

.\server\build\Debug\GameServer.exe --campaign battle_zone_multiplayer --location uni_exterior

The listener defaults to 0.0.0.0:8080. It can be changed with:

--address IP
--port N

Launch the Windows game and select battle_zone_multiplayer. The client connects to 127.0.0.1:8080. Selecting another campaign continues to use the local server.

Verification

The implementation was verified with:

• A successful Windows graphical-game build.
• A successful Windows headless-server build.
• Server state and protocol tests.
• A WebSocket smoke test receiving the initial state and the next five-second broadcast.
• A check that the shared "player" exists and the battle-zone test bot is not created for the network server.

Current Limitations

• All clients share the fixed player ID "player".
• Client commands are not sent to the server.
• The server does not process commands.
• State is sent as a complete snapshot rather than a delta.
• There is no authentication, authorization, reconnect loop, or session identity.
• Presentation events are not replicated.
• The endpoint is hardcoded in the graphical client.
• Multiplayer Lua and dialogue behavior remains unsupported.