Document components and resources needed for rollback

[Jondolf]

For things like networking, it can be important to enable rollback for certain physics components and resources to avoid mispredictions. However, it can be unclear which components should be rolled back without good knowledge of engine internals.

Avian should have documentation listing stateful components and resources that can affect simulation behavior and are important for rollback.

List of components and resources

Below, I've listed the ones that come to mind.

Components:

• Position
• Rotation
• LinearVelocity
• AngularVelocity
• ExternalForce (if used, and only if persistent)
• ExternalTorque (if used, and only if persistent)
• ExternalImpulse (if used, and only if persistent)
• ExternalAngularImpulse (if used, and only if persistent)
• Sleeping (if sleeping is enabled)
• TimeSleeping (if sleeping is enabled)
• CollidingEntities (if used)

Resources:

• Collisions (only if solver warm starting is enabled)

You may also need to roll back Transform and GlobalTransform, as changes to them can affect Position and Rotation either directly or through hierarchies.

If you notice components or resources missing that are important for rollback, let me know :)

[janhohenheim]

Also CollidingEntities per Discord

[cscorley]

I would suggest also adding Time<Physics> and Time<Substeps> if you are pausing the physics via the pausing mechanism on the former.

If your game has a rollback to a frame that starts a pause, then the delta can still have an effect -- specifically Time<Substeps> may get a delta time from Time<Physics> before the latter is zeroed out on the next run of the schedule. (It may also be worth having Time<Substeps> skipped & zeroed out in a similar manner as Time<Physics> when it is paused.)

[cscorley]

Having Sleeping enabled will need to be handled with care -- if the simulation is not large, I'd recommend disabling it.

On a rollback that triggers a component's Changed state (e.g. with bevy_ggrs), even if the object is Sleeping in both the most recent frame and the frame we're rolling back to, the change detection for Position, Rotation, etc, will be triggered and Sleeping removed on that rolled back frame by Avian. This means one client can have something marked Sleeping and the other will not. Depending on the situation, this can cause a desync e.g. the velocity could be changed (slightly) in the world on one and not the other because TimeSleeping is also set to zero, and you'll need to wait several frames (likely) until mark_sleeping_bodies runs again.

If insistent on using Sleeping, when a rollback occurs, take care to rollback TimeSleeping again manually and re-execute mark_sleeping_bodies after wake_on_changed has ran. This may be doable with a plugin.

[janhohenheim]

@cscorley huh, I didn't think about it before, but that definitely makes sense. Good catch!