Skip to content

Update unreal sdk to use v3 websocket api#4764

Open
joshua-spacetime wants to merge 2 commits intojoshua/ws/v3from
joshua/unreal/v3-ws-bindings
Open

Update unreal sdk to use v3 websocket api#4764
joshua-spacetime wants to merge 2 commits intojoshua/ws/v3from
joshua/unreal/v3-ws-bindings

Conversation

@joshua-spacetime
Copy link
Copy Markdown
Collaborator

@joshua-spacetime joshua-spacetime commented Apr 9, 2026

Description of Changes

This PR adds Unreal/C++ SDK support for the v3.bsatn.spacetimedb WebSocket API which was added in #4761.

v3 is implemented as a thin transport envelope around the existing v2 logical message schema. The SDK continues to use the generated v2 ClientMessage / ServerMessage types for logical protocol handling, while v3 is used only to wrap and unwrap already-encoded v2 payloads.

On the Unreal SDK side, this PR adds:

  • v3 transport frame support via ClientFrame::{Single, Batch} and ServerFrame::{Single, Batch}
  • v3-preferred connection behavior with fallback to v2
  • outbound batching of already-encoded v2 client messages when v3 is active
  • inbound unwrapping of v3 server frames into ordered v2 logical messages before normal processing
  • a 256 KiB cap for each outbound v3 frame
  • deferred follow-up flushes so oversized outbound queues do not monopolize a single game-thread turn

The batching behavior is intentionally transport-only:

  • v2 logical messages remain unchanged
  • message ordering is preserved
  • existing cache / update processing continues to run on v2 logical messages after v3 unwrapping

One Unreal-specific implementation detail is that the SDK currently uses a single subprotocol string per connection attempt, so v3/v2 fallback is implemented as “try v3 first, retry with v2 if the initial connection fails,” rather than browser-style multi-protocol negotiation in a single handshake.

This PR also adds focused BSATN roundtrip coverage for the new v3 frame types and updates maintainer docs to clarify that Unreal still uses generated v2 logical bindings while the v3 transport envelope is hand-written.

API and ABI breaking changes

None. Existing v2-only servers continue to work via fallback, and the logical client message API exposed to SDK users is unchanged.

Expected complexity level and risk

3

The main risks are:

  • preserving v2 behavior when v3 is not active
  • preserving message ordering when a single v3 frame contains multiple logical messages
  • keeping fallback behavior correct during initial connection
  • avoiding subtle scheduling regressions on the game thread

Testing

  • Added BSATN roundtrip tests for FClientFrame::{Single, Batch} and FServerFrame::{Single, Batch}
  • Added protocol negotiation and inbound message ordering integration tests

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant