6 releases (breaking)
|0.5.0||Jan 13, 2023|
|0.4.0||Oct 27, 2022|
|0.2.0||Jan 10, 2022|
|0.1.1||Sep 13, 2021|
|0.0.1||Sep 11, 2021|
#902 in Network programming
43 downloads per month
Painless peer-to-peer WebRTC networking for rust wasm applications.
The goal of the Matchbox project is to enable udp-like, unordered, unreliable p2p connections in web browsers to facilitate low-latency multiplayer games.
It is currently an all-in-one solution, it comes with:
- A tiny signalling server, matchbox_server. Written in rust, uses only a couple of megabytes of memory. Also available as a docker image.
- An example browser game, using
- A socket abstraction for rust wasm, matchbox_socket
- With a feature,
ggrs-socketfor providing a ggrs compatible socket.
- With a feature,
- 2-player demo: https://helsing.studio/box_game/
- 4-player demo: https://helsing.studio/box_game/?players=4
Open each link in a separate browser window (or machine).
When enough players have joined, you should see a couple of boxes, one of which
you can move around using the
You can open the browser console to get some rough idea about what's happening (or not happening if that's the unfortunate case).
How it works
WebRTC allows direct connections between peers, but in order to establish
those connections, some kind of signalling 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 signalling server.
The signalling 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 signalling
service and provides a room id. The signalling server then notifies the peers
that have already connected about the new peer (sends a
The existing peers then send back WebRTC connection offers through the signalling service to the new client, each of which the new client responds with an "answer". Once the peers have enough information about each other, a WebRTCPeerConnection is established for each peer, and an unreliable, unordered data channel is opened.
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 signalling server url and a room id
.awaitthe message loop future that processes new messages. If you are using Bevy, it can be spawned as a Bevy io task (see
matchbox_simple_demofor usage with
wasm-bindgen-futures. Alternatively, the future can be polled manually (at least once per frame).
You will then get notified whenever a new peer data connection has been
established, and you will get all packets from peers in a single channel.
Packets include a boxed
u8 slice and the corresponding client's id.
Similarly, you can send packets to clients using a simple non-blocking method.
matchbox_server supports a rudimentary form of matchmaking. By appending
?next=3 to the room id, the next three players to join will be connected, and
then the next three players will be connected separately to the first three.
You can also use the room id for scoping what kind of players you want to
Projects using Matchbox:
- NES Bundler - Transform your NES game into a single executable targeting your favorite OS!
- Extreme Bevy - Simple 2-player arcade shooter
- Matchbox demo
- A Janitors Nightmare - 2-player jam game
- A huge thanks to Ernest Wong for his Dango Tribute
matchbox_socketis heavily inspired its wasm-bindgen server_socket and Matchbox would probably not exist without it.
All code in this repository dual-licensed under either:
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
- Apache License, Version 2.0 (LICENSE-APACHE 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.