Yleiskatsaus

Steamin vertaispelihaun perustana on aula. Aula on chat-huonetta muistuttava kokonaisuus, joka toimii Steamin taustapalvelimilla. Käyttäjät voivat luoda uuden aulan, liittää aulaan tietoja, hakea auloja näiden tietojen perusteella, liittyä auloihin tai jakaa tietoja samassa aulassa olevien käyttäjien kanssa. Yhdessä aulassa voi olla jopa 250 käyttäjää, vaikka useimmissa peleissä on 2–16 pelaajaa. Taitopohjainen pelihaku on rakennettu tämän järjestelmän päälle.

Steamin vertaispelihaun ohjelmointirajapinta on joukko toimintoja, joilla käyttäjät voivat löytää toisiaan peliseuraksi. Pelihakutoiminnot ovat saatavilla ISteamMatchmaking-ohjelmointirajapinnassa, joka sisältää lisätietoja kunkin toiminnon parametreista. Aulat yksilöidään Steam ID:llä käyttäjien tai pelipalvelinten tapaan. Steamworks-esimerkissä on täysin toimiva aulojen toteutus.

Pelihakuprosessin kulku

Ryhmien yleinen kokoamismalli on seuraavanlainen:

1. Käyttäjä valitsee haluavansa pelata moninpeliä ja moninpelin tyypin (säännöt, skenaario, jne.).
   
2. Peli hakee aulahaun ohjelmointirajapinnalla auloja, joilla on samanlaiset säännöt.
   
3. Jos aula löytyy, peli liittyy aulaan. Jos aulaa ei löydy, peli luo uuden aulan.
   
4. Käyttäjät jäävät aulaan, kunnes mukana on riittävä määrä pelaajia pelin aloittamiseksi. Aulan jäsenten välillä lähetetään tietoja esimerkiksi valittavista hahmoista tai muista käyttäjäkohtaisista asetuksista. Jos aula sisältää valvottavia sääntöjä (esimerkiksi se, että vain yksi käyttäjä voi pelata tiettyä hahmoa), valvonnan voi hoitaa vain aulan omistaja.
   
5. Aulassa voi olla käyttöliittymä. Jos aulassa on sellainen, aulan jäsenet voivat lähettää toisilleen keskusteluviestejä. Myös ääntä voidaan lähettää, mutta siihen on käytettävä Steam-tietoliikenneverkot-ohjelmointirajapintaa.
   
6. Kun peli on käynnistysvalmis, kaikki käyttäjät liittyvät pelipalvelimelle tai muodostavat yhteyden pelin isäntään ja poistuvat sen jälkeen aulasta. Kun kaikki käyttäjät ovat poistuneet aulasta, se poistetaan automaattisesti.

Aulojen hakeminen

Jotta pelisi hakee aulaa, sinun tulee kutsua jäsenfunktiota:
ISteamMatchmaking::RequestLobbyList
Tämä on asynkroninen funktio, joka palauttaa käsittelyyn SteamAPICall_t-kahvan, jota voit käyttää pyynnön tilan seurantaan. Kutsun suorittaminen voi kestää 0,3 sekunnista 5 sekuntiin ja aikakatkaisu on 20 sekuntia. Aika riippuu käyttäjän yhteydestä Steamin taustapalvelimelle.
LobbyMatchList_t kertoo palautuneiden tulosten määrän ja ISteamMatchmaking::GetLobbyByIndex auttaa iteroinnissa ja tunnusten hankkimisessa.
.
Palautettavia tuloksia voi olla jopa 50, mutta yleensä korkeintaan pari. Tulokset palautetaan maantieteelliseen välimatkaan perustuvassa järjestyksessä ja minkä tahansa suodatusmääritysten perusteella. Lähtökohtaisesti täysiä auloja ei palauteta. Välimatkasuodatuksen arvona on k_ELobbyDistanceFilterDefault (lähellä). Jos haluat lisätä suodatusasetuksia, kutsu yksi tai useampia suodatinfunktioita ennen RequestLobbyList-kutsua:

• ISteamMatchmaking::AddRequestLobbyListStringFilter – lisää merkkijonovertailusuodatuksen.
  
• ISteamMatchmaking::AddRequestLobbyListNumericalFilter – lisää lukumäärävertailusuodatuksen.
  
• ISteamMatchmaking::AddRequestLobbyListNearValueFilter – luokittelee tulokset, jotka ovat lähimpänä määritettyä arvoa.
  
• ISteamMatchmaking::AddRequestLobbyListFilterSlotsAvailable – suodattaa palautettavaksi vain aulat, joissa on tietty määrä avoimia paikkoja.
  
• ISteamMatchmaking::AddRequestLobbyListDistanceFilter – asettaa käytettävälle aulahauille fyysisen välimatkan, joka pohjautuu käyttäjien IP-osoitteisiin ja Steamin taustajärjestelmän IP-osoitekarttaan.
  
• ISteamMatchmaking::AddRequestLobbyListResultCountFilter – asettaa palautettavien aulojen enimmäismäärän. Mitä pienempi määrä on, sitä nopeammin aulatulokset ja -tiedot latautuvat sovellukseen.

Aulan luominen

Jos käyttäjälle ei löydy valmista aulaa, hänelle yleensä luodaan sellainen. Kutsu
ISteamMatchmaking::CreateLobby ja odota aulan valmistumista. Kutsutulos ilmoittaa, onnistuiko aulan luominen. Jos onnistui, se palauttaa aulan Steam ID:n takaisinkutsussa LobbyCreated_t, jota voi käyttää aulan metatietojen määrittämiseen. Aulan luomisen jälkeen sille on määritettävä tiedot, joiden avulla pelin muut asiakasohjelmat voivat hakea sitä (ks. alla).

Aulaan liittyminen

Kun olet haulla tai ystävän vihjeellä löytänyt hyvän aulan, voit käyttää ISteamMatchmaking::JoinLobby ja odottaa LobbyEnter_t-takaisinkutsun palautusta. Kun olet aulassa, aulatietojen ohjelmointirajapinnan avulla voit hankkia tietoja aulasta ja selvittää, mitä kannattaisi näyttää (jos näytettävää on).

Kun käyttäjä liittyy aulaan tai poistuu siitä, LobbyChatUpdate_t-takaisinkutsu julkaistaan kaikille aulan jäsenille, myös omistajalle.

Voit iteroida senhetkiset aulassa olevat jäsenet käyttämällä seuraavia:

• ISteamMatchmaking::GetNumLobbyMembers
  
• ISteamMatchmaking::GetLobbyMemberByIndex

Jos haluat lisätietoja aulan muista käyttäjistä, sinun on käytettävä kavereiden ohjelmointirajapintaa. Lisätietoja: Kaverit, kutsut ja aulat.

Aulan metatiedot

Aulan metatietojen avulla voit määrittää aulan tilan, sen nimen, nykyisen kartan, pelitilan, pelin nykytilanteen ja muita haluamiasi tietoja.

Käyttäjä saa automaattisesti uusimmat tiedot kaikista auloista, joissa hän on jäsenenä. Käyttäjä saa hakutulosten palauttamat aulatiedot siltä hetkeltä, kun haku tehtiin. Jos kyseessä on kaverin aula, aulatietoja ei voi katsoa, ennen kuin on kutsuttu jäsenfuntiota ISteamMatchmaking::RequestLobbyData ja käsitelty se onnistuneesti.

Jos aulan tietoja on muutettu aulan sisällä, kaikki sen jäsenet saavat LobbyDataUpdate_t-takaisinkutsun. (Samalla takaisinkutsulla saat tiedon, että jäsenfunktion ISteamMatchmaking::RequestLobbyData kutsu on suoritettu.)

Näillä funktioilla voit noutaa ja määrittää aulatietoja. Vain aulan omistaja voi määrittää tai poistaa aulatietoja.

• ISteamMatchmaking::SetLobbyData
  
• ISteamMatchmaking::GetLobbyData
  
• ISteamMatchmaking::DeleteLobbyData

Näillä funktioilla voit iteroida metatietoja (yleensä vain vianetsintätarkoituksessa):

• ISteamMatchmaking::GetLobbyDataCount
  
• ISteamMatchmaking::GetLobbyDataByIndex

Aulassa jäsenet voivat määrittää myös omia metatietoja, joiden päivityksiä muut jäsenet voivat vastaanottaa. Se onnistuu seuraavilla funktioilla.

• ISteamMatchmaking::GetLobbyMemberData
  
• ISteamMatchmaking::SetLobbyMemberData

Aulan sisäinen viestintä

Voit lähettää aulan sisällä tietoja (chat-viestejä, pelinaloitussignaaleja jne.) kutsumalla ISteamMatchmaking::SendLobbyChatMsg. Kutsu lähettää yksinkertaisen binaariviestin kaikille aulassa oleville käyttäjille. Aulan jäsenten on kuunneltava takaisinkutsua ISteamMatchmaking::LobbyChatMsg_t. Takaisinkutsun vastaanottamisen jälkeen voit palauttaa viestin sisällön kutsumalla ISteamMatchmaking::GetLobbyChatEntry .

Kaverit, kutsut ja aulat

Voit saada selville kaikki aulat, joissa käyttäjän kaverit ovat, käyttämällä kaverien ohjelmointirajapintaa:

Voit kutsua kaverin aulaan jäsenfunktiolla ISteamMatchmaking::InviteUserToLobby
.
Käyttäjä vastaanottaa chat-ikkunan, jossa on linkki peliin liittymiseksi. Jos käyttäjä klikkaa linkkiä eikä kyseinen peli ole käynnissä, linkki käynnistää pelin komentorivillä:
+connect_lobby <64-bit lobby id>. Varmista, että sovellus käyttää jäsenfunktiota ISteamApps::GetLaunchCommandLine, jotta voit poistaa ponnahdusvaroituksen, kun komentorivillä käynnistys on tehty.

Jos käyttäjä on jo pelissä, julkaistaan ISteamFriends::GameLobbyJoinRequested_t-takaisinkutsu, joka sisältää Steam-tunnuksen sille aulalle, johon käyttäjä haluaa liittyä. Pelistäsi riippuu, noudattaako se kutsua.

Jos haluat, että käyttäjä valitsee aulaan kutsuttavan käyttäjän kaveriluettelosta, voit kutsua ISteamFriends::ActivateGameOverlayInviteDialog.
Se aktivoi Steamin pelinaikaisen yhteisönäkymän, joka on suunniteltu sitä varten, että kaverit voi kutsua senhetkiseen aulaan.

Varmentaminen

Steamin auloissa olevat käyttäjät on varmennettu jo täysin Steamin taustajärjestelmällä. Pelin ei tarvitse suorittaa ylimääräisiä vaiheita aulan käyttäjien todentamiseksi, jollei ole tarvetta tarkistaa, onko käyttäjällä VAC-kielto (tutustu Valven huijauksenestojärjestelmään). Jos käyttäjä yrittää kirjautua sisään samalla tilillä toisesta sijainnista, hänen aiempi kirjautumisensa poistetaan automaattisesti mahdollisista auloista.

Lopputoimet

Kun peli on alkanut, jokainen käyttäjä voi poistua aulasta kutsumalla
ISteamMatchmaking::LeaveLobby
Kun kaikki käyttäjät ovat poistuneet, taustajärjestelmä poistaa aulan automaattisesti.

Aulavinkit

• Luo auloja vain silloin, kun niitä tarvitaan. Esimerkiksi, kun käyttäjä kutsuu kaverin pelaamaan tai käynnistää manuaalisesti aulaa edellyttävän toiminnon.
  
• Älä päivitä aulojen metatietoja liian tiuhaan. Lisää vain metatietoja ja arvoja, joita käytetään hauissa (esimerkiksi pelityyppi tai pelitilanne). Sinulla ei tarvitse olla pelaajien lukumääriä, koska aulan hakutoiminto etsii auloja, joissa on vapaita paikkoja.
  
• Älä liity auloihin hakeaksesi niiden metatietoja. Aulojen metatiedot voidaan ladata erikseen kaikista auloista, joita pelisi voi käyttää joko näyttääkseen käyttäjälle auloista listan, josta käyttäjä voi valita, tai peli voi automaattisesti päättää, mihin hakutuloksiin se haluaa liittyä.

Onko sinulla kysyttävää?

Esitä kysymyksiä Steamin pelihakua ja aulat -keskustelussa.