Feb 18, 2025

Colyseus 0.16 is here!

Introducing StateView. Experimental WebTransport support, and more.

By Endel Dreyer

---

I’m thrilled to share version 0.16 of Colyseus is here! 🎉

This version brings a new iteration of the @colyseus/schema library, introducing the StateView API, deprecating @filter(), and providing quality of life improvements to the framework.

Introducing StateView ✨

The StateView is the new way to filter data per client. It replaces the @filter() and @filterChildren() decorators, allowing you to create a “view” that can be used to manually add or remove items visible only to a particular client.

It is still not recommended to rely on StateView for big datasets, as it is not optimized for that yet. However, it is a great way to filter data per client, such as “private fields” per schema instance, “level of detail”, area-based, team-owned data, and more.

See StateView 📚 for more.

Documentation has been reworked 🎉

The documentation got a brand new look, and got restructured, which is now easier to extend and navigate.

Shout out to a special page dedicated to the Community 📚, where you can find open-source projects and content created by the community.

Experimental WebTransport support 🔌

WebTransport is a really exciting new technology. It is built on top of the QUIC protocol, which uses UDP instead of TCP, and in practical terms, it allows for unreliable delivery of messages — which is a great fit for real-time multiplayer games.

It is important for Colyseus to incorporate the new concepts that WebTransport brings, so we can improve its internal and external APIs to support both WebTransport and WebSockets using the same API. In this initial iteration, unreliable delivery is only supported when using WebTransport via the client.sendUnreliable() method from the client-side. We’d love to support more features in the future, such as unreliable portions of the state, even when using WebSockets.

See WebTransport 📚 for more.

Quality of life improvements 🛠

1. You can now set the state and patchRate directly on the Room class definition, along with maxClients and autoDispose properties:

class MyRoom extends Room {
  state = new MyState();
  patchRate = 1000 / 10;
  autoDispose = false;
  maxClients = 20;
}

2. The onAuth method now receives a context argument instead of req:

class MyRoom extends Room {
  async onAuth(client, options, context) {
    // - context.token contains the auth token sent by the client
    // - context.headers contains the request headers
    // - context.ip contains the client's IP address
  }
}

Both static and instance onAuth methods are supported and receive 3 arguments. See the differences in Room Authentication 📚.

… and more! Check out the full 0.16 Release Notes.

New, experimental encoding/decoding APIs 🔢

In order to allow more flexibility and customization, new APIs have been exposed to allow you to encode/decode arbitrary structures without the need to inherit from the Schema class. This also allows you to customize the change tracking, encoding, and decoding at the byte level.

See Advanced Usage 📚 for more.

Breaking changes 🚨

Migrating from version 0.15 to 0.16 shouldn’t take long. Here’s an overview of the breaking changes:

• @filter() and @filterChildren() have been removed.
• client.getAvailableRooms() has been removed.
• matchMaker.getRoomById() behaviour has changed.
• Sending schema-encoded messages is now deprecated

See Upgrading to 0.16 📚 for more details.

The Future: Version 1.0 and Beyond 🚀

I’m dedicated to keeping Colyseus independent and open-source. We’re on track to version 1.0 with a roadmap shaped by community feedback, addressing key issues and outlining our vision for the framework’s future.

A huge thank you to our vibrant community, sponsors, and Colyseus Cloud users for making this journey possible!

💖 Special shoutout to Poki, Pixels.xyz, Bloxd, 0x&, and all our supporters 💖