johan helsing.studio

Announcing Matchbox 0.4

I’m happy to announce that Matchbox 0.4 has finally been released on crates.io. Matchbox is a solution for painless peer-to-peer networking in rust web assembly.

To read more about why Matchbox was made and the problem it solves, please refer to the introductory post for 0.1. Most of it still applies, but 0.4 is the biggest change since, and has a few extra bells and whistles, so I felt a proper release announcement was warranted.

TL;DR:

  • New contributors and community :)
  • Native-to-native connections implemented for easier development or native-only games
  • Extreme Bevy: Matchbox, Bevy and GGRS web game tutorial series updated
  • TURN relay server support
  • Next-N style rooms (for simple matchmaking) now support scoping
  • GGRS socket feature updated for GGRS 0.9
  • Stability improvements
  • All public API is now documented
  • Firefox is (and was) broken

Initial reception, use-cases and collaboration

I was thrilled to see the response the initial release of Matchbox got. It was mentioned on this week in rust, and the repo quickly reached 100+ stars on github.

Since then, I collaborated closely with gschup, the creator of GGRS, to make the projects work smoothly together. GGRS is a rollback networking library, and is the perfect fit for Matchbox, in fact it’s why I made Matchbox in the first place, I wanted rollback networking in browsers. We also made a small game together, A Janitor’s Nightmare, for Bevy Jam #1.

Since then, I wrote a tutorial series, Extreme Bevy, to make the two projects more approachable to the Bevy community. This post quickly became my most visited post ever, so it’s clear people are interested.

As people started using Matchbox for their own projects. We got more contributors to the project.

tedsteen used Matchbox to implement online multiplayer for his NES bundler project which bundles NES roms into a single executable.

Screenshot of Nes Bundler

Native support

One of the most requested features was the ability to use this for non-web games as well. After some heavy refactoring, I’m now proud to say that Matchbox is now able to connect native peers using the webrtc-rs project.

One caveat, though, and also one of the main reasons 0.4 is so late, is that native-to-web cross play is still not supported. There are some slight differences in how connections are established. We have been working to solve this, but I decided not to let it further block the 0.4 release. Follow the issue on GitHub for updates to cross-play support.

However, even though we don’t have cross-play yet, this means that if you are developing a web game, you could easily test and develop it on native, or you could make a native-only game (like NES bundler) using Matchbox.

Thanks to sapir, who helped implementing and debugging this when I had been stuck for months and was about to lose hope.

TURN relay and authentication support

Sometimes, proper direct peer-to-peer connections fail because of bad/old network configurations etc. When this happens, WebRTC can use a TURN relay server to still get data through. Network traffic is not free, though, so in order to practically support this, authentication support was needed as well. Matchbox now supports configuring turn server urls and providing credentials.

The configuration is exposed through RtcIceServerConfig.

Many thanks to tedsteen who patiently helped reviewing the API and testing it in NES bundler. Also heartlabs who contributed the initial config API.

BREAKING: Next N style and id-based matchmaking unified

Previously, matchbox_server supported two types of rooms:

  1. id-based rooms, where a single key would scope peers. Everyone joining this id would be connected in a full-mesh network.
  2. next_n style rooms, where the next n peers to join would be connected in a full mesh, and then the next n peers to join would be connected in another full mesh.

E.g.:

wss://match.example.com/some_id

or

wss://match.example.com/next_2

These two types of rooms were mutually exclusive. For instance it was not possible to have two next_2 rooms with different scopes on the same matchbox_server instance.

In 0.4 these two endpoints have been merged using an optional query parameter for next_n style behavior. The new next_n style API is simply:

wss://match.example.com/some_id?next=2

A huge thanks to Vrixyz for implementing this!

Stability improvements and Firefox issues

  1. The initial implementation had a lot of .expect calls. Most of them have been removed in favor of retrying or sometimes just logging errors or warnings on non-fatal errors.
  2. Some production proxies would automatically kill the websocket connections to matchbox_server if no messages were sent for around 15 seconds. Matchbox_socket now sends empty KeepAlive messages a regular intervals to make sure this doesn’t happen.
  3. Matchbox server is now more robust against clients that send bogus data.

However, we are still have issues with Firefox connections dropping shortly after connecting. Initially I thought this a regression in Matchbox, and was another reason I delayed the 0.4 release for so long. Known regressions is one of my pet peeves, a new release should not be worse than a previous one if we can avoid it.

After some investigation, however, we discovered this was also happening with older versions of Matchbox. The confusing factor here was that installing the media panel extension (debug tools for webrtc) made the bug disappear. So looks like we got a proper heisenbug to deal with.

In any case, I’ve had this extension installed for a long time, so either Firefox connections never really worked properly in the first place, or there is a regression in Firefox itself. However, I’m now pretty confident I’ll not make the experience worse for anyone by releasing a new version.

Follow the progress on this issue. Thanks to everyone who helped report test and figure out that the media panel extension affected this bug. More leads and help with this would be extremely welcome!

Rustdocs for everything

All the public API is now documented with rustdoc. The readme is also included as crate level documentation. This should make the project usable only looking at its documentation on docs.rs

Some of the documentation is probably a bit brief. If you’re stuck or something is confusing, please don’t hesitate to make an issue for it on GitHub!

ggrs-socket feature simplified

The GGRS-specific WebRtcNonBlockingSocket has now been removed. WebRtcSocket simply implements the required GGRS trait instead.

Extreme bevy tutorial series updated

Speaking of documentation, during the long silence between 0.3 and 0.4, several new versions of Bevy had been released and people were struggling to follow the Extreme Bevy tutorial series. I waited so long as I wanted to make a 0.4 release first. Thanks to everyone who commented on the post and supported on the Bevy discord to help people along in the meantime.

The series has now been updated to Bevy 0.8, GGRS 0.9 and Matchbox 0.4, so it should at least be up-to-date for a couple of weeks until Bevy 0.9 is released :) I’m hoping to keep it more up-to-date going forward, though.

The series now has live playable demos embedded at the at end of each part, so you can easily try out the reference implementation along the way.

Also thanks to tracteurblinde who updated the matchbox_demo example to Bevy 0.8.

Future work

Going forward, the plan is to:

Where to go from here

If you’re interested in trying out the project, and are using Bevy, I definitely recommend Extreme Bevy: Making a peer to peer web game with Bevy, Matchbox and GGRS

If you’re doing something else, look at either the GitHub repository, or the crate documentation

Comments

Loading comments...