Documentazione di Steamworks
Matchmaking di Steam e lobby

Panoramica

Il sistema di ricerca peer-to-peer di Steam è costruito intorno al concetto della lobby. Una lobby è un'entità presente nei server back-end di Steam molto simile a una chat room. Gli utenti possono creare una nuova lobby o unirsi a una esistente, associarvi dei dati, eseguire una ricerca sulla base di tali dati e condividere informazioni con gli altri utenti presenti. Una singola lobby può ospitare fino a 250 utenti, nonostante nella maggior parte dei giochi la lobby ospita tipicamente dai 2 ai 16 giocatori. Il sistema di ricerca basato sull'abilità è costruito in aggiunta a questo sistema.

L'API del sistema di ricerca 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 sistema di ricerca sono su ISteamMatchmaking, che include maggiori dettagli sui parametri per ciascuna funzione. Le lobby vengono identificate in modo unico da un ID di Steam, proprio come gli utenti o i server di gioco. L'esempio di Steamworks include l'implementazione completa delle funzionalità delle lobby.

Logica di processo del sistema di ricerca

Il processo che consente ai giocatori di unirsi per giocare è il seguente:
  1. L'utente seleziona nel gioco l'opzione multigiocatore e indica le impostazioni desiderate (regole, scenario, ecc.).
  2. Il gioco cerca le lobby con regole simili utilizzando l'API di ricerca delle lobby.
  3. Se la ricerca ha esito positivo, il gioco fa unire l'utente alla lobby. In caso contrario, crea una nuova lobby.
  4. Gli utenti rimangono nella lobby fino al raggiungimento del numero sufficiente di giocatori per avviare la partita. I membri della lobby comunicano i dati relativi al personaggio scelto e altre eventuali impostazioni personali. Se devono essere applicate alcune regole alla lobby (ad esempio, se un dato personaggio può essere scelto solo da un utente), puoi affidare a un singolo e unico proprietario della lobby la gestione dell'assegnazione.
  5. Può essere presente un'interfaccia utente associata alla lobby. In tal caso, le funzioni delle comunicazioni dei dati della lobby possono essere utilizzate per far sì che gli utenti partecipanti possano scambiare messaggi via chat. È possibile inviare anche dati vocali, ma ciò deve essere effettuato mediante l'API Connessione in rete di Steam.
  6. Quando la partita è pronta per iniziare, tutti gli utenti si uniscono al server di gioco o si collegano all'utente designato per ospitarlo, quindi lasciano la lobby. Quando tutti gli utenti si sono uniti alla partita, la lobby viene distrutta automaticamente.

Ricerca delle lobby

Per eseguire la ricerca di una lobby è necessario effettuare la chiamata a ISteamMatchmaking::RequestLobbyList
Questa 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 di risultati restituiti è nel risultato della chiamata LobbyMatchList_t, che puoi utilizzare su ISteamMatchmaking::GetLobbyByIndex per iterare tutti i risultati e ottenere i rispettivi ID.
La chiamata può restituire fino a 50 risultati, ma di solito non ne restituisce più di un paio. I risultati vengono ordinati in base alla distanza geografica e a un qualsiasi set di filtri di prossimità. Come impostazione predefinita, le lobby che hanno già raggiunto il numero massimo di giocatori non vengono restituite nei risultati e il filtro della distanza è impostato su k_ELobbyDistanceFilterDefault (vicino). Per aggiungere filtri, prima di effettuare la chiamata a RequestLobbyList è necessario chiamare una o più funzioni di filtraggio:

Creazione di una lobby

Generalmente una lobby viene creata se l'utente non riesce a trovarne una attiva a cui unirsi. È sufficiente chiamare
ISteamMatchmaking::CreateLobby e attendere il completamento dell'operazione. Il risultato della chiamata indica se è riuscita o meno. In caso positivo, restituirà l'ID di Steam della lobby in una struttura LobbyCreated_t, che può essere utilizzata per impostare i metadati sulla lobby. La prima cosa da fare dopo la creazione di una lobby è impostarvi un dato che gli altri client di gioco possano utilizzare per la ricerca (vedi di seguito).

Unirsi a una lobby

Se è stata trovata una lobby adeguata tramite una ricerca o un amico puoi utilizzare ISteamMatchmaking::JoinLobby e attendere il risultato della chiamata LobbyEnter_t. Una volta dentro, utilizza l'API dei dati della lobby per ottenere i relativi dettagli e capire cosa visualizzare (se ci sono dati da visualizzare).

Quando un utente si unisce a una lobby o la lascia, la richiamata LobbyChatUpdate_t viene inviata a tutti i membri presenti, incluso il proprietario.

Per reiterare quali utenti sono attualmente in una lobby, utilizza:

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 della lobby consentono di impostarne lo stato arbitrario, compreso il nome, la mappa attuale, la modalità di gioco, lo stato corrente del gioco o qualsiasi altro elemento 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 visualizzerà i dati relativi al momento in cui ha eseguito la ricerca. 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 richiamata LobbyDataUpdate_t (è lo stesso metodo per sapere se la 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 eseguire l'iterazione sui metadati e sono in genere utilizzate solo per scopi di debug:

Inoltre, le funzioni di seguito consentono ai membri delle lobby di impostare metadati di cui gli altri partecipanti possano ricevere aggiornamenti.

Comunicazione interna alla lobby

Per inviare informazioni all'interno di una lobby (messaggi di chat, segnali di avvio del gioco, ecc.) è necessario effettuare la chiamata a ISteamMatchmaking::SendLobbyChatMsg, che invierà un semplice messaggio binario a tutti gli utenti nella lobby. I membri della lobby devono ascoltare la nuova chiamata ISteamMatchmaking::LobbyChatMsg_t. Dopo aver ricevuto la nuova chiamata, puoi utilizzare ISteamMatchmaking::GetLobbyChatEntry per recuperare il contenuto del messaggio.

Amici, inviti e lobby

È possibile trovare tutte le lobby a cui gli amici di un utente si sono uniti con l'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 a cui puoi unirti o utilizza RequestLobbyData() per ottenere i metadati } }

È possibile invitare un amico in una lobby con ISteamMatchmaking::InviteUserToLobby.
L'utente visualizzerà una finestra di chat con un collegamento per unirsi alla partita. Se fa clic sul collegamento e il gioco non è ancora in esecuzione, verrà avviato con la seguente riga di comando:
+connect_lobby

Se l'utente è già nel gioco, verrà inviata la richiamata ISteamFriends::GameLobbyJoinRequested_t contenente lo SteamID della lobby a cui l'utente desidera unirsi. È il gioco a definire l'accettazione della richiesta.

Se desideri che l'utente selezioni gli amici da invitare a una lobby da un elenco, puoi effettuare la chiamata ISteamFriends::ActivateGameOverlayInviteDialog.
In questo modo si attiva l'Overlay di Steam nel gioco che mostrerà all'utente una finestra utilizzata per invitare gli amici nella lobby attuale.

Autenticazione

Qualsiasi utente in una lobby di Steam è già completamente autenticato dal back-end di Steam. Non c'è bisogno che il gioco esegua ulteriori fasi di autenticazione per gli utenti della lobby, a meno che non stia cercando di rilevare un eventuale ban del VAC (consulta la sezione Tecnologia anti-trucchi di Valve). Se un utente tenta di accedere da una posizione diversa con lo stesso account, l'accesso precedente verrà rimosso automaticamente da qualsiasi lobby esistente.

Pulizia

Quando la partita inizia, ogni utente può lasciare la lobby con
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 quando è necessario. Ad esempio quando l'utente invita un amico a giocare o attiva un'azione manuale che richiede una lobby.
  • Non aggiornare i metadati sulle lobby con alta frequenza. Aggiungi solo metadati e valori utilizzati per la ricerca (ad esempio, il tipo di gioco o lo stato del gioco). Non dovrai inserire un conteggio dei giocatori, poiché la ricerca nella lobby cercherà già le lobby con gli slot disponibili
  • Non ti unire alle lobby solo per scoprire i loro metadati. I metadati possono essere scaricati separatamente per tutte le lobby e il tuo gioco può utilizzarli per mostrare un elenco di lobby da cui un utente può scegliere, oppure il gioco può decidere automaticamente a quale risultato di ricerca unirsi.

Altre domande?

Fai le tue domande sul forum di discussione Matchmaking di Steam e lobby.