Crate matchbox_socket 

Painless peer-to-peer WebRTC networking for rust’s native and wasm applications.

The goal of the Matchbox project is to enable udp-like, unordered, unreliable p2p connections in web browsers or native to facilitate low-latency multiplayer games.

Matchbox supports both unreliable and reliable data channels, with configurable ordering guarantees and variable packet retransmits.

• Tutorial for usage with Bevy and GGRS

The Matchbox project contains:

• matchbox_socket: A socket abstraction for Wasm or Native, with:

  • ggrs: A feature providing a ggrs compatible socket.

• matchbox_signaling: A signaling server library, with ready to use examples

• matchbox_server: A ready to use full-mesh signalling server

• bevy_matchbox: A matchbox_socket integration for the Bevy game engine

  bevy	bevy_matchbox
  0.17	0.13, main
  0.16	0.12
  0.15	0.11
  0.14	0.10
  0.13	0.9
  0.12	0.8
  0.11	0.7
  0.10	0.6
  < 0.9	Unsupported

Examples

• simple: A simple communication loop using matchbox_socket
• bevy_ggrs: An example browser game, using bevy and bevy_ggrs
  • Live 2-player demo: https://helsing.studio/box_game/
  • Live 4-player demo: https://helsing.studio/box_game/?players=4

How it works

WebRTC allows direct connections between peers, but in order to establish those connections, some kind of signaling service is needed. matchbox_server is such a service. Once the connections are established, however, data will flow directly between peers, and no traffic will go through the signaling server.

The signaling service needs to run somewhere all clients can reach it over http or https connections. In production, this usually means the public internet.

When a client wants to join a p2p (mesh) network, it connects to the signaling service. The signaling server then notifies the peers that have already connected about the new peer (sends a NewPeer event).

Peers then negotiate a connection through the signaling server. The initiator sends an “offer” and the recipient responds with an “answer.” Once peers have enough information relayed, a RTCPeerConnection is established for each peer, which comes with one or more data channels.

All of this, however, is hidden from rust application code. All you will need to do on the client side, is:

• Create a new socket, and give it a signaling server url
• .await the message loop future that processes new messages.
  • If you are using Bevy, this is done automatically by bevy_matchbox (see the bevy_ggrs example).
  • Otherwise, if you are using WASM, wasm-bindgen-futures can help (see the simple example).
  • Alternatively, the future can be polled manually, i.e. once per frame.

You can hook into the lifecycle of your socket through the socket’s API, such as connection state changes. Similarly, you can send packets to peers using the socket through a simple, non-blocking method.

Showcase

Projects using Matchbox:

• NES Bundler - Transform your NES game into a single executable targeting your favorite OS!
• Cargo Space (in development) - A coop 2D space game about building and flying a ship together
• Extreme Bevy - Simple 2-player arcade shooter
• Matchbox demo
• A Janitors Nightmare - 2-player jam game
• Lavagna - collaborative blackboard for online meetings

Contributing

PRs welcome!

If you have questions or suggestions, feel free to make an issue. There’s also a Discord channel if you want to get in touch.

Thanks

• A huge thanks to Ernest Wong for his Dango Tribute experiment! matchbox_socket is heavily inspired its wasm-bindgen server_socket and Matchbox would probably not exist without it.

License

All code in this repository dual-licensed under either:

• MIT License or http://opensource.org/licenses/MIT
• Apache License, Version 2.0 or http://www.apache.org/licenses/LICENSE-2.0

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Re-exports

pub use async_trait;

Structs

ChannelConfig

Configuration options for a data channel See also: https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel

PeerId

The format for a peer signature given by the signaling server

RtcIceServerConfig

Configuration options for an ICE server connection. See also: https://developer.mozilla.org/en-US/docs/Web/API/RTCIceServer#example

WebRtcChannel

Used to send and receive packets on a given WebRTC channel. Must be created as part of a WebRtcSocket.

WebRtcSocket

Contains a set of WebRtcChannels and connection metadata.

WebRtcSocketBuilder

Builder for WebRtcSockets.

Enums

ChannelError

An error that can occur when getting a socket’s channel through get_channel, take_channel or try_update_peers.

Error

Errors that can happen when using Matchbox sockets.

PeerSignal

Signals go from peer to peer via the signaling server

PeerState

The state of a connection to a peer

SignalingError

An error that can occur with WebRTC messaging. See [Signaller].

Traits

Signaller

A signalling implementation.

SignallerBuilder

A builder that constructs a new Signaller from a room URL.

Type Aliases

MessageLoopFuture

A future which runs the message loop for the socket and completes when the socket closes or disconnects

Packet

The raw format of data being sent and received.

PeerEvent

Events go from signaling server to peer

PeerRequest

Requests go from peer to signaling server