Marathon

A peer-to-peer game engine development kit built with Rust and CRDTs

Marathon is a multiplayer game engine framework designed for building real-time collaborative games with offline-first capabilities. Built on Bevy and iroh, it provides CRDT-based state synchronization, peer-to-peer networking, and persistent state management out of the box - so you can focus on making great games instead of wrestling with networking code.

⚠️ Early Development Notice

This project is in early development (<v1.0.0).

• The API is unstable and may change without notice
• Breaking changes are expected between minor versions
• Not recommended for production use
• Documentation is still being written
• We welcome feedback and contributions!

Version 1.0.0 will indicate the first stable release.

Features

• CRDT-based synchronization - Conflict-free multiplayer state management using OR-Sets, RGA, and LWW semantics
• Peer-to-peer networking - Built on iroh with QUIC transport and gossip-based message broadcasting
• Offline-first architecture - Players can continue playing during network issues and sync when reconnected
• Persistent game state - SQLite-backed storage with automatic entity persistence
• Cross-platform - Supports macOS desktop and iOS (simulator and device), with more platforms planned
• Built with Bevy - Leverages the Bevy game engine's ECS architecture and parts of its ecosystem

Demo

The current demo is a replicated cube game that synchronizes in real-time across multiple instances:

• Apple Pencil input support on iPad
• Real-time player cursor and selection sharing
• Automatic game state synchronization across network partitions
• Multiple players can interact with the same game world simultaneously

Quick Start

Prerequisites

• Rust 2024 edition or later
• macOS (for desktop demo)
• Xcode (for iOS development)

Building the Desktop Demo

# Clone the repository
git clone https://github.com/yourusername/marathon.git
cd marathon

# Build and run
cargo run --package app

To run multiple instances for testing multiplayer:

# Terminal 1
cargo run --package app -- --instance 0

# Terminal 2
cargo run --package app -- --instance 1

Building for iOS

Marathon includes automated iOS build tooling via xtask:

# Build for iOS simulator
cargo xtask ios-build

# Deploy to connected device
cargo xtask ios-deploy

# Build and run on simulator
cargo xtask ios-run

See docs/ios-deployment.md for detailed iOS setup instructions.

Architecture

Marathon is organized as a Rust workspace with four crates:

• libmarathon - Core engine library with networking, persistence, and CRDT sync
• app - Demo game showcasing multiplayer cube gameplay
• macros - Procedural macros for serialization
• xtask - Build automation for iOS deployment

Key Components

• Networking - CRDT synchronization protocol, gossip-based broadcast, entity mapping
• Persistence - Three-tier system (in-memory → write buffer → SQLite WAL)
• Engine - Core event loop, peer discovery, session management
• Debug UI - egui-based debug interface for inspecting state

For detailed architecture information, see ARCHITECTURE.md.

Documentation

• RFCs - Design documents covering core architecture decisions
  • 0001: CRDT Synchronization Protocol
  • 0002: Persistence Strategy
  • 0003: Sync Abstraction
  • 0004: Session Lifecycle
  • 0005: Spatial Audio System
  • 0006: Agent Simulation Architecture
• iOS Deployment Guide - Complete iOS build instructions
• Estimation Methodology - Project sizing and prioritization approach

Technology Stack

• Bevy 0.17 - Game engine and ECS framework
• iroh 0.95 - P2P networking with QUIC
• iroh-gossip 0.95 - Gossip protocol for multi-peer coordination
• SQLite - Local persistence with WAL mode
• rkyv 0.8 - Zero-copy serialization
• egui 0.33 - Immediate-mode GUI
• wgpu 26 - Graphics API (via Bevy)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development environment setup
• Code style and conventions
• How to submit pull requests
• Testing guidelines

Please also read our Code of Conduct and AI Usage Policy.

Project Status

Marathon is actively developed and currently focused on:

• Core CRDT synchronization protocol
• Persistence layer stability
• Multi-platform support (macOS, iOS)
• Demo applications

See our roadmap for planned features and known issues.

Community

• Issues - GitHub Issues
• Discussions - GitHub Discussions

Security

Please see our Security Policy for information on reporting vulnerabilities.

License

Marathon is licensed under the MIT License.

Acknowledgments

Marathon builds on the incredible work of:

• The Bevy community for the game engine
• The iroh team for P2P networking infrastructure
• The Rust CRDT ecosystem

---

Built with Rust 🦀 and collaborative spirit