More ergonomics

Author: wallstop

CHANGELOG.md

@@ -16,6 +16,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `GameStateCell::load_or_err()` method for strict state loading with proper error handling
+- `InvalidFrameReason::MissingState` variant for clearer error messages when loading missing states
+- `SessionBuilder::with_lan_defaults()` preset for low-latency LAN play
+- `SessionBuilder::with_internet_defaults()` preset for typical online play
+- `SessionBuilder::with_high_latency_defaults()` preset for mobile/unstable connections
 - `Frame` ergonomic methods for safe arithmetic and conversion:
   - `as_usize()`, `try_as_usize()` — convert to usize with Option/Result
   - `buffer_index(size)`, `try_buffer_index(size)` — ring buffer index calculation

examples/configuration.rs

@@ -77,10 +77,28 @@ fn basic_configuration() {
 }
 
 /// Using built-in presets for common network conditions
+///
+/// NOTE: For even simpler configuration, use the new convenience presets:
+/// - `with_lan_defaults()` - LAN/local play with minimal latency
+/// - `with_internet_defaults()` - Typical online play (2-frame input delay)
+/// - `with_high_latency_defaults()` - Mobile/unstable connections (4-frame input delay)
+///
+/// Example:
+/// ```ignore
+/// SessionBuilder::<GameConfig>::new()
+///     .with_num_players(2).unwrap()
+///     .with_lan_defaults()
+///     .add_local_player(0).unwrap()
+///     .add_remote_player(1, addr).unwrap()
+///     .start_p2p_session(socket)
+/// ```
 fn network_presets() {
     println!("--- Network Presets ---");
+    println!("TIP: Use with_lan_defaults(), with_internet_defaults(), or");
+    println!("     with_high_latency_defaults() for quick configuration!\n");
 
     // LAN/Local play - fast connections, minimal latency
+    // Equivalent to: .with_lan_defaults()
     let lan_builder = SessionBuilder::<GameConfig>::new()
         .with_num_players(2)
         .unwrap()
@@ -99,6 +117,7 @@ fn network_presets() {
     println!("  Builder: {:?}\n", lan_builder);
 
     // Regional internet (20-80ms RTT)
+    // Equivalent to: .with_internet_defaults().with_max_prediction_window(8)
     let regional_builder = SessionBuilder::<GameConfig>::new()
         .with_num_players(2)
         .unwrap()
@@ -116,6 +135,7 @@ fn network_presets() {
     println!("  Builder: {:?}\n", regional_builder);
 
     // High-latency networks (80-200ms RTT)
+    // Similar to: .with_high_latency_defaults().with_max_prediction_window(12)
     let high_latency_builder = SessionBuilder::<GameConfig>::new()
         .with_num_players(2)
         .unwrap()

src/error.rs

@@ -154,6 +154,16 @@ pub enum InvalidFrameReason {
     },
     /// Frame is NULL or negative (general validation).
     NullOrNegative,
+    /// No saved state exists for this frame.
+    ///
+    /// Returned when attempting to load a game state that was never saved.
+    /// This typically indicates a programming error — [`LoadGameState`] requests
+    /// should only be issued for frames that were previously saved via
+    /// [`SaveGameState`].
+    ///
+    /// [`LoadGameState`]: crate::FortressRequest::LoadGameState
+    /// [`SaveGameState`]: crate::FortressRequest::SaveGameState
+    MissingState,
     /// Custom reason (fallback for API compatibility).
     Custom(&'static str),
 }
@@ -192,6 +202,7 @@ impl Display for InvalidFrameReason {
                 )
             },
             Self::NullOrNegative => write!(f, "frame is NULL or negative"),
+            Self::MissingState => write!(f, "no saved state exists for this frame"),
             Self::Custom(s) => write!(f, "{}", s),
         }
     }
@@ -1336,6 +1347,16 @@ mod tests {
         assert!(display.contains("50"));
     }
 
+    #[test]
+    fn invalid_frame_reason_missing_state_display() {
+        let reason = InvalidFrameReason::MissingState;
+        let display = format!("{reason}");
+        assert!(
+            display.contains("saved state"),
+            "Expected 'saved state' in: {display}"
+        );
+    }
+
     #[test]
     fn test_internal_error_kind_index_out_of_bounds() {
         let kind = InternalErrorKind::IndexOutOfBounds(IndexOutOfBounds {

src/sessions/builder.rs

@@ -765,6 +765,141 @@ impl<T: Config> SessionBuilder<T> {
         self
     }
 
+    // =========================================================================
+    // Session Presets
+    // =========================================================================
+
+    /// Applies LAN-optimized defaults for low-latency local network play.
+    ///
+    /// This preset configures the session for minimal latency scenarios typical
+    /// of local area networks, where RTT is typically <10ms and packet loss is rare.
+    ///
+    /// # Configuration Applied
+    ///
+    /// - **Sync**: Fast handshake with fewer required roundtrips ([`SyncConfig::lan()`])
+    /// - **Protocol**: Competitive settings with quick detection ([`ProtocolConfig::competitive()`])
+    /// - **Time Sync**: Small window for responsive sync ([`TimeSyncConfig::lan()`])
+    /// - **Input Delay**: 0 frames (can be adjusted with [`with_input_delay()`])
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use fortress_rollback::{SessionBuilder, Config};
+    ///
+    /// # struct MyConfig;
+    /// # impl Config for MyConfig {
+    /// #     type Input = u8;
+    /// #     type State = ();
+    /// #     type Address = std::net::SocketAddr;
+    /// # }
+    /// let builder = SessionBuilder::<MyConfig>::new()
+    ///     .with_lan_defaults();
+    /// ```
+    ///
+    /// [`SyncConfig::lan()`]: crate::SyncConfig::lan
+    /// [`ProtocolConfig::competitive()`]: crate::ProtocolConfig::competitive
+    /// [`TimeSyncConfig::lan()`]: crate::TimeSyncConfig::lan
+    /// [`with_input_delay()`]: Self::with_input_delay
+    pub fn with_lan_defaults(self) -> Self {
+        self.with_sync_config(SyncConfig::lan())
+            .with_protocol_config(ProtocolConfig::competitive())
+            .with_time_sync_config(TimeSyncConfig::lan())
+    }
+
+    /// Applies Internet-optimized defaults for typical online play.
+    ///
+    /// This preset configures the session for typical internet connections with
+    /// moderate latency (30-100ms RTT) and occasional packet loss (<5%).
+    ///
+    /// # Configuration Applied
+    ///
+    /// - **Sync**: Default handshake settings ([`SyncConfig::default()`])
+    /// - **Protocol**: Default network timing ([`ProtocolConfig::default()`])
+    /// - **Time Sync**: Default averaging window ([`TimeSyncConfig::default()`])
+    /// - **Input Delay**: 2 frames (recommended for hiding network jitter)
+    ///
+    /// # Errors
+    ///
+    /// Returns [`FortressError::InvalidRequest`] if the input delay cannot be set
+    /// (e.g., if the input queue is too small).
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use fortress_rollback::{SessionBuilder, Config, FortressError};
+    ///
+    /// # struct MyConfig;
+    /// # impl Config for MyConfig {
+    /// #     type Input = u8;
+    /// #     type State = ();
+    /// #     type Address = std::net::SocketAddr;
+    /// # }
+    /// let builder = SessionBuilder::<MyConfig>::new()
+    ///     .with_internet_defaults()?;
+    /// # Ok::<(), FortressError>(())
+    /// ```
+    ///
+    /// [`SyncConfig::default()`]: crate::SyncConfig::default
+    /// [`ProtocolConfig::default()`]: crate::ProtocolConfig::default
+    /// [`TimeSyncConfig::default()`]: crate::TimeSyncConfig::default
+    /// [`FortressError::InvalidRequest`]: crate::FortressError::InvalidRequest
+    pub fn with_internet_defaults(self) -> Result<Self, FortressError> {
+        self.with_sync_config(SyncConfig::default())
+            .with_protocol_config(ProtocolConfig::default())
+            .with_time_sync_config(TimeSyncConfig::default())
+            .with_input_delay(2)
+    }
+
+    /// Applies mobile/high-latency defaults for unstable connections.
+    ///
+    /// This preset configures the session for challenging network conditions
+    /// typical of mobile/cellular networks or high-latency connections:
+    /// - High RTT (100-300ms)
+    /// - Variable latency (high jitter)
+    /// - Intermittent packet loss (5-20%)
+    /// - Connection handoffs (WiFi/cellular switches)
+    ///
+    /// # Configuration Applied
+    ///
+    /// - **Sync**: Robust handshake with more retries ([`SyncConfig::mobile()`])
+    /// - **Protocol**: Tolerant settings with larger buffers ([`ProtocolConfig::mobile()`])
+    /// - **Time Sync**: Large window for stable sync ([`TimeSyncConfig::mobile()`])
+    /// - **Input Queue**: Larger queue for longer history ([`InputQueueConfig::high_latency()`])
+    /// - **Input Delay**: 4 frames (helps absorb jitter spikes)
+    ///
+    /// # Errors
+    ///
+    /// Returns [`FortressError::InvalidRequest`] if the input delay cannot be set.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use fortress_rollback::{SessionBuilder, Config, FortressError};
+    ///
+    /// # struct MyConfig;
+    /// # impl Config for MyConfig {
+    /// #     type Input = u8;
+    /// #     type State = ();
+    /// #     type Address = std::net::SocketAddr;
+    /// # }
+    /// let builder = SessionBuilder::<MyConfig>::new()
+    ///     .with_high_latency_defaults()?;
+    /// # Ok::<(), FortressError>(())
+    /// ```
+    ///
+    /// [`SyncConfig::mobile()`]: crate::SyncConfig::mobile
+    /// [`ProtocolConfig::mobile()`]: crate::ProtocolConfig::mobile
+    /// [`TimeSyncConfig::mobile()`]: crate::TimeSyncConfig::mobile
+    /// [`InputQueueConfig::high_latency()`]: crate::InputQueueConfig::high_latency
+    /// [`FortressError::InvalidRequest`]: crate::FortressError::InvalidRequest
+    pub fn with_high_latency_defaults(self) -> Result<Self, FortressError> {
+        self.with_sync_config(SyncConfig::mobile())
+            .with_protocol_config(ProtocolConfig::mobile())
+            .with_time_sync_config(TimeSyncConfig::mobile())
+            .with_input_queue_config(InputQueueConfig::high_latency())
+            .with_input_delay(4)
+    }
+
     /// Consumes the builder to construct a [`P2PSession`] and starts synchronization of endpoints.
     /// # Errors
     /// - Returns [`InvalidRequest`] if insufficient players have been registered.
@@ -1290,4 +1425,105 @@ mod tests {
             .handles
             .contains_key(&PlayerHandle::new(1)));
     }
+
+    // ========================================================================
+    // Session Preset Tests
+    // ========================================================================
+
+    #[test]
+    fn with_lan_defaults_returns_valid_builder() {
+        // Arrange & Act: Create builder with LAN preset
+        let builder = SessionBuilder::<TestConfig>::new()
+            .with_num_players(2)
+            .unwrap()
+            .with_lan_defaults();
+
+        // Assert: Builder is in a valid state and can accept players
+        let result = builder.add_local_player(0);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn with_internet_defaults_returns_valid_builder() {
+        // Arrange & Act: Create builder with internet preset
+        let builder = SessionBuilder::<TestConfig>::new()
+            .with_num_players(2)
+            .unwrap()
+            .with_internet_defaults()
+            .expect("with_internet_defaults should succeed");
+
+        // Assert: Builder is in a valid state and can accept players
+        let result = builder.add_local_player(0);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn with_high_latency_defaults_returns_valid_builder() {
+        // Arrange & Act: Create builder with high-latency preset
+        let builder = SessionBuilder::<TestConfig>::new()
+            .with_num_players(2)
+            .unwrap()
+            .with_high_latency_defaults()
+            .expect("with_high_latency_defaults should succeed");
+
+        // Assert: Builder is in a valid state and can accept players
+        let result = builder.add_local_player(0);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn with_lan_defaults_applies_expected_configs() {
+        // Arrange & Act
+        let builder = SessionBuilder::<TestConfig>::new().with_lan_defaults();
+
+        // Assert: Verify the preset applied the expected configuration
+        assert_eq!(builder.sync_config, SyncConfig::lan());
+        assert_eq!(builder.protocol_config, ProtocolConfig::competitive());
+        assert_eq!(builder.time_sync_config, TimeSyncConfig::lan());
+    }
+
+    #[test]
+    fn with_internet_defaults_applies_expected_configs() {
+        // Arrange & Act
+        let builder = SessionBuilder::<TestConfig>::new()
+            .with_internet_defaults()
+            .expect("with_internet_defaults should succeed");
+
+        // Assert: Verify the preset applied the expected configuration
+        assert_eq!(builder.sync_config, SyncConfig::default());
+        assert_eq!(builder.protocol_config, ProtocolConfig::default());
+        assert_eq!(builder.time_sync_config, TimeSyncConfig::default());
+        assert_eq!(builder.input_delay, 2);
+    }
+
+    #[test]
+    fn with_high_latency_defaults_applies_expected_configs() {
+        // Arrange & Act
+        let builder = SessionBuilder::<TestConfig>::new()
+            .with_high_latency_defaults()
+            .expect("with_high_latency_defaults should succeed");
+
+        // Assert: Verify the preset applied the expected configuration
+        assert_eq!(builder.sync_config, SyncConfig::mobile());
+        assert_eq!(builder.protocol_config, ProtocolConfig::mobile());
+        assert_eq!(builder.time_sync_config, TimeSyncConfig::mobile());
+        assert_eq!(builder.input_queue_config, InputQueueConfig::high_latency());
+        assert_eq!(builder.input_delay, 4);
+    }
+
+    #[test]
+    fn presets_are_chainable_with_other_methods() {
+        // Arrange & Act: Chain preset with additional configuration
+        let builder = SessionBuilder::<TestConfig>::new()
+            .with_num_players(4)
+            .unwrap()
+            .with_lan_defaults()
+            .with_max_prediction_window(6)
+            .with_desync_detection_mode(DesyncDetection::Off);
+
+        // Assert: Both preset and subsequent configs applied
+        assert_eq!(builder.sync_config, SyncConfig::lan());
+        assert_eq!(builder.max_prediction, 6);
+        assert_eq!(builder.desync_detection, DesyncDetection::Off);
+    }
 }