lightyear

A networking library to make multiplayer games for the Bevy game engine

APACHE-2.0 License

Downloads
32.5K
Stars
246
Committers
25
View Code on GitHub Visit Website
Ecosystems: Bevy, Rust

Bot releases are hidden (Show)

lightyear - Release 0.17.0 Latest Release

Published by cBournhonesque 2 months ago

Release 0.17.0

Upgrade to leafwing 0.15

Leafwing's newest version brings some improvements to the API, but also fixes an important bug where you couldn't use JustPressed and JustReleased in the FixedUpdate schedule. That was problematic since networking usually requires inputs to be handled in the FixedUpdate schedule. With this fix it is now much easier to use leafwing-inputs with lightyear.

Added rollback for non-networked components

Previously, only components that were registered in the ComponentRegistry (meaning that they can be networked) could be affected by rollback. However there's plenty of cases where you might want to rollback non-networked client components: for example rolling back animations or sounds. You can now call app.add_rollback::<C>() to enable rollback for a non-networked component.

Seamless entity mapping

Previously, entity-mapping was only done on the receiver. (i.e. server spawns E1, sends it to the client who spawns E2 and maintains a mapping from E1 to E2). The mapping wasn't applied when sending messages/updates, which meant that the client had to map the entity manually from E2 to E1 if they wanted to send a message about E2. Entity mapping is now correctly applied in all directions.

Introducing authority transfer

Lightyear now has the concept of Authority: which peer (client or server) is simulating the entity and sending replication updates for it? Only one peer can have authority over an entity at any given time.

The server can freely transfer authority over an entity to other peers with the EntityCommands::transfer_authority(new_owner) command.
The Replicate bundles automatically provide you with authority over the entity; make sure to remember to update them if you're just adding Replicate on the server to re-broadcast a client-authoritative entity to other clients.

You can find an example with authority transfer here.

Important fixes

  • Guarantee that inputs get synced correctly even in low bandwidth situations. PR

What's Changed

New Contributors

Full Changelog: https://github.com/cBournhonesque/lightyear/compare/0.16.4...0.17.0

lightyear - 0.16.4

Published by cBournhonesque 3 months ago

What's Changed

Full Changelog: https://github.com/cBournhonesque/lightyear/compare/0.16.3...0.16.4

lightyear - Release 0.16.0

Published by cBournhonesque 4 months ago

Release 0.16.0

Added

Support for Steam P2P

Thanks to a PR from @msvbg , it is now possible to connect to a client acting as host-server by using Steam P2P sockets

The network_send_interval is now configurable with more precision

Previously you only had access to 2 settings:

  • client_send_interval
  • server_send_interval
    which would control how often the client or the server sent packets to the remote.

Now the send_interval is configurable:

  • per ReplicationGroup (if you want to update an entity less frequently)
  • per Channel

This gives you more flexibility to control how often you want to send messages/packets.
For example, you can send replication updates every 100ms, but send client inputs every frame if available. (this setup is particularly useful if you want to predict other player's inputs, a la RocketLeague)

@RJ added an example with remote player prediction

Added better support for handling remote player inputs. Now inputs from other players can easily be forwarded to a given player so that they can run client-prediction on all entities (the local player entity and the remote player entities)
@RJ created an awesome example spaceships showcasing how to achieve something like this.

It uses input delay, remote player prediction, physics via xpbd, etc.

Updated the InputDelay/Prediction settings [EXPERIMENTAL]

Previously you could only set a fixed amount of input delay (for example 3 ticks).
Now the input delay depends on your network conditions: the settings are identical to what is described here.

Note that this feature is still being tested and might not work if the network conditions are varying.

Miscellaneous

  • Some common bevy RunConditions are now provided, such as is_started, is_disconnected, is_host_server, etc.
  • The serialization logic now uses bincode instead of bitcode. You can provide your own serialization function instead of bincode.
  • lightyear doesn't use anyhow anymore, instead functions now return typed errors such as ReplicationError, SerializationError, etc.
  • Extra diagnostics are provided, such as PingDiagnostics to track the jitter/RTT, or RollbackDiagnostics to track the number of rollbacks

Fixed

  • lightyear can now work properly when running on wasm even if the tab is put in the background! Thanks to https://github.com/Nul-led/bevy_web_keepalive/tree/main from @Nul-led
  • Tons of bugfixes for replication edge cases
  • Input handling has been refactored to be more robust and more independent from world replication. In particular inputs can be replicated every tick even if the world replication is less frequent

Breaking changes

  • The serialization logic now uses bincode instead of bitcode
  • The Controlled component now has an extra field lifetime that specified how to despawn the entity if the controlling client is disconnected
  • Visibility has been renamed to NetworkRelevance to avoid a name conflict with bevy's Visibility
  • The DisconnectEvent now returns a DisconnectReason explaining why the client was disconnected
  • The PredictionConfig, ReplicationConfig, SharedConfig now contain additional fields

What's Changed

New Contributors

Full Changelog: https://github.com/cBournhonesque/lightyear/compare/0.15.1...0.16.0

lightyear - Release 0.15.0

Published by cBournhonesque 5 months ago

Release 0.15.0

Added

Refactored the Replicate component

Replicate used to be a Component describing all facets of how an entity should be replicated to a remote peer.
It is now a bundle composed of multiple smaller components:

  • Server to Client:
    • ReplicationTarget: which clients should receive the entity
    • SyncTarget: which clients should predict/interpolate the entity
    • VisibilityMode: do we use interest management or not
    • ControlledBy: which clients are the 'owners' of the entity?
  • Client to Server:
    • ReplicateToServer: marker component to initiate the replication to the server
  • Shared
    • Replicating: marker component indicating that the entity should be actively replicated. If this component is removed, the replication is paused.
    • ReplicateHierarchy: whether we replicate the children of this entity or not
    • ReplicationGroup: how do we group multiple entities into a single message

On the receiver side, all replicated entities will have the Replicated component.
For client->server replication, you can use Replicated::client_id() to identify the client that replicated this entity.

You can also customize the replication of a specific component via the components:

  • DisabledComponent<C>: the component is not replicated at all
  • ReplicateOnce<C>: the component's insertion/removal are replicated, but no the updates
  • OverrideTargetComponent<C>: override the replication target (the list of receiving clients) for this component

Entity ownership

It can be useful for the server to be aware of which client is 'owning' an entity.
For example, so that you can despawn all of a client's entities when the client disconnects.

You can add the ControlledBy component on an entity in the server World to specify which clients 'own' the entity.
When this entity gets replicated, the owning clients will have the Controlled marker component added.
This can be useful for the client to identify the entities it should apply client-side prediction on. (usually client-prediction is used only on the entities owned by the client)

When a client disconnects, lightyear automatically despawns the entities owned by that client. (this will be more configurable in the future).

How can you access this per-client metadata on the server? We now spawn one entity per client on the server, which can be used to hold metadata about that client. The entity can be accessed via ConnectionManager::client_entity(client_id).
For now, the only metadata has ControlledEntities component which holds a list of all the entities controlled by a client; feel free to add more if you need!

Replication logic can be updated at runtime

Before, you could only add the Replicate component once; it was not allowed to update the Replicate component after the entity was first replicated.
Now you can freely update the replication components to make changes to the replication logic:

  • modify the ReplicationTarget component to spawn an entity on new clients, or despawn the entity on some clients
  • update the VisibilityMode component to enable interest management
  • update ReplicateHierarchy to start replicating the children of an entity
  • etc.

Client and server plugins are now plugin groups

The ClientPlugin and ServerPlugin plugins have been replaced with the ClientPlugins and ServerPlugins plugin groups.
This means that you can freely override or disable any of the internal plugins that compose the plugin groups.

All internal plugins are enabled by default, but feel free to disable any that you don't need. For example you could disable the VisibilityPlugin on the server if you don't need interest management, the ClientDiagnosticsPlugin if you don't need to compute statistics on the connection, or ClientReplicationSendPlugin if you don't need to replicate entities from the client to the server.

Immediate mode visibility

lightyear used "rooms" to perform interest management. Clients and entities could join rooms, and an entity would only be replicated to a client if they shared a room.
This semi-static method is convenient in most cases, but sometimes you need a more immediate API to handle visibility.
You can now use the VisibilityManager to directly specify the visibility of a (client, entity) pair:

  • VisibilityManager::gain_visibility
  • VisibilityManager::lose_visibility

Miscellaneous

  • You can now override the function that checks if a rollback is necessary for a given component. It defaults to PartialEq::ne (rollback if the values are different) but you can override it with add_should_rollback_fn(custom_fn)
  • Added an example to showcase how to securely send a ConnectToken to a client so that it can initiate a connection.
  • Added the [zstd] feature to run zstd-compression on all packets.

Fixed

  • ChangeDetection is not triggered anymore if a component gets replicated to an entity but is equal to the existing value of the component on that entity.
  • The NetworkingState is now correctly updated when the io gets disconnected (for example via a timeout). The io tasks now get disconnected if the NetworkingState is set to disconnected (for example if the client requests disconnection).
  • Support bevy_xpbd with f64 precision
  • Improved parallelization of prediction and interpolation systems
  • Improved protocol ergonomics: you don't need to specify the component on every function anymore
app.register_component::<PlayerId>(ChannelDirection::ServerToClient)
     .add_prediction(ComponentSyncMode::Once)
     .add_interpolation(ComponentSyncMode::Once);

Breaking changes

  • Changes mentioned above for Replicate, ClientPlugin, ServerPlugin
  • Components in the ComponentRegistry must now implement PartialEq
  • Updated RoomId to be a u64
lightyear - Release 0.14.0

Published by cBournhonesque 6 months ago

Release 0.14.0

Added

Refactored the Protocol

lightyear used to require a Protocol struct which contained 2 enums MessageProtocol and ComponentProtocol that held the list of messages that could be sent over the network.

Now you can split up a protocol into multiple pieces, each piece can be registered directly on the App:

app.add_message::<Message1>(ChannelDirection::Bidirectional);
app.add_plugins(InputPlugin::<Inputs>::default());
app.register_component::<PlayerPosition>(ChannelDirection::ServerToClient)
    .add_prediction::<PlayerPosition>(ComponentSyncMode::Full)
    .add_interpolation::<PlayerPosition>(ComponentSyncMode::Full)
    .add_linear_interpolation_fn::<PlayerPosition>();
app.add_channel::<Channel1>(ChannelSettings {
    mode: ChannelMode::OrderedReliable(ReliableSettings::default()),
    ..default()
});

This approach provides more flexibility, since the Protocol can now be defined in various separate plugins; it also removes a lot of procedural macro magic that was hard to maintain.
Currently the only requirement is that the protocol registration must happen after the ClientPlugin or the ServerPlugin have been added.

Network configuration is modifiable at runtime

Previously, your network configuration would be set in stone after adding the ClientPlugin and ServerPlugin.
Now, you can freely update the configuration (by updating the ClientConfig and ServerConfig resources) at any time, and the configuration change will take effect on the next connection attempt.

I also introduce the NetworkingState state to track the status of the client or server (Connecting, Connected, Disconnected).

This means that a machine can dynamically become a client or a server depending on the configuration!
Here is an example where clients can choose at runtime whether to host the game by acting as 'host-servers', or just join the game as clients.

Automatic Resource replication

You can now easily replicate resources!
There are 2 steps:

  1. Define the resource in your protocol: app.register_resource::<R>(ChannelDirection::ServerToClient);
  2. Use commands to start/stop the replication:
  • commands.replicate_resource::<R>(target) starts the replication
  • commands.pause_replicate_resource::<R>() pauses the replication (without removing the resource)

And every changes to your resource will now be replicated!

Updated

Automatic cleanup on client disconnection

When a client gets disconnected, we now automatically cleanup all entities and resources that had been spawned on the client via replication.
In the future I have plans to make this behavior more configurable (we might want some entities to remain even when disconnected), but I chose to enable this currently for simplicity.

Separating the prediction and interpolation mode

Previously, there was only one configuration shared between Prediction and Interpolation. But there are actually situations where one would want to only enable Prediction and not Interpolation, or vice-versa.
For example, you might need to turn on Prediction on a physics component like AngularVelocity, but not turn on Interpolation since AngularVelocity doesn't have any visual impact on the component.
You can now independently specify the prediction behavior and the interpolation behavior.

Breaking changes

  • The ClientPlugin is now directly created from the ClientConfig, same for ServerPlugin
  • You now have to define a shared protocol by registering the protocol on the App after the ClientPlugin and ServerPlugin have been registered.
  • You now update the connection status via Commands:
    • commands.connect_client()
    • commands.disconnect_client()
    • commands.start_server()
    • commands.stop_server()
lightyear - Release 0.13.0

Published by cBournhonesque 7 months ago

Release 0.13.0

Added

Added Steam transport

You can now use Steam sockets as a networking Transport layer!
Note that the server can run multiple transports in parallel, so you can have cross-play between steam and non-steam users!

Running lightyear in "Host Server" mode

In the previous release, I updated all the examples to run in "listen server" mode (the server and client are running in the same machine). This was done by starting a client bevy app and a server bevy app in different threads, and sending messages between them via channels.

This works fine but has some disadvantages:

  • extra CPU overhead from running 2 bevy apps and 2 Worlds
  • complexity of having 2 different timelines
  • inputs would be slightly delayed (by 1-2 frames)

In this release, you can now run lightyear in "host server" mode. In this mode, you can create a single bevy app where the server also acts as a client. There are no packets sent between client and server because the client and server plugins are running in the same bevy World!

Updated

  • Added an object pool to re-use memory allocation of ReadBuffers used to deserialize packets

Fixed

  • Fixed a bug with interest management where an entity would get despawned when changing rooms

Breaking changes

  • Updated ClientId: instead of a u64 it is now an enum that depends on the type of Transport used by the client
  • Removed the GlobalMetadata structs; the client_id is directly accessible via connection.id()
  • Pre-Predicted entities are now spawned using the PrePredicted component instead of ShouldBePredicted
  • Updated ConnectEvent and DisconnectedEvent on the client side to also include the ClientId of the client with event.client_id()
  • Inputs are buffered on the client-side using an InputManager resource, not the ClientConnection anymore

Planned Future work

  • Add steam p2p connections
  • Enable runtime configuration of the transports: for example let a different user become the 'host' at runtime
lightyear - Release 0.12.0

Published by cBournhonesque 7 months ago

Release 0.12.0

Added

Server can support multiple Transports simultaneously

A lightyear server can now listen simultaneously on different types of Transports: WebSocket, WebTransport, UDP, local channels, etc.
It requires almost no code change: instead of providing a single TransportConfig when building the server, you can now provide a Vec<TransportConfig> and the server will be listening on each config simultaneously!

All examples have been updated to showcase this behavior: the server listens for WebTransport connections on port 5000, UDP on port 5001 and WebSocket on port 5002!

This is very exciting for two main reasons:

  • this is will allow cross-play between different connection configurations. I have plans to integrate with Steam and EOS (Epic Online Services). With this feature, players connected via Steam could also play with players connected via UDP directly to a dedicated server!
  • this enables running lightyear in "Listen Server" mode!

Running lightyear in "Listen Server" mode

"Listen Server" means that a player acts as both the server and the client. (the server will run on a separate thread on the client's machine). This could be useful for p2p games, or for some single-player game architectures where the client talks to a local server.
With the above change, it is now easy to run lightyear as a Listen Server! The server and client apps run on different threads and use local channels to communicate with 0 latency, and other clients can still connect to the host.

All examples have been updated to be able to run like this with the command: cargo run -- listen-server

Updated

  • Updated all examples to use a separate settings.ron file to specify the networking configuration. (the previous cli-based approach wasn't flexibly enough when using multiple transports for a given server)

Future work

My next priority will be to add Steam as a connection option.

lightyear - Release 0.11.0

Published by cBournhonesque 8 months ago

Release 0.11.0

Small release with mostly internal changes.

Fixed

Internal refactor by regrouping logic into bevy plugins

Moved some of the logic for the client and server into 3 new internal plugins:

  • NetworkingPlugin: contains the main receive and send systems that receive and send raw packets
  • ReplicationPlugin: contains the logic to perform World replication
  • EventsPlugin: write bevy Events whenever a networking event happens (MessageReceived, InputReceived, ConnectionReceived, etc.)

The main server and client plugins are now relatively short and just consist in importing a few other plugins.

Fixed a bug that was causing the docs to not be generated

The vendored bitcode crate could not be compiled in nightly anymore, this has been fixed.

Added

remove_replicate command

Added an EntityCommand called remove_replicate that lets you stop replicating an entity, and guarantees that any event related to that entity won't be replicated, including Despawns.
For example you can call

entity_commands.remove_replicate();
entity_commands.despawn()

on the server, and the entity's despawn won't be replicated to clients. (This could be useful if you want to play a despawn animation on the client)

Breaking changes

  • The SharedConfig struct does not have a enable_replication field anymore. This field was previously unused, so I am removing it for clarity. In the future, I will probably provide the ability to disable replication by turning the Client and Server plugins into PluginGroups
lightyear - Release 0.10.0

Published by cBournhonesque 8 months ago

Support for bevy 0.13

Lightyear is updated for bevy 0.13!

There are still a couple of issues (a leafwing-input related problem on the bullet_prespawn example, and waiting for bevy_inspector_egui to be updated for bevy 0.13) which will be fixed in a future minor release.

Hierarchy replication

Lightyear now supports replicating bevy hierarchies (i.e. replicating the Parent/Children components).
You can just set replicate.replicate_hierarchy = true on the Replicate component of the root entity of your hierarchy; all entities in the hierarchy will be replicated in a single ReplicationGroup (meaning that it is guaranteed that updates for all these entities will be received by the remote on the same tick).

Scheduling quality-of-life

Lightyear now makes use of the newly added FixedFirst, FixedPreUpdate, FixedPostUpdate schedules, which means that you can now add all your logic in the FixedUpdate schedule without worrying about ordering with other lightyear systems. In particular, the FixedUpdateSet::Main SystemSet has been removed.

Visual interpolation

Most networked data is meant to be updated in the FixedUpdate schedule so that they don't depend on framerate.
This can cause visual artifacts (jitter, etc.) because you could have multiple frames in a row without the FixedUpdate schedule running, or the FixedUpdate schedule could run multiple times in a single frame.

I've added a plugin VisualInterpolationPlugin that smoothly interpolates the value of a component between the FixedUpdate values. This adds 1 tick (FixedUpdate timestep) of visual delay, which should be negligible in most cases.
You can read more about it in the book.

Fixed

  • Interpolation is now more precise, as it uses the Time<Fixed>::overstep_fraction to compute the interpolation percentage

Migration

  • The FixedUpdateSet::Main SystemSet has been removed, you can now just add your systems to the FixedUpdate schedule
  • The MapEntities trait has been replaced with the LightyearMapEntities trait
  • The input_buffer systems have to be added to the FixedPreUpdate schedule. (this limitation is only present for native inputs, not for leafwing_inputs)
  • The LogConfig setting in SharedConfig has been removed. I will provide a custom tracing::subscriber Layer to add additional metrics/logging
lightyear - Release 0.9.0

Published by cBournhonesque 8 months ago

Added

Bandwidth management and priority scores

Lightyear now supports putting a limit on the bandwidth between a client and a server.
You can set a cap (for example 50KB/sec).

If there are too many messages to send, lightyear will use a priority with accumulation scheme to decide which messages will be sent and which will be discarded. You can set a priority score on each message, channel or entity to define its relative priority to other messages.

You can find more information in the book.
You can also check an example online

Added traits to represent the long-running connection

We already have a trait Transport that represents how to send raw byte slices over the wire, with several implementations: UdpSocket, WebTransport, WebSocket, etc. An Io is a wrapper around a dyn Transport, which lets us swap the different transport implementations effortlessly.

Similarly, I am introduce two new traits NetClient and NetServer that are an abstraction of a long-lived 'Connection': how to connect, do a handshake, get the list of connected clients, disconnect, etc.
The structs ClientConnection and ServerConnection becomes wrapped around dyn NetClient and dyn NetServer, so that we can use different 'connection' implementations. The only implementation currently is based on the netcode protocol, but this opens the door to other connection abstractions. In particular I plan to use this to add steam sockets support!

Added support for WebSockets (from @Nul-led )

There is one new implementation of the Transport trait using websockets! Those work on both native and wasm; they can be a good alternative to WebTransport on browsers that don't support WebTransport (Safari). They can be easier to work with as well as there is no need to generate a short-lived certificate.
Be mindful that websockets use TCP and can encounter head-of-line blocking.

Fixed

  • Some bugfixes related to pre-spawning entities
  • The io connection (WebTransport, UDP socket, etc.) establishes the connection when the connect function is called instead of when the lightyear Plugins are built
  • Removed the Eq bound on non-leafwing inputs, so that they can contain f32s

Migration

lightyear - Release 0.8.0

Published by cBournhonesque 9 months ago

Added

WebTransport with WASM support!

I am super excited for this: thanks to @Nul-led and @MOZGIII's help I was able the wasm webtransport working!
This means that lightyear is now available in the browser.

See here for an example running in WASM along with instructions.

PreSpawning entities

lightyear already had some support for prespawning entities on the Predicted timeline, but it was fairly awkward.
I'm introducing an easier way to do this, where the server and client can use the exact same system to spawn the entities. The only thing you need to do is add the component PreSpawnedPlayerObject on the entity, on the client and the server.

When the client receives a server entity, it will first check if that entity corresponds to one of its prespawned entities by using a hash of the Archetype and the spawn tick of the entity.

See here for an example of how to use prespawning.
You can also read more about it in the book.

lightyear - Release 0.7.0

Published by cBournhonesque 9 months ago

Added

  • Split the Client and Server monolithic resources into a bunch of smaller independent resources to remove coupling and improve parallelism. The new resources are:

    • ConnectionManager: the main resource to use to send inputs, send messages and handle replication in general.
    • Io: for sending/receiving raw packets
    • Protocol: to access the list of channels/components/messages/inputs that make up the protocol
    • Config: access the lightyear config
    • Netcode: abstraction of a network connection on top of the raw io
    • Events: a resource that handles creating Bevy events for network-related events
    • TimeManager: keeps track of the time and when we should send network packets
    • TickManager: keeps track of the internal tick (which is incremented on each FixedUpdate run)

    I am still planning on further breaking up the remaining ConnectionManager into different parts:

    • InputManager to handle inputs

    • SyncManager for handling time-syncing between client and server

    • maybe having a different resource per channel so that you can send messages to different channels in parallel

    • Added diagnostics to print the incoming/outgoing bandwidth that is being used

You can use enable the diagnostics like so:

    app.add_plugins(LogDiagnosticsPlugin {
      filter: Some(vec![
          IoDiagnosticsPlugin::BYTES_IN,
          IoDiagnosticsPlugin::BYTES_OUT,
      ]),
      ..default()
  });

I am planning on adding more diagnostics in the future.

Fixed

  • I fixed a LOT of bugs related to long-term connections after the Tick wrapped-around (after around 15 minutes); all features (input handling, replication, time-syncing) should now work correctly even for long-term sessions, up to 46 days.

  • Fixed an issue where leafwing ActionStates could not be replicated correctly from client->server in some edge-cases. Now inputs are networked correctly whether the controlled Entity is Controlled, Predicted or Pre-Predicted.

Migration

  • You will need to update your systems; the old 'monolithic' resources are still available as the SystemParams Client/ClientMut and Server/ServerMut. Otherwise you will mostly need to use the resources ClientConnectionManager and ServerConnectionManager.
lightyear - Release 0.6.1

Published by cBournhonesque 9 months ago

  • Add support for bevy_xpbd 0.3.3
  • Fixes some issues (overflow) for WrappedTime
  • Removed some info! and warn! logs in client sync
lightyear - Release 0.6.0

Published by cBournhonesque 9 months ago

Summary

This release introduces the following changes:

  • added an integration with leafwing_input_manager! This provides a more flexible way of handling inputs, and is now the recommended way. (gated behing the leafwing feature)
  • added an integration with bevy_xpbd_2d! Some components of bevy_xpbd_2d now implement Message and can be used directly in your replication protocol. (gated behind the xpbd_2d feature)
  • added the possibility to add some input delay. This lets you have a trade-off between mispredictions but responsive inputs (if the input delay is 0) or no mispredictions but delayed inputs (if the input delay is greater than the RTT)
  • added the possibility to specify how to handle mispredictions: the default behaviour is to immediately snap to the Corrected state, but it is now possible to visually interpolate between the current state and the corrected state over a few ticks
  • added the possibility to specify custom replication characterics per component for a given entity. The current options are:
    • whether to replicate this component or not
    • whether to replicate this component only once (but not send further updates)
    • whether to replicate this component only to a subset of Clients
  • examples have been updated so that they work on real connections. I have tested all examples on a connection with a remote headless server with both UDP and WebTransport!
  • Added an example showcasing most new features:
    • uses leafwing_input_manager to handle inputs
    • replicates physics via bevy_xpbd_2d
    • each client predicts every entity, and uses variable input_delay and correction_ticks to improve the handling of mispredictions
    • each client controls several entities using different keys
  • Various bug fixes

Changelog

Added

Handling inputs via leafwing_input_manager (feature leafwing)

The current input_handling is quite crude and has several limitations:

  • the user can only provide a single enum of possible actions
  • the user must handle inputs in the FixedUpdate::Main system set

This release adds special support for networking inputs via leafwing_input_manager, so that we can get all the benefits from that crate (handling chords, having multiple entities controlled by different keys).

IMPORTANT:

  • I am not sure that all features are currently working with the current ("native") input handler (for example input delay). I might remove it in the future to only support leafwing_input_manager
  • It is currently not possible to replicate inputs using a global ActionState resource. Only inputs attached to entities are supported
  • Inputs that are attached to pre-Predicted entities or Confirmed entities are currently supported, but not for Predicted entities.

Bevy xpbd 2d integration (feature xpbd_2d)

It can be hard currently to directly use external components in your replication protocol, as every component must implement such custom lightyear traits such as Message or MapEntities.
I wanted to create a demo of a physics-based networked simulation so I manually implemented some good defaults for some components of bevy_xpbd_2d, so that you can use them directly in your replication protocol.

Input delay

Lightyear now supports adding some input delay: i.e. the user presses a button on tick 10 but their character only moves on tick 15.
This lets you choose a good trade-off between having a less responsive game (more input delay) vs a very responsive game but where there is more mispredictions because the client is far in the future (low input delay).
At the extreme where the input delay is higher than the RTT, the game won't have any mispredictions as both the client and server will have access to all inputs.

See more information here: https://www.snapnet.dev/docs/core-concepts/input-delay-vs-rollback/

Prediction correction

This release adds the option to visually interpolate between the current position and the corrected position when there is a misprediction rollback. This is the technique used in RocketLeague to ensure that the game still runs smoothly even when all clients are being predicted.
The two default behaviours are:

  • InstantCorrector (no correction, we just perform rollback as usual)
  • InterpolatedCorrector (we re-use the interpolation logic for the correction; which will happen over a few ticks)

Note that the correction still has some jittery artifacts, but that's something that I will be working on in the future.

Enable custom replication logic for specific components of an Entity

It is now possible to have some replication custom logic per component of an entity.

For instance, by default only components present in the ComponentProtocol get replicated; but there could be situations where we don't want to replicate a component of an entity even it is present in the ComponentProtocol.
This can be achieved simply by calling the following methods on the Replicate component (which defines how this entity gets replicated):

  • replicate.disable_component<Component1>() to disable replication
  • replicate.enable_component<Component1>() to enable replication.
    (by default, all components are enabled)

Another example is that we might want to replicate the ActionState of an entity to all players except for the player who controls the entity (since they are the ones who are updating the ActionState with their inputs). This can be done easily by calling:

replicate.add_target::<ActionState>(NetworkTarget::AllExceptSingle(client_id));

Benchmarks

I used divan to add CPU/memory benchmarks for replicating many entities to one client, or a few entities to many clients.
I still have to think about how to best interpret the results from the benchmarks. For example I suspect that I'm doing unnecessary clones:

  • during serialization/deserialization in the packet/message layer
  • when replicating a single object to many different clients
    Ideally the benchmarks should reflect this but I haven't been able to use them for this yet.

Improved examples

I have cleaned-up the examples and tested them all in a real connection with a remote server.
The server now has the option to run in headless mode, i.e. with all rendering-related plugins disabled. Only Bevy's MinimalPlugins are enabled, so that only the simulation is running.
All examples are working with both UDP and WebTransport!

QOL improvements

  • We are now exporting the type aliases:

    type Client = Client<MyProtocol>
type Server = Server<MyProtocol>
type Replicate = Replicate<MyProtocol>

    for convenience, so that we don't have to keep mentioning the protocol as generic parameter.

  • Added the AllExceptSingle and Single NetworkTargets

  • The trait Message is now automatically implemented. You just need to implement the MapEntities and Named traits.

Fixed

  • Fixed an issue where prediction time/interpolation time were not being computed properly when the client started, which would cause the Predicted/Interpolated entities to appear frozen

  • PredictionHistory was being added even to entities that were not being Predicted. This was consuming additional CPU/memory for no reason, and has been fixed

  • Removed warn loggings being emitted by mistake for pre-Predicted entities

  • We are no longer getting a panic when we try to despawn the entities of a client who has disconnected

  • Fixed an issue where if two entities were in the same ReplicationGroup and one of them rolled back, the other would not roll back as well. Now it is guaranteed that all components of all predicted entities will rollback if there is a mispredictions on any of them.

  • Fixed some issues with rollback (including an off-by-1 error in the rollback logic)

  • Fixed some issues with replication (we now compute the bevy ChangeTick correctly)

Migration

  • Use Client instead of Client<Protocol>, Replicate instead of Replicate<Protocol>
  • UserInput has been renamed to UserAction
  • Components don't implement SyncComponent directly anymore (because this was preventing users from directly using components from external crates due to the orphan rule), instead the ComponentProtocol implements SyncMetadata<C> for each component. Use this to access the mode, interpolator, corrector of each Component
lightyear - Release 0.5.0

Published by cBournhonesque 10 months ago

Summary

This release introduces the following changes:

  • client-side replication: entities/components spawned can now be replicated from the client to the server and to other clients!
  • entity pre-spawning: it is now possible to spawn Pre-Predicted entities on the client! This means that you can spawn entities on the client timeline (i.e without any delay); as soon as you get the corresponding server entities, the pre-spawned predicted entity will update to using the server's entity as 'source of truth' for rollback
  • tested most edge-cases of client-prediction (rolling back a despawned entity, rolling back a removed component); most of them are now supported correctly!

Changelog

Added

Message broadcasting

You can know send messages from client to other clients. Previously we could only send messages between a client and the server. I added the method client.send_message_to_target which allows a client to send a message to any other client (by routing via the server)

Client-side prediction

It is now possible to have replication from the client to the server!
Note that currently I do not provide any particular helper to broadcast an entity from a client to other clients; the only way to do that is to:

  • replicate an entity from the client to the server
  • add the Replicate component to the server entity, to specify how it will be replicated to other clients

I might add some more ergonomic way to achieve this in the future (i.e specifying directly on the client how we want the entity to be replicated to other clients).

Pre-spawning Predicted entities on the Client

Currently, the only way to spawn Predicted entities (i.e. responsive and on the client's timeline) was to spawn them on the server and wait for them to be replicated. This would introduce a delay if the entity was spawned as part of a client action. We would have to wait for:

  1. the client's action to be sent to the server
  2. then for the server to spawn an entity
  3. and then for that entity to be replicated to the client
    to be able to spawn a Predicted entity on the client, which is at a minimum a full RTT of delay.

Instead, we can now spawn a pre-predicted entity on the client. Here is an example:

  1. a client spawns a PrePredicted entity C1 by adding the component ShouldBePredicted { client_entity }
  2. the client replicates that entity C1 to the server, which creates an entity S1
  3. the server replicates the entity S1 back to the client, which creates a Confirmed entity C2 and re-uses the existing entity C1 as its Predicted entity

Correctly handling replication edge-cases

There are a lot of potential edge-cases with client-prediction, especially with the addition of spawning Pre-Predicted entities.

I have listed most of them in that link; for instance:

  • despawning a predicted entity, but the server doesn't despawn -> need to rollback the Predicted despawn
  • despawning a predicted entity, and the server accepts the despawn -> we want the server's replicated entity to be immediately despawned
  • despawning the server entity -> need to replicate the despawn to Predicted entities
  • ...
    etc.

I have tested most them; almost all situations are supported correctly!
The only one that has some caveats is rolling back a predicted despawn; this only happens if we receive a server update for that entity after the despawn.

Client replication example

Added a new example client_replication that show-cases the newly-added features:

  • pressing M will send a message from a client to other clients
  • performs client-authoritative replication by replicating the user's cursor to other clients
  • pressing Space will spawn a Pre-Predicted entity. The entity is spawned immediately, and then becomes the Predicted version of a Confirmed entity once it gets replicated
  • pressing Delete will delete the Predicted entity. You can use this to confirm the behavior of rollback in various edge-cases.

Updated

  • Renamed the send_message methods from buffer_send ->send_message and send_to_target -> send_message_to_target for clarity.

Migration guide 0.4.0 -> 0.5.0

  • server.send_to_target has been renamed to server.send_message_to_target
  • server.buffer_send has been renamed to server.send_message
  • client.buffer_send has been renamed to client.send_message
  • Adding Replicate on the server to re-replicate client entities to other clients must be done in the newly added MainSet::ClientReplication SystemSet
  • Correctly despawning Predicted entities requires to use EntityCommands::prediction_despawn instead of EntityCommands::despawn
lightyear - Release 0.4.0

Published by cBournhonesque 10 months ago

Summary

This release:

  • enables the replication of Messages and Components that contain Entities
  • greatly improves the stability of client-prediction and snapshot-interpolation
  • adds a more involved example showing how to use custom interpolation logic, and components that contain Entities

Changelog

Added

  • Added an example ReplicationGroups that showcases:
    • the concept of ReplicationGroups: where multiple entities are guaranteed to be replicated in a single message, so will always be in sync with each other
    • how replicating components that refer to other entities works (via the MapEntities trait)
    • how to execute a complex custom snapshot interpolation logic: the interpolation is not a simple linear interpolation. The interpolated will stay on the "path" of the snake, and never do any diagonal movement
    • showcases how prediction/interpolation performs with bad connections; the example default settings are with 400ms RTT, 40ms jitter and 10% packet loss

Updated

  • Handle entity mappings more rigorourously now! By Entity Mapping I mean Messages or Components that contain references to other entities, such as HasParent(Entity). The entity in the message is from the server's World, and it needs to be mapped to the client's World.

    • refactored the MapEntities trait to be more flexible
    • introduced also entity mapping between the Confirmed entities and the Predicted/Interpolated entities (i.e. a component with HasParent(Entity) on the Confirmed entity will be synced with the correct mapping on the Predicted/Interpolated entities)
    • A Replication Group will be guaranteed to be replicated with an entity order that respects any dependencies between the entities: for example if you have two entities A and B and B depends on A (maybe because it contains a component HasParent(A), B will be replicated after A has finished replicating.

  • Updated the Input handling logic to get rid of some jitter around client prediction:

    • clients now must send inputs every tick (even if there are no inputs), so that the server can distinguish between "no input" and "lost input"
    • For a lost input, the server uses the last received input as a fallback estimate
    • this helps reduce prediction errors by a huge amount; client prediction should be more robust now!

  • Refactored some of the interpolation logic:

    • a Component only needs to implement Add and Mul if it uses LinearInterpolation, not if it uses a custom interpolation function
    • added an option to give the user complete freedom to implement their interpolation logic

Fixed

  • Fixed an issue that was causing some instability during client-prediction: the client inputs were not buffered for long enough, so the input buffer was sometimes empty during rollback
  • Fixed some issues that were causing instability/jitter during snapshot-interpolation: the interpolation start and end ticks were sometimes not computed correctly, which would cause the interpolation to 'jitter'. Snapshot interpolation should be much smoother now
  • Fixed an issue where the ping buffer was sometimes too small and would panic, especially if the ping send_interval was short

Migration guide

  • Clients must now send inputs every tick, even if the user isn't doing any action. Practically, this means that you need to add a None variant in your Input enum, like so:
pub enum Inputs {
    Direction(Direction),
    Delete,
    Spawn,
    // *new*: inputs must be sent every tick, even if there is no action
    NoAction,
}
  • The MapEntities trait has been modified; all old implementors must be updated to match the new trait:
/// Trait that Messages or Components must implement to be able to map entities
pub trait MapEntities<'a> {
    /// Map the entities inside the message or component from the remote World to the local World
    fn map_entities(&mut self, entity_mapper: Box<dyn EntityMapper + 'a>);

    /// Get all the entities that are present in that message or component
    fn entities(&self) -> EntityHashSet<Entity>;
}
lightyear - Release 0.3.0

Published by cBournhonesque 10 months ago

Release 0.3.0

Added

  • Added interest management via the concept of Room, to be able to replicate only a subset entities to a certain client to save bandwidth and prevent cheating. See more information here
  • Updated the replication manager to be much more robust. The new manager:
    • makes sure that an entity or a group of entities (via ReplicationGroup) are replicated with a consistent state. See more information here
    • inspired by what bevy_replicon is doing
    • this fixes some edge cases with prediction/interpolation; in particular when send_interval is small compared with jitter
  • Added a new UnreliableSenderWithAck channel where senders can get notified when a given message has been ACK-ed
  • Some common bevy structs (Transform, Color, Visibility) now implement the Message trait and can be used for replication

Updated

  • the ComponentProtocol now derives Debug directly (which shows the type of the replicated Component, but not the value)

Fixed

  • the existing world state is now replicated properly to newly connected clients (whether they use Room or not for replication)
Package Rankings
Top 49.38% on Crates.io
Badges
Extracted from project README
crates.io docs.rs codecov
Related Projects
bevy_impulse

Reactive programming and workflow execution for bevy

29 Aug 2023 0
bevy_talks

A Bevy plugin to write dialogues for your characters, together with player choices.

23 Jan 2023 53
beet

A modular behavior library for the Bevy Engine.

03 Mar 2024 28
aeronet

A light-as-air client/server networking library for Rust

02 Sep 2023 19
bevy_replicon

ECS-focused high-level networking crate for the Bevy game engine.

24 Mar 2023 232
bevy_pkv

Cross-platform (including wasm) persistent key value store plugin for rust games/apps

15 Mar 2022 133
matchbox

Painless peer-to-peer WebRTC networking for rust wasm (and native!)

01 Sep 2021 877
bevy_quinnet

A Client/Server game networking plugin using QUIC, for the Bevy game engine.

17 Oct 2022 198
bevy_hanabi

🎆 Hanabi — a GPU particle system plugin for the Bevy game engine.

27 Jan 2022 801
bevy_tweening

Tweening animation plugin for the Bevy game engine.

27 Jan 2022 400
bevy_defer

A simple asynchronous runtime for executing async coroutines in the bevy engine.

13 Mar 2024 44
bevy_octopus

A Low leveling ECS driven network plugin for Bevy.

19 Apr 2024 7
bevy_prototype_networking_laminar

This is a prototype of a networking crate for bevy. This create provides a low-level networking p...

21 Aug 2020 30
bevy_eventlistener

Event listening, bubbling, and callbacks

05 May 2023 174
bevy_mod_picking

Picking and pointer events for Bevy.

31 Aug 2020 771