From d38e7da158592c9c2c8df0028d8681d898d7f30e Mon Sep 17 00:00:00 2001 From: Zac Harrold Date: Wed, 8 Nov 2023 09:22:07 +1100 Subject: [PATCH] Updated incomplete/incorrect documentation --- src/lib.rs | 13 +++---------- src/rollback.rs | 12 ++++++------ src/snapshot/mod.rs | 20 ++++++++++++++++++-- src/time.rs | 29 +++++++++++++++++++++++++++++ 4 files changed, 56 insertions(+), 18 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index fb39570..5cea93c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,4 +1,6 @@ //! bevy_ggrs is a bevy plugin for the P2P rollback networking library GGRS. +//! +//! See [`GgrsPlugin`] for getting started. #![forbid(unsafe_code)] // let us try use bevy::{ @@ -26,7 +28,7 @@ pub(crate) mod time; pub mod prelude { pub use crate::{ snapshot::prelude::*, AddRollbackCommandExtension, GgrsApp, GgrsConfig, GgrsPlugin, - GgrsSchedule, PlayerInputs, ReadInputs, Rollback, Session, + GgrsSchedule, GgrsTime, PlayerInputs, ReadInputs, Rollback, Session, }; pub use ggrs::{GGRSEvent as GgrsEvent, PlayerType, SessionBuilder}; } @@ -146,15 +148,6 @@ pub struct AdvanceWorld; /// /// To add more data to the rollback management, see the methods provided by [GgrsApp]. /// -/// # Rollback -/// -/// This will provide rollback management for the following items in the Bevy ECS: -/// - [Entities](`Entity`) -/// - [Parent] and [Children] components -/// - [Time] -/// -/// To add more data to the rollback management, see the methods provided by [GgrsApp]. -/// /// # Examples /// ```rust /// # use bevy::prelude::*; diff --git a/src/rollback.rs b/src/rollback.rs index 8f9d8c2..75e52de 100644 --- a/src/rollback.rs +++ b/src/rollback.rs @@ -6,19 +6,19 @@ use bevy::{ /// This component flags an entity as being included in the rollback save/load schedule with GGRS. /// -/// You must use the `AddRollbackCommand` when spawning an entity to add this component. Alternatively, -/// you can use the `add_rollback()` extension method provided by `AddRollbackCommandExtension`. +/// You must use the [`AddRollbackCommand`] when spawning an entity to add this component. Alternatively, +/// you can use the `add_rollback()` extension method provided by [`AddRollbackCommandExtension`]. #[derive(Component, Hash, PartialEq, Eq, Clone, Copy, Debug)] pub struct Rollback(Entity); impl Rollback { - /// Creates a new `Rollback` component from an `Entity`. + /// Creates a new [`Rollback`] component from an [`Entity`]. pub(crate) fn new(entity: Entity) -> Self { Self(entity) } } -/// An `EntityCommand` which adds a `Rollback` component to an entity. +/// An [`EntityCommand`] which adds a [`Rollback`] component to an entity. pub struct AddRollbackCommand; impl EntityCommand for AddRollbackCommand { @@ -34,11 +34,11 @@ impl EntityCommand for AddRollbackCommand { } mod private { - /// Private seal to ensure `AddRollbackCommandExtension` cannot be implemented by crate consumers. + /// Private seal to ensure [`AddRollbackCommandExtension`](`super::AddRollbackCommandExtension`) cannot be implemented by crate consumers. pub trait AddRollbackCommandExtensionSeal {} } -/// Extension trait for `EntityCommands` which adds the `add_rollback()` method. +/// Extension trait for [`EntityCommands`] which adds the `add_rollback()` method. pub trait AddRollbackCommandExtension: private::AddRollbackCommandExtensionSeal { /// Adds an automatically generated `Rollback` component to this `Entity`. fn add_rollback(&mut self) -> &mut Self; diff --git a/src/snapshot/mod.rs b/src/snapshot/mod.rs index 88fc8fe..20760ea 100644 --- a/src/snapshot/mod.rs +++ b/src/snapshot/mod.rs @@ -44,9 +44,10 @@ pub type GgrsComponentSnapshots = GgrsSnapshots { /// Queue of snapshots, newest at the front, oldest at the back. + /// Separate from `frames`` to avoid padding. snapshots: VecDeque, - /// Queue of snapshots, newest at the front, oldest at the back.\ - /// Separate from snapshots to avoid padding. + /// Queue of frames, newest at the front, oldest at the back. + /// Separate from `snapshots`` to avoid padding. frames: VecDeque, /// Maximum amount of snapshots to store at any one time depth: usize, @@ -65,6 +66,7 @@ impl Default for GgrsSnapshots { } impl GgrsSnapshots { + /// Updates the capacity of this storage to the provided depth. pub fn set_depth(&mut self, depth: usize) -> &mut Self { self.depth = depth; @@ -82,10 +84,13 @@ impl GgrsSnapshots { self } + /// Get the current capacity of this snapshot storage. pub const fn depth(&self) -> usize { self.depth } + /// Push a new snapshot for the provided frame. If the frame is earlier than any + /// currently stored snapshots, those snapshots will be discarded. pub fn push(&mut self, frame: i32, snapshot: As) -> &mut Self { debug_assert_eq!( self.snapshots.len(), @@ -122,6 +127,8 @@ impl GgrsSnapshots { self } + /// Confirms a snapshot as being stable across clients. Snapshots from before this + /// point are discarded as no longer required. pub fn confirm(&mut self, confirmed_frame: i32) -> &mut Self { debug_assert_eq!( self.snapshots.len(), @@ -141,6 +148,7 @@ impl GgrsSnapshots { self } + /// Rolls back to the provided frame, discarding snapshots taken after the rollback point. pub fn rollback(&mut self, frame: i32) -> &mut Self { loop { let Some(¤t) = self.frames.front() else { @@ -159,10 +167,12 @@ impl GgrsSnapshots { self } + /// Get the current snapshot. Use `rollback(frame)` to first select a frame to rollback to. pub fn get(&self) -> &As { self.snapshots.front().unwrap() } + /// Get a particular snapshot if it exists. pub fn peek(&self, frame: i32) -> Option<&As> { let (index, _) = self .frames @@ -172,6 +182,7 @@ impl GgrsSnapshots { self.snapshots.get(index) } + /// A system which automatically confirms the [`ConfirmedFrameCount`], discarding older snapshots. pub fn discard_old_snapshots( mut snapshots: ResMut, confirmed_frame: Option>, @@ -187,6 +198,7 @@ impl GgrsSnapshots { } } +/// A storage type suitable for per-[`Entity`] snapshots, such as [`Component`] types. pub struct GgrsComponentSnapshot { snapshot: HashMap, _phantom: PhantomData, @@ -202,6 +214,7 @@ impl Default for GgrsComponentSnapshot { } impl GgrsComponentSnapshot { + /// Create a new snapshot from a list of [`Rollback`] flags and stored [`Component`] types. pub fn new(components: impl IntoIterator) -> Self { Self { snapshot: components.into_iter().collect(), @@ -209,15 +222,18 @@ impl GgrsComponentSnapshot { } } + /// Insert a single snapshot for the provided [`Rollback`]. pub fn insert(&mut self, entity: Rollback, snapshot: As) -> &mut Self { self.snapshot.insert(entity, snapshot); self } + /// Get a single snapshot for the provided [`Rollback`]. pub fn get(&self, entity: &Rollback) -> Option<&As> { self.snapshot.get(entity) } + /// Iterate over all stored snapshots. pub fn iter(&self) -> impl Iterator + '_ { self.snapshot.iter() } diff --git a/src/time.rs b/src/time.rs index 7cf896d..b5e1296 100644 --- a/src/time.rs +++ b/src/time.rs @@ -17,6 +17,32 @@ impl Default for RollbackFrameRate { } } +/// A [`Time`] type for use with GGRS. This time is guaranteed to be in-sync with +/// all peers, and reflect that exactly [`RollbackFrameCount`] frames have passed at +/// the [`RollbackFrameRate`] rate. Note that in the [`GgrsSchedule`](`crate::GgrsSchedule`), +/// this is the [default time](`Time<()>`). +/// +/// # Examples +/// ```rust +/// # use bevy::prelude::*; +/// # use bevy_ggrs::prelude::*; +/// # +/// # const FPS: usize = 60; +/// # +/// # fn read_local_inputs() {} +/// # +/// # fn start(session: Session>) { +/// # let mut app = App::new(); +/// # app.add_plugins(GgrsPlugin::>::default()); +/// # app.add_systems(ReadInputs, read_local_inputs); +/// # app.insert_resource(session); +/// fn get_in_game_time(real_time: Res>, game_time: Res>) { +/// info!("Real Time: {}", real_time.elapsed_seconds()); +/// info!("Game Time: {}", game_time.elapsed_seconds()); +/// } +/// # app.add_systems(Update, get_in_game_time); +/// # } +/// ``` #[derive(Default, Clone, Copy, Debug)] pub struct GgrsTime; @@ -25,6 +51,7 @@ pub struct GgrsTime; pub struct GgrsTimePlugin; impl GgrsTimePlugin { + /// Updates the [`Time`] resource to match [`RollbackFrameCount`] and [`RollbackFrameRate`]. pub fn update( mut time: ResMut>, framerate: Res, @@ -40,6 +67,7 @@ impl GgrsTimePlugin { time.advance_to(runtime); } + /// Overrides the [default time](`Time<()>`) with [`Time`]. pub fn replace_default_with_ggrs( mut default_time: ResMut>, ggrs_time: Res>, @@ -47,6 +75,7 @@ impl GgrsTimePlugin { *default_time = ggrs_time.as_generic(); } + /// Overrides the [default time](`Time<()>`) with [`Time`]. pub fn replace_default_with_virtual( mut default_time: ResMut>, virtual_time: Res>,