bevy_ggrs

Because Bevy Entity IDs are not stable across despawn/respawn cycles, bevy_ggrs uses specific components to maintain logical identity during rollbacks:

• Rollback: A marker component. Add this to any entity that must be saved and rolled back. Adding this automatically assigns a RollbackId.
• RollbackId: An immutable component representing the Entity ID at the time Rollback was first added. This is the stable key used in GgrsComponentSnapshot.
• RollbackOrdered: A resource maintaining a stable, insertion-ordered list of all RollbackIds, used for deterministic checksums.

Reconciliation Process: During LoadWorld, the EntitySnapshotPlugin compares the live entity set against the snapshot:

• Exists in both: Maps current → snapshot IDs.
• In snapshot only: Spawns a new entity with the same Rollback + RollbackId and maps new_id → old_id.
• In world only: Despawns the entity.

Mappings are stored in RollbackEntityMap and used by LoadWorldSystems::Mapping to fix up stale Entity references in components or resources.

The GgrsPlugin manages the rollback loop by running the run_ggrs_schedules system (typically in PreUpdate). This system accumulates real-world delta time and polls the Session for remote input. When enough time has accumulated, it processes GgrsRequest objects by triggering specific Bevy schedules:

Normal Frame: One SaveGameState followed by one AdvanceFrame. Rollback Frame: One LoadGameState to rewind, followed by a sequence of AdvanceFrame + SaveGameState pairs to re-simulate up to the current frame.

The execution order of schedules within a single Bevy frame is critical for correct rollback behavior:

1. PreUpdate: Runs run_ggrs_schedules.
2. SaveWorld: Snapshots the current state.
   • SaveWorldSystems::Checksum: Computes ChecksumParts.
   • SaveWorldSystems::Snapshot: Writes to snapshot storage.
3. LoadWorld: Restores the world to a rollback frame (if needed).
   • LoadWorldSystems::Entity: Reconciles entity sets and builds RollbackEntityMap.
   • LoadWorldSystems::EntityFlush.
   • LoadWorldSystems::Data: Restores component/resource values.
   • LoadWorldSystems::DataFlush.
   • LoadWorldSystems::Mapping: Remaps stale Entity references via MapEntities.
4. AdvanceWorld: Runs game logic.
   • AdvanceWorldSystems::First: Pre-frame setup (e.g., GgrsTime update).
   • [ApplyDeferred]
   • AdvanceWorldSystems::Main: Runs your custom GgrsSchedule (game logic).
   • [ApplyDeferred]
   • AdvanceWorldSystems::Last: Post-frame cleanup (e.g., restoring Time<()>)

To implement rollback networking with bevy_ggrs, follow these core steps:

1. Define your configuration: Create a type alias for GgrsConfig, specifying your input type (e.g., u8).
2. Initialize the Plugin: Add GgrsPlugin::<GgrsConfig>::default() to your Bevy App.
3. Set Frame Rate: Insert the RollbackFrameRate resource to define how many frames per second the rollback logic should run at.
4. Register Components: Use .rollback_component_with_clone::<T>() to register components that need to be snapshotted for rollbacks. These components must implement Clone.
5. Handle Inputs: Add systems to the ReadInputs schedule to provide local player inputs each frame.
6. Implement Game Logic: Place your deterministic game logic systems into the GgrsSchedule instead of the standard Update schedule.
7. Initialize Session: Insert a Session resource (e.g., Session::SyncTest) to start the networking session.

use bevy::prelude::*;
use bevy_ggrs::prelude::*;

type GgrsConfig = bevy_ggrs::GgrsConfig<u8>; // replace u8 with your input type

App::new()
    .add_plugins(GgrsPlugin::<GgrsConfig>::default())
    .insert_resource(RollbackFrameRate(60))
    // register components/resources for snapshotting
    .rollback_component_with_clone::<Transform>()
    // provide inputs each frame
    .add_systems(ReadInputs, read_local_inputs)
    // your game logic — must be deterministic!
    .add_systems(GgrsSchedule, move_players)
    .insert_resource(Session::SyncTest(session))
    .run();

// #[require(Rollback)] ensures Rollback is always added with Player —
// no need to include it manually in every spawn call.
#[derive(Component)]
#[require(Rollback)]
struct Player;

fn spawn_player(mut commands: Commands) {
    commands.spawn((Transform::default(), Player));
}