DOCSEARCHbyAlgolia
Submit Docs

Matchbox

repository·main·Indexed 22 days ago

https://github.com/johanhelsing/matchbox

A peer-to-peer networking library for Rust (Native and WASM) designed for low-latency multiplayer games using WebRTC. It abstracts signaling and peer connection negotiation and includes the bevy_matchbox extension for the Bevy game engine. The ecosystem consists of matchbox_socket for socket abstraction, matchbox_signaling for building signaling servers, and matchbox_server as a ready-to-use full-mesh signaling server.

Tokens
19.8K
Snippets
62
Records
88
Agent score
77%

What's inside matchbox

  1. Overview of Matchbox P2P Networking

    main

    Matchbox provides painless peer-to-peer WebRTC networking for both native Rust and WASM applications. It is designed to facilitate low-latency multiplayer games by enabling UDP-like, unordered, and unreliable P2P connections.

    Key features include:

    • Support for both unreliable and reliable data channels.
    • Configurable ordering guarantees.
    • Variable packet retransmits.
    • Seamless integration with the Bevy game engine via bevy_matchbox.
    • Compatibility with ggrs via the ggrs feature in matchbox_socket.

  2. Use matchmaking with the 'next' parameter

    main

    The signaling server supports rudimentary matchmaking via a query parameter. By appending ?next=N to the room ID in your WebSocket URL, you can specify how many players should be grouped together in a single room.

    For example, if you use ?next=3, the server will connect the first three players to each other, and then the next three players to each other in a separate group.

    # Example URL pattern
wss://match.example.com/room_id?next=3

  3. Core components of the Matchbox project

    main

    The Matchbox ecosystem consists of several specialized crates:

    • matchbox_socket: The primary socket abstraction for WASM or Native. Includes a ggrs feature for ggrs compatibility.
    • matchbox_signaling: A library for building signaling servers.
    • matchbox_server: A ready-to-use full-mesh signaling server.
    • bevy_matchbox: A matchbox_socket integration specifically for the Bevy game engine.

  4. How Matchbox P2P connections work

    main

    Matchbox uses WebRTC to establish direct peer-to-peer connections. Because WebRTC requires an initial exchange of information to connect, a signaling service is used to facilitate this.

    The Workflow:

    1. Signaling: A client connects to a signaling service (like matchbox_server). The server notifies existing peers of the new connection via a NewPeer event.
    2. Negotiation: Peers negotiate a connection through the signaling server by exchanging 'offers' and 'answers'.
    3. P2P Connection: Once negotiated, an RTCPeerConnection is established. Data flows directly between peers; the signaling server is no longer involved in the data path.

    Client-side implementation requirements:

    • Create a new socket and provide the signaling server URL.
    • .await the message loop future to process incoming messages.
      • In Bevy, bevy_matchbox handles this automatically.
      • In WASM, use wasm-bindgen-futures to run the loop.
      • Alternatively, poll the future manually once per frame.
    • Use the socket API to monitor connection state changes and send non-blocking packets to peers.

  6. Run the custom signaller example on WASM

    main

    To run the demo in a web browser using WASM, follow these steps:

    1. Prerequisites

    Install the WASM target and the server runner:

    rustup target install wasm32-unknown-unknown
cargo install wasm-server-runner

    2. Serve the WASM application

    Run the following command to compile and serve the application:

    RUSTFLAGS='--cfg getrandom_backend="wasm_js"' cargo run --target wasm32-unknown-unknown

    3. Connect nodes in the browser

    1. Open a browser and navigate to http://127.0.0.1:1334.
    2. Open the browser console to find the Iroh ID and the room join URL.
    3. Open a second browser tab and navigate to the room join URL (e.g., http://127.0.0.1:1334#000DEADBEEF....FFF).
    # Install targets
rustup target install wasm32-unknown-unknown
cargo install wasm-server-runner

# Serve
RUSTFLAGS='--cfg getrandom_backend="wasm_js"' cargo run --target wasm32-unknown-unknown

  8. Run the Simple Example on WASM

    main

    To run the example as a WebAssembly (WASM) application, you must first install the WASM target and a web server runner, then compile and serve the project. Once running, access the application via a web browser at http://127.0.0.1:1334 and check the browser console for execution logs.

    # 1. Install prerequisites
rustup target install wasm32-unknown-unknown
cargo install wasm-server-runner

# 2. Build and serve
cargo run --target wasm32-unknown-unknown

# 3. Access at http://127.0.0.1:1334

  9. Run the custom signaller example on Native

    main

    To run the demo natively, start the first node and then use its Iroh ID to connect a second node.

    1. Start the first node:
      cargo run
    2. Observe the terminal output to find the Iroh ID.
    3. Start the second node using that ID:
      cargo run -- "000DEADBEEF....FFF"
    # First node
cargo run

# Second node (replace with actual Iroh ID)
cargo run -- "000DEADBEEF....FFF"

  10. Run the Bevy + GGRS demo on Native

    main

    To run the demo locally on your machine, ensure you have a Matchbox signaling server running (either the provided matchbox_server or your own at ws://localhost:3536/). Use the following command to launch the application with optional flags for the signaling server address, player count, and room name.

    Note: Enough clients must connect before the game starts.

    cargo run -- [--matchbox ws://127.0.0.1:3536] [--players 2] [--room <name>]

  11. Run the Bevy + GGRS demo on WASM

    main

    To run the demo in a web browser using WebAssembly (WASM), follow these steps:

    1. Prerequisites

    Install the WASM target and a lightweight web server runner:

    rustup target install wasm32-unknown-unknown
cargo install wasm-server-runner

    2. Serve the application

    Run the project targeting the WASM architecture:

    cargo run --target wasm32-unknown-unknown

    3. Access the demo

    Open your browser and navigate to http://127.0.0.1:1334/. You can specify the number of players via a query parameter, for example: http://127.0.0.1:1334/?players=2.

    # Install prerequisites
rustup target install wasm32-unknown-unknown
cargo install wasm-server-runner

# Serve the WASM build
cargo run --target wasm32-unknown-unknown