Introduzione
Il matchmaking peer-to-peer di Steam si basa sul concetto di lobby. Una lobby è un'entità molto simile a una chat room presente nei server del back-end di Steam. Gli utenti possono creare una nuova lobby o unirsi a una già esistente, associare dati a una lobby, cercare una lobby in base a quei dati e condividere informazioni con gli altri utenti presenti nella lobby. Una singola lobby può ospitare fino a 250 utenti, ma tipicamente questo numero varia da 2 a 16 in gran parte dei giochi. Le lobby sono lo strumento principale utilizzato dal matchmaking basato sul livello di abilità.
L'API del matchmaking peer-to-peer di Steam è un insieme di funzioni che consentono agli utenti di trovare altri giocatori con cui avviare una partita. Tutte le funzioni del matchmaking fanno parte dell'API
ISteamMatchmaking, che include maggiori dettagli sui parametri di ciascuna funzione. Le lobby vengono identificate in modo univoco da un ID di Steam, proprio come gli utenti o i server di gioco. L'esempio di Steamworks include un'implementazione completa e funzionante delle lobby.
Flusso del processo di matchmaking
Il modello tipicamente utilizzato per abbinare i giocatori è il seguente:
- L'utente seleziona nel gioco la modalità multigiocatore e configura tutte le impostazioni desiderate (regole, scenario e così via).
- Il gioco cerca le lobby con regole simili utilizzando l'API di ricerca delle lobby.
- Se la ricerca ha esito positivo, il gioco fa unire l'utente alla lobby. In caso contrario, il sistema crea una nuova lobby.
- Gli utenti rimangono nella lobby fino al raggiungimento del numero sufficiente di giocatori per avviare la partita. La lobby comunica a tutti gli altri membri i dati relativi al personaggio scelto o ad eventuali impostazioni personali. Se devono essere applicate alcune regole (ad esempio se un dato personaggio può essere scelto da un solo utente), questo compito verrà affidato all'unico proprietario della lobby.
- La lobby potrebbe essere associata a un'interfaccia utente. In tal caso, le funzionalità di comunicazione dei dati della lobby possono essere utilizzate dai membri per scambiarsi messaggi di chat. È possibile inviare anche dati vocali, ma soltanto tramite l'API Rete di Steam.
- Quando la partita è pronta per iniziare, tutti gli utenti si uniscono al server di gioco o si collegano all'utente designato per ospitare la partita, quindi lasciano la lobby. Quando tutti gli utenti lasciano una lobby, questa viene automaticamente distrutta.
Ricerca delle lobby
Per avviare la ricerca di una lobby, è necessario effettuare una chiamata a
ISteamMatchmaking::RequestLobbyListQuesta funzione asincrona restituisce un handle SteamAPICall_t utilizzabile per tenere traccia dello stato della richiesta. A seconda della connessione degli utenti al back-end di Steam, questa chiamata può richiedere da 300 ms a 5 secondi per il completamento e ha un timeout di 20 secondi.
Il numero dei risultati restituiti si trova all'interno di
LobbyMatchList_t, utilizzabile successivamente con la funzione
ISteamMatchmaking::GetLobbyByIndex per iterare su tutte le lobby e ottenerne i rispettivi ID.
La chiamata può restituire fino a 50 risultati, ma di solito non ne restituisce più di un paio. I risultati vengono restituiti in ordine di distanza geografica e si basano su eventuali filtri definiti per la ricerca. Come impostazione predefinita, i risultati non comprendono le lobby al completo e il filtro della distanza è impostato su
k_ELobbyDistanceFilterDefault (vicino). Per aggiungere altri filtri, sarà necessario utilizzare almeno una delle seguenti funzioni prima di effettuare la chiamata a
RequestLobbyList:
Creazione di una lobby
Generalmente una lobby viene creata se l'utente non riesce a trovarne una già esistente a cui unirsi. È sufficiente chiamare la funzione
ISteamMatchmaking::CreateLobby e attenderne il completamento. Il risultato della chiamata indica se l'operazione è riuscita o meno. In caso di esito positivo, verrà restituito l'ID di Steam della lobby in una struct
LobbyCreated_t, utilizzabile per definire i metadati della lobby. La prima cosa da fare dopo la creazione di una lobby è definirne i dati che gli altri client possono usare per ricercarla (vedi più in basso).
Unirsi a una lobby
Se è stata trovata una lobby adeguata in seguito a una ricerca o grazie all'invito di un amico, puoi utilizzare la funzione
ISteamMatchmaking::JoinLobby e attendere il risultato di chiamata
LobbyEnter_t. Una volta dentro, utilizza l'API dei dati della lobby per ottenerne tutti i dettagli e stabilire cosa mostrare a schermo.
Quando un utente si unisce a una lobby o la abbandona, tutti i membri all'interno, incluso il proprietario, ricevono una callback
LobbyChatUpdate_t.
Usa le seguenti funzioni per iterare sui membri attualmente presenti in una lobby:
Per ottenere ulteriori informazioni su un altro utente nella lobby è necessario utilizzare l'API degli amici. Consulta la sezione
Amici, inviti e lobby per ulteriori informazioni.
Metadati della lobby
I metadati consentono di definire uno stato arbitrario per la lobby, compreso il nome, la mappa attuale, la modalità di gioco, lo stato corrente della partita o qualsiasi altra informazione utile.
L'utente visualizzerà automaticamente i dati più recenti per ogni lobby a cui si è unito. Per le lobby restituite dai risultati di ricerca, l'utente disporrà dei dati ottenuti al momento della ricerca stessa. Se si tratta di una lobby degli amici, i dati non saranno disponibili fino a quando non viene effettuata e completata correttamente la chiamata all'API
ISteamMatchmaking::RequestLobbyData.
Se i dati della lobby vengono modificati, tutti i membri ricevono una callback
LobbyDataUpdate_t (la stessa usata per stabilire se una chiamata a
ISteamMatchmaking::RequestLobbyData è stata completata).
Di seguito sono elencate le funzioni utilizzabili per ottenere e impostare i dati della lobby. Solo il proprietario può impostare o eliminare i dati della lobby.
Queste funzioni consentono di iterare sui metadati e sono in genere utilizzate solo per scopi di debug:
Le funzioni di seguito consentono ai membri delle lobby di definire alcuni metadati su cui gli altri partecipanti possono venire aggiornati.
Comunicazioni nelle lobby
Lo scambio di informazioni all'interno di una lobby (messaggi di chat, segnali di inizio partita e così via) richiede di effettuare una chiamata a
ISteamMatchmaking::SendLobbyChatMsg per inviare un semplice messaggio binario a tutti gli utenti nella lobby. I membri della lobby devono essere in ascolto della callback
ISteamMatchmaking::LobbyChatMsg_t. Dopo aver ricevuto la callback, puoi utilizzare
ISteamMatchmaking::GetLobbyChatEntry per recuperare il contenuto del messaggio.
Amici, inviti e lobby
È possibile trovare tutte le lobby in cui si trovano gli amici di un utente grazie all'API degli amici:
int cFriends = SteamFriends()->GetFriendCount( k_EFriendFlagImmediate );
for ( int i = 0; i < cFriends; i++ )
{
FriendGameInfo_t friendGameInfo;
CSteamID steamIDFriend = SteamFriends()->GetFriendByIndex( i, k_EFriendFlagImmediate );
if ( SteamFriends()->GetFriendGamePlayed( steamIDFriend, &friendGameInfo ) && friendGameInfo.m_steamIDLobby.IsValid() )
{
// friendGameInfo.m_steamIDLobby è una lobby valida. Unisciti a questa lobby o richiedine i metadati utilizzando RequestLobbyData().
}
}
È possibile invitare un amico in una lobby con la funzione
ISteamMatchmaking::InviteUserToLobby.
L'utente riceverà una notifica nella chat con un link per unirsi alla partita. Se l'utente clicca sul link e non ha ancora avviato il gioco, questo verrà aperto con la seguente riga di comando:
+connect_lobby <64-bit lobby id>. Assicurati che la tua applicazione implementi la funzione
ISteamApps::GetLaunchCommandLine per disattivare il popup di avviso quando viene avviata tramite riga di comando.
Se l'utente è già in una partita, verrà inviata una callback
ISteamFriends::GameLobbyJoinRequested_t contenente l'ID di Steam della lobby a cui l'utente vuole unirsi. Sta al gioco decidere se accettare o meno la richiesta.
Se vuoi che l'utente scelga da un elenco gli amici da invitare in una lobby, puoi effettuare la chiamata a
ISteamFriends::ActivateGameOverlayInviteDialog.
Questa funzione aprirà l'Overlay di Steam e mostrerà all'utente una finestra dedicata per invitare gli amici nella lobby attuale.
Autenticazione
Tutti gli utenti in una lobby di Steam risultano già autenticati dal back-end di Steam. Non c'è bisogno che il gioco sottoponga gli utenti delle lobby a ulteriori passaggi di autenticazione, a meno che non si voglia verificare se hanno ricevuto un ban del VAC (consulta la documentazione sul sistema Valve Anti-Cheat). Se un utente cerca di accedere da una posizione diversa con lo stesso account, la sessione precedente verrà rimossa automaticamente da qualsiasi lobby esistente.
Pulizia
Quando la partita ha inizio, ogni utente può abbandonare la lobby con la funzione
ISteamMatchmaking::LeaveLobby.
Una volta che tutti gli utenti hanno lasciato la lobby, questa viene distrutta automaticamente nel back-end.
Suggerimenti per le lobby
- Crea una lobby solo in caso di necessità, ad esempio quando l'utente invita un amico a giocare o esegue un'azione manuale che richiede la creazione di una lobby.
- Non aggiornare troppo spesso i metadati delle lobby. Aggiungi solo i metadati e i valori usati per la ricerca delle lobby, come la tipologia o lo stato della partita. Non sarà necessario inserire il numero dei giocatori: la ricerca delle lobby escluderà in automatico quelle senza posti disponibili.
- Non ti unire alle lobby soltanto per recuperarne i metadati. I metadati possono essere scaricati separatamente per tutte le lobby e utilizzati dal tuo gioco per decidere in automatico a quale unirsi o per mostrare all'utente un elenco di lobby tra cui scegliere.
Altre domande?
Scrivi le tue domande nel
forum di discussione sul matchmaking e sulle lobby di Steam.
