Skip to content

Release 0.21.0

Choose a tag to compare

View all tags
@cBournhonesque cBournhonesque released this 04 Jul 01:43
· 282 commits to main since this release
0.21.0
86bf851
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Lightyear 0.21.0

Multiple crates

This is a massive release that is basically a full rewrite of the crate. In particular, the crate has been split into multiple subcrates, for the following reasons:

  • faster compile times
  • more modularity by splitting up small pieces into different crates
  • encourages a better separation of concerns

This was definitely challenging but I think it's for the better.
Similarly to bevy, you will have lightyear_* subcrates and a main lightyear crate which imports every subcrate.
It is possible to use the subcrates directly if you want, as the main crate just imports the relevant plugins from the subcrates.

From Resources to Entities

Instead of managing the networking behaviour via a set of Resources (ClientConfig, ClientConnectionManager, etc.), we now switch to a model where you have one entity per network connection between the local peer and the remote peer. (this approach was pioneered by
aeronet)

  • at the transport layer (how to send/remove bytes):

    • you can add one of the IO components (UdpIO, WebTransportIO, etc.) to specify how you will send or receive bytes from the remote peer
    • the IO-agnostic Link component is used to abstract away from the actual io
    • you can access metadata about the io link using the LocalAddr and PeerAddr components
    • the state of the link can be accessed via various marker components (Linked, Unlinked)
    • the Transport component can be added to specify various channels that provide different reliability and ordering guarantees
    • the MessageSender<M> and MessageReceiver<M> components can be added to add the ability to send and receive structs instead of raw bytes. The MessageManager is responsible for handling the serialization and the entity mapping

  • at the connection layer (how to establish a persistent connection on top of the raw io):

    • you can add the Client or Server component to specify the role of the entity. In particular, the Server component will listen for incoming connections and spawn new ClientOf entities for each connected client
    • the state of the connection can be accessed via various marker components (Connected, Disconnected, Started, Stopped)
    • the NetcodeClient or NetcodeServer components can be added to use netcode as the layer providing authentication + persistent IDs on top of the raw IO

  • at the syncing layer (how to make sure that the local and remote peers are in sync)

    • there is now a new Timeline component that is used to represent the various networking timelines:
      • the LocalTimeline simply increments the tick whenever the FixedUpdate schedule runs
      • the RemoteTimeline is the local peer's best estimate of the remote peer's timeline; computed from the received packets. This is used to make sure that all the timelines remain in sync with the remote peer
      • the InterpolationTimeline is in the past compared to the Remote, and is used to define how to interpolate between the received remote packets
      • the InputTimeline is in the future to the Remote, and is used to define when ticks should be buffered

  • at the input layer (how do the clients send inputs to the server)

    • the ActionState component defines the current state of the inputs at the current tick. It is guaranteed to be the same between client and server for a given tick
    • the InputBuffer component can be used to access the received inputs that were locally buffered
    • lightyear now has a shared generic inputs plugin that makes sure input-handling is correct with rollback, input_delay, rebroadcasting to other clients, etc. There are 3 implementations: native, leafwing, and bevy-enhanced-input

  • at the replication layer (how to replicate the state of the World to the remote)

    • you can add the ReplicationSender and ReplicationReceiver components to specify if you want the peer to be part of replication
    • the PredictionManager and InterpolationManager mark a link entity as having prediction/interpolation enabled

The bevy ECS provides a lot of flexibility: you can add or remove these components from a subset of the peers to change their networking configuration. Usually if you make changes, they will be applied on the next connection attempt.
This change was mostly made possibly with the recent ECS innovations: observers and relationships.

Moving away from Client-Server

Lightyear was strongly tied to the concepts of client and server. You had to use some specialized client or server resources (ClientManager and ServerManager) and those would have very similar code that varied in subtle ways. For example the replication code was essentially duplicated between them, apart from some server-specific code.

With the new component-based approach, the code has become fairly agnostic to the roles of client and servers.
For example there is now a unique replication system that works on any entity that has a ReplicationSender component, so each local peer can replicate to a remote peer in the exact same way!

I think this is super exciting as this opens the door to handling P2P topology with code that is very similar to client-server topologies!

Total parity?

This refactor of the crate doesn't achieve total parity with the previous version. Some of the functionality that hasn't been ported is:

  • Resource replication: I believe bevy is moving towards resource-as-entities, where resources are simply components stored on an entity. I will just be waiting for this to be merged before re-adding resource replication
  • input broadcasting: we previously had convenience functions so that a client could send a message to another client (the message would be sent to the server, who would broadcast it to the correct client). This hasn't been re-added yet
  • authority: the handling of authority is still somewhat in flux, I have made steps towards it but it hasn't been properly tested, and the distributed_authority example is still outdated.

Extras

  • Instead of maintaining my own steam, webtransport, websocket io layers, I now defer to the excellent aeronet crate!

  • Special thanks to @hukasu for helping me improve the compile time of lightyear!

Next steps

With the increased flexibility and modularity, I would like to tackle:

  • handling networking modes where only inputs are replicated, such as deterministic lockstep! I believe this should now be very much within reach, as it mostly involves adding a LockstepTimeline to define how the local and remote peers stay in sync
  • handling P2P topologies

What's Changed

New Contributors

Full Changelog: 0.20.2...0.21.0

Contributors

hukasu, cBournhonesque, and 4 other contributors
Assets 2
Loading