Marker-based API

[Shatur]

This PR have multiple purposes, but unfortunately they highly related, so I can't split it into multiple PRs.

Right for prediction crates like https://github.com/Bendzae/bevy_replicon_snap or https://github.com/RJ/bevy_timewarp we rely on overriding deserialization and remove functions. But this approach have 3 major drawbacks:

1. In order to customize serialization for interpolated or predicted components, user need to copy the code from the crate or use some crate-provided helpers.
2. Serialization function is is unsafe due to pointer manipulation.
3. If you want to override writing or removal only for some entities, it's costly to check if a component present on each writing.

Marker-based API solves all of the above. Now for replication user register only serialize, deserialize and newly added deserialize_in_place. These functions assigned to rules as before. So instead of ComponentFns, we now have SerdeFns. And these function now only do one thing - serialization/deserialization.

All other logic now represented by CommandFns. Unlike SerdeFns, this struct created for each component only once and automatically when user register a SerdeFns for a component. It uses default write and remove functions. To override it, user can register a marker and assign a custom functions for each component. We use markers instead of archetypes because clients do not know in advance the archetype of the entity being deserialized.

Then on receive we collect a reusable Vec<bool> for each marker (by checking if a marker is present) and based on it pick write/remove functions for each component. We pick first marker that have a registration for the current component and present on an entity (true in the Vec). Markers are sorted by priority customizable by user.

Since for deserialization we call two functions now (write and then deserialize), we can do a nice trick to remove unsafe from ser/de customization and make it even more flexible!
Since write knows the component type of deserialize, we can store a type-erased function pointers and let write "restore" the type. "restoration" is done by calling transmute, but we abstract it inside SerdeFns and check the type if debug_assertions enabled.

So serialize and deserialize now just a normal functions with a very simple signature. This also unlocks the usage of deserialize_in_place that fallback into deserialize if not overridden by user.
Similar trick is done for serialize, except read is non-overridable by user and only used to remove extra unsafety from the public API.

The mentioned read and write are still unsafe since it's possible to pass SerdeFns that was created with a different type.

And lastly, instead of using EntityWorldMut for writing and removal, we use EntityMut and Commands. Using EntityWorldMut have 2 major drawbacks:

• You can't borrow a component from EntityWorldMut for in-place deserialization and ClientMapper at the same time.
• Each insertion creates a new archetype.

With commands we can spawn new entities inside ClientMapper and it will be possible to batch insertions in the future, see: bevyengine/bevy#10154

Huge thanks to @NiseVoid for the idea!

[codecov]

Codecov Report

Attention: Patch coverage is 97.01987% with 9 lines in your changes are missing coverage. Please review.

Project coverage is 91.51%. Comparing base (70db508) to head (44f8e97).
Report is 1 commits behind head on master.

Files	Patch %	Lines
src/core/replication_fns/serde_fns.rs	86.48%	5 Missing ⚠️
src/client.rs	98.03%	1 Missing ⚠️
src/core/replication_fns/command_fns.rs	98.03%	1 Missing ⚠️
src/server.rs	83.33%	1 Missing ⚠️
src/server/replicated_archetypes.rs	85.71%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #227      +/-   ##
==========================================
+ Coverage   90.62%   91.51%   +0.88%     
==========================================
  Files          28       31       +3     
  Lines        1718     1909     +191     
==========================================
+ Hits         1557     1747     +190     
- Misses        161      162       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[UkoeHB]

This PR feels like it's working against ReplicationRules a bit. Replication rules now provide quite a bit less power since deserialize can only be used for serialization optimizations, without any additional logic.

Maybe you could somehow tie replication rule ids to which write command gets selected.

[UkoeHB]

Suggested change

	let (serde_fns, command_fns) = replication_fns.get(fns_id);
	let (command_fns, serde_fns) = replication_fns.get(fns_id);

Nit: this order seems more consistent with how they are used.

[UkoeHB]

Is there a race condition where the unwrap can fire? I.e. despawning in PreUpdate.

[Shatur]

We have test for combining insertions or updates with despawns, they pass.

But yes, if not server, but client itself despawn an entity in PreUpdate, it will panic. This is how it was before (World::entity_mut panics if there is no such entity).
I probably should replace it with expect with something like "replicated entities can be despawned only by server"?

[UkoeHB]

Sure that would work

[UkoeHB]

Suggested change

	let mut server_entity = query.get_mut(client_entity).unwrap();
	let mut client_entity = query.get_mut(client_entity).unwrap();

[Shatur]

Maybe you could somehow tie replication rule ids to which write command gets selected.

My original plan was to just separate writing and just store it in ReplicationRule. So users would just need to supply additional write function.
But for prediction and rollback, the write function should be picked dynamically on client. And it can be guessed from server archetype because prediction and rollback are client-specific things. For example, local client player could be predicted and other players - interpolated. This is why we went with a different mechanism for writing and it should be based on client entities. And we can't use archetypes here since we don't know the archetype in advance when we deserialize.

Yes, it loses a little bit of power since writing is now component-based, rather then rule-based. But I think that it's an acceptable trade-off? Feel free to suggest anything about how we can improve it. Also in the comments I answered one of your questions about your use case. Let me know if the proposed solution works for you.

[UkoeHB]

And it can be guessed from server archetype because prediction and rollback are client-specific things.

The problem is it can't be guessed until after the first tick of replication, because CommandMarkers are filtered based on the client archetype. So you always have one tick of ambiguity.

And we can't use archetypes here since we don't know the archetype in advance when we deserialize.

This isn't totally true - we know the replication rule FnsId, which represents a segment of the server's archetype.

If you want to override writing or removal only for some entities, it's costly to check if a component present on each writing. (from the PR comment)

Now you are checking all entities for all marker components.

[Shatur]

Discussed in Discord. We decided to provide set_command_fns.
There have also been some suggestions to improve the safety of public API, but these will be addressed in a separate PR.