bones_matchmaker_proto/
lib.rs

1#![doc = include_str!("../README.md")]
2// This cfg_attr is needed because `rustdoc::all` includes lints not supported on stable
3#![cfg_attr(doc, allow(unknown_lints))]
4#![deny(rustdoc::all)]
5
6use serde::{Deserialize, Serialize};
7
8/// ALPN used for the matchmaking protocol.
9pub const MATCH_ALPN: &[u8] = b"/bones/match/0";
10
11/// ALPN used for the direct connections between players.
12pub const PLAY_ALPN: &[u8] = b"/bones/play/0";
13
14//
15// === Matchmaking Mode ===
16//
17// These are messages sent when first establishing a connection to the matchmaker and waiting for a
18// match.
19//
20/// Requests that may be made in matchmaking mode
21#[derive(Serialize, Deserialize, Debug, Clone)]
22pub enum MatchmakerRequest {
23    /// Request to have the client join matchmaking queue
24    RequestMatchmaking(MatchInfo),
25    /// Request to remove the client from the matchmaking queue
26    StopMatchmaking(MatchInfo),
27    /// Request a list of lobbies for a specific game
28    ListLobbies(String),
29    /// Request to create a new lobby
30    CreateLobby(LobbyInfo),
31    /// Request to join an existing lobby for a specific gameid, optionally providing a password
32    JoinLobby(GameID, LobbyId, Option<String>),
33}
34
35/// Information about a match that is being requested
36#[derive(Serialize, Deserialize, Debug, Clone, Hash, Eq, PartialEq)]
37pub struct MatchInfo {
38    /// The maximum number of players to have in a match.
39    pub max_players: u32,
40    /// This is an arbitrary set of bytes that must match exactly for clients to end up in the same match.
41    /// This allows us to support matchmaking for different modes or game versions with the same matchmaking server.
42    pub match_data: Vec<u8>,
43    /// The unique identifier for the game
44    pub game_id: GameID,
45    /// Enables choosing how player_idx should be assigned to each player who joins the match.
46    pub player_idx_assignment: PlayerIdxAssignment,
47}
48
49/// Information about a lobby
50#[derive(Serialize, Deserialize, Debug, Clone)]
51pub struct LobbyInfo {
52    /// The name of the lobby
53    pub name: String,
54    /// The maximum number of players allowed in the lobby
55    pub max_players: u32,
56    /// The hashed password for the lobby, if any
57    pub password_hash: Option<String>,
58    /// This is an arbitrary set of bytes that the lobby creator specifies and which other clients must read/accept (ie. settings, version number, etc.)
59    pub match_data: Vec<u8>,
60    /// The unique identifier for the game
61    pub game_id: String,
62    /// Enables choosing how player_idx should be assigned to each player who joins the match.
63    pub player_idx_assignment: PlayerIdxAssignment,
64}
65
66/// Choose how player_idx should be assigned to each player who joins a match/lobby.
67#[derive(Serialize, Deserialize, Debug, Clone, Hash, Eq, PartialEq, Default)]
68pub enum PlayerIdxAssignment {
69    /// The players will be assigned an idx based on the order that they join the match/lobby.
70    #[default]
71    Ordered,
72    /// The players will randomly be assigned an idx
73    Random,
74    /// The order specified in the Vec will be assigned to the players based on the order they join the match/lobby.
75    /// Ie. If the Vec contains `0,2,1,3` then the first player will get player_idx 0, second 2, third 1, and fourth 3.
76    SpecifiedOrder(Vec<usize>),
77}
78
79/// A unique identifier for a game
80pub type GameID = String;
81
82/// A unique identifier for a lobby
83#[derive(Serialize, Deserialize, Debug, Clone, Hash, Eq, PartialEq)]
84pub struct LobbyId(pub String);
85
86/// Responses that may be returned in matchmaking mode
87#[derive(Serialize, Deserialize, Debug, Clone)]
88pub enum MatchmakerResponse {
89    /// The connection has been accepted
90    Accepted,
91    /// Response that specifies updates about the current matchmaking (ie. player count updates)
92    MatchmakingUpdate { player_count: u32 },
93    /// The desired client count has been reached, and the match may start.
94    Success {
95        /// The random seed that each client should use.
96        random_seed: u64,
97        /// The client idx of the current client
98        player_idx: u32,
99        /// The number of connected clients in the match
100        player_count: u32,
101        /// The node ids of all players.
102        player_ids: Vec<(u32, iroh::NodeAddr)>,
103    },
104    /// Response that specifies updates about the current lobby (ie. player count updates)
105    LobbyUpdate { player_count: u32 },
106    /// A list of available lobbies
107    LobbiesList(Vec<LobbyListItem>),
108    /// Confirmation that a lobby has been created
109    LobbyCreated(LobbyId),
110    /// Confirmation that a client has joined a lobby
111    LobbyJoined(LobbyId),
112    /// An error message
113    Error(String),
114}
115
116/// Information about a lobby for the lobby list
117#[derive(Serialize, Deserialize, Debug, Clone)]
118pub struct LobbyListItem {
119    /// The unique identifier of the lobby
120    pub id: LobbyId,
121    /// The name of the lobby
122    pub name: String,
123    /// The current number of players in the lobby
124    pub current_players: u32,
125    /// The maximum number of players allowed in the lobby
126    pub max_players: u32,
127    /// Whether the lobby is password protected
128    pub has_password: bool,
129    /// The unique identifier for the game this lobby belongs to
130    pub game_id: String,
131}
132
133/// The format of a message sent by a client to the proxy, so the proxy can send it to another client.
134#[derive(Serialize, Deserialize, Debug, Clone)]
135pub struct SendProxyMessage {
136    /// The client that the message should go to.
137    pub target_client: TargetClient,
138    /// The message data.
139    pub message: Vec<u8>,
140}
141
142/// The client to send a network message to.
143#[derive(Serialize, Deserialize, Debug, Clone)]
144pub enum TargetClient {
145    /// Send the message to all connected clients.
146    All,
147    /// Send the message to the client with the specified index.
148    One(u8),
149}
150
151/// The format of a message forwarded by the proxy to a client.
152#[derive(Serialize, Deserialize, Debug, Clone)]
153pub struct RecvProxyMessage {
154    /// The client that the message came from.
155    pub from_client: u8,
156    /// The message data.
157    pub message: Vec<u8>,
158}
bones_matchmaker_proto/lib.rs

bones_matchmaker_proto/
lib.rs
