fortress-rollback 0.4.1

Fortress Rollback (a fork of GGRS) is a fortified, verified P2P rollback networking library for Rust.
Documentation

🤖 AI-Assisted Development Notice

This project was developed with substantial AI assistance. The vast majority of the code, documentation, tests, and formal specifications were written with the help of Claude Opus 4.5 and Codex 5.1. Human oversight was provided for code review, architectural decisions, and final approval, but the implementation work was heavily AI-driven. This transparency is provided so users can make informed decisions about using this crate.

⚠️⚠️⚠️ WARNING ⚠️⚠️⚠️

This crate is currently in alpha state as I start integrating it with some in-development game projects. I will utilize semver to the best of my ability to help guard against breaking changes. The main goal of this is to provide a robust, easy-to-use, 100% reliable rollback engine for games. As such, there may be anywhere between "zero" API changes and "complete overhauls". This readme and the version will be updated appropriately as things stabilize.

P2P Rollback Networking in Rust

Fortress Rollback is a fortified, correctness-first port of the original, phenomenal ggrs crate and reimagination of the GGPO network SDK, written in 100% safe Rust 🦀. This crate was primarily developed with AI assistance. The callback-style API from the original library has been replaced with a simple, request-driven control flow: instead of registering callback functions, Fortress Rollback returns a list of requests for the user to fulfill.

If you are interested in integrating rollback networking into your game or just want to chat with other rollback developers (not limited to Rust), check out the GGPO Developers Discord!

Interactive Examples

Fortress Rollback includes interactive game examples built with macroquad. Run them locally to see rollback networking in action:

# P2P session (run in two terminals with different ports)
cargo run --example ex_game_p2p --features graphical-examples -- --local-port 7000 --remote-addr 127.0.0.1:7001
cargo run --example ex_game_p2p --features graphical-examples -- --local-port 7001 --remote-addr 127.0.0.1:7000

# Sync test (determinism verification)
cargo run --example ex_game_synctest --features graphical-examples

See the examples README for system dependencies and more options.

Getting Started

To get started with Fortress Rollback, check out the following resources:

  • 📖 User Guide — Full documentation site with guides, architecture, and API reference
  • 📚 GitHub Wiki — Quick reference and community-editable docs
  • 💻 Examples — Working code examples for common use cases
  • 🎮 Request Handling Example — How to handle game loop requests with manual matching or the handle_requests! macro
  • 📋 API Documentation — Auto-generated Rust docs on docs.rs

System Dependencies for Examples

The interactive examples use macroquad, which requires system libraries:

Linux (Debian/Ubuntu):

sudo apt-get install libasound2-dev libx11-dev libxi-dev libgl1-mesa-dev

Linux (Fedora/RHEL):

sudo dnf install alsa-lib-devel libX11-devel libXi-devel mesa-libGL-devel

macOS/Windows: No additional dependencies required.

Development Status

Alpha / experimental only.

Key Improvements in Fortress Rollback

  • 100% Deterministic: All collections use BTreeMap/BTreeSet for guaranteed iteration order; new hash module provides FNV-1a deterministic hashing
  • Panic-Free API: All public APIs return Result types instead of panicking — no unexpected crashes
  • Correctness-First: Formally verified with TLA+ and Z3 proofs; ~1600 tests (~92% coverage) including multi-process network and resilience scenarios
  • Enhanced Desync Detection: Built-in checksum validation with P2PSession::confirmed_inputs_for_frame() for debugging state divergence
  • handle_requests! Macro: Eliminates boilerplate in the game loop — see User Guide
  • Config Presets: SyncConfig::lan(), ProtocolConfig::mobile(), etc. for common network conditions

📋 Complete comparison with GGRS → — See all differences, bug fixes, and migration steps

Network Requirements

Condition Supported Optimal
RTT <200ms <100ms
Packet Loss <15% <5%
Jitter <50ms <20ms

For detailed configuration guidance, see the User Guide.

Feature Flags

Feature Description
sync-send Adds Send + Sync bounds for multi-threaded game engines (e.g., Bevy)
tokio Enables TokioUdpSocket for async Tokio applications
paranoid Runtime invariant checking in release builds
graphical-examples Enables ex_game graphical examples (requires macroquad deps)
loom Loom-compatible synchronization primitives for concurrency testing
json JSON serialization for telemetry types (to_json() methods)

For detailed feature documentation, see the User Guide.

Migration from ggrs

Moving from the original ggrs crate? See the step-by-step guide in migration.md. It covers the crate rename (fortress-rollback), the new Config::Address Ord bound, and import changes (fortress_rollback).

Web / WASM Support

Fortress Rollback works in the browser! WASM support is automatic — no feature flags needed. The library detects target_arch = "wasm32" at compile time and uses browser-compatible APIs (web_time for timing, js_sys::Date for epoch timestamps).

For networking in the browser, use Matchbox — it provides WebRTC sockets that implement NonBlockingSocket and work seamlessly with Fortress Rollback:

[dependencies]
fortress-rollback = "0.4"
matchbox_socket = { version = "0.13", features = ["ggrs"] }

Matchbox handles:

  • WebRTC peer-to-peer connections — direct data channels between browsers
  • Signaling server — connection establishment (only needed during setup)
  • Cross-platform — works on native and WASM with the same API

See the custom socket example for implementing your own transport (WebSockets, custom protocols, etc.)

Licensing

Fortress Rollback is dual-licensed under either

at your option.