Crate crystalorb[][src]

Expand description
WARNING: This crate currently depends on nightly rust unstable and incomplete features.


Network-agnostic, high-level game networking library
for client-side prediction and server reconciliation. ci cd Coverage

Quick start

You may copy the standalone example to use as a starting template, and build off from there. You may also want to check out crystalorb-mock-network and crystalorb-bevy-networking-turbulence, either to use directly in your projects, or as examples for you to integrate your own choice of networking layer.

If you prefer a more visual and interactive example, there is the demo shown above that uses the Rapier physics engine. Feel free to use the demo’s source code as a starting template for your next project.

For more information about how to implement the required traits, refer to the docs.


Game networking is hard, because we usually want to give the illusion that the physics simulation is responsive, fair, and consistent between multiple game clients despite having significant network latency between the clients and the server. There are many different ways to solve the game networking problem. CrystalOrb tries implementing one of such ways.

CrystalOrb is a young networking library that implements:

  • Client-side prediction. Clients immediately apply their local input to their simulation before waiting for the server, so that the player’s inputs feel responsive.
  • Server reconciliation. Server runs a delayed, authoritative version of the simulation, and periodically sends authoritative snapshots to each client. Since the server’s snapshots represent an earlier simulation frame, each client fast-forwards the snapshot they receive until it matches the same timestamp as what’s being shown on screen. Once the timestamps match, clients smoothly blend their states to the snapshot states.
  • Display state interpolation. The simulation can run at a different time-step from the render framerate, and the client will automatically interpolate between the two simulation frames to get the render display state.

CrystalOrb does not (yet) implement “lag compensation” (depending on your definition of “lag compensation”), because CrystalOrb clients currently simulate all entities (including other players) in the present anyway. Some netcode clients would rather simulate entities in the past except for the local player. There are pros and cons to both methods:

  • By simulating everything in the present, collision timings will be consistent across all clients provided that no player input significantly changes the course of the simulation. This might be beneficial for physics-heavy games like… Rocket League? This is what CrystalOrb does. If you have two clients side-by-side, and you issue a “jump” command for the player using the left client, then the right client will see a jump after a small delay, but both clients will see the player land at the exact same time.

  • By simulating most remote entities in the past, remote entities require little correction in the client, so other players’ movement will look more natural in response to their player inputs. If you have two clients side-by-side, and issue a “jump” command for the player using the left client, then the right client will not see any jerk in the movement, but the jump and the landing will occur slightly later after the left client.

Caveat: You need to bring your own physics engine and “mid-level” networking layer. CrystalOrb is only a “sequencer” of some sort, a library that encapsulates the high-level algorithm for synchronizing multiplayer physics games. CrystalOrb is physics-engine agnostic and networking agnostic (as long as you can implement the requested traits).

Is CrystalOrb any good?

Doubt it. This is my first time doing game networking, so expect it to be all glitter and no actual gold. For more information on game networking, you might have better luck checking out the following:

(Yes, those were where I absorbed most of my small game-networking knowledge from. Yes, their designs are probably much better than CrystalOrb)

CrystalOrb is a client-server rollback library, and there are other kinds of rollback/networking libraries out there you should check out! Here are some other rollback libraries by other authors in the rust community you might be interested in:

Your project’s not listed? Feel free to make a PR or submit an issue, and I’d be happy to promote it.

More examples

  • Demo by @ErnWong is hard-coded for only two clients (source).
  • orbgame by @vilcans is a Bevy demo that accepts more than two clients.
  • Dango Tribute by @ErnWong is a Bevy interactive experience with multiplayer blob physics. CrystalOrb was the networking code that was eventually extracted out from that project.

Your project’s not listed? Feel free to make a PR or submit an issue, and I’d be happy to promote it.

Unstable Rust Features

CrystalOrb currently uses the following unstable features:



This module houses the structures that are specific to the management of a CrystalOrb game client.

The clocksync module is responsible for managing the difference between the clocks on the local and remote machine (aka client and server clocks), and for the client to estimate the server’s local time.

Traits and structures relating to and for managing commands. Commands are messages sent from outside the physics simulation to alter how the physics simulation runs. For example, causing a rigid body for a player to jump requires a jump command, and causing a player to spawn requires a spawn command.

Home for the Stepper trait, and home to the structures responsible for keeping these steppers up to date with the current local clock.

The set of traits that need to be implemented to tell CrystalOrb how to use your external networking library to send and receive messages.

This module houses the structures that are specific to the management of a CrystalOrb game server.

Types for identifying/indexing and comparing the time between simulation frames.

Contains traits for CrystalOrb to interface with your game physics world, along with internal structures that interfaces directly with your world.


Configuration parameters that tweak how CrystalOrb works.


Represent how to calculate the current client display state based on the simulated undershot and overshot frames (since the two frames closest to the current time may not exactly line up with the current time).