Oversigt

Steams peer-to-peer-matchmaking er bygget op omkring lobbykonceptet. En lobby er en enhed, som eksisterer i Steams backend-servere, som fungerer meget lig et chatrum. Brugere kan oprette en ny lobby, knytte data til en lobby, søge efter lobbyer baseret på disse data, tilslutte sig lobbyer og dele oplysninger med andre brugere i lobbyen. En enkelt lobby kan have op til 250 brugere, selvom de fleste spil typisk har maksimalt 2-16 spillere. Færdighedsbaseret matchmaking er bygget oven på dette system.

Steams peer-to-peer matchmaking-API er et sæt af funktioner, som giver brugere mulighed for at finde andre brugere at spille med. Alle matchmaking-funktionerne eksisterer i ISteamMatchmaking, som indeholder flere detaljer om parametrene for hver funktion. Lobbyer identificeres entydigt af et Steam-ID, ligesom brugere eller spilservere. Steamworks-eksemplet har en fuldstændig implementering af lobbyer.

Matchmaking-processen

Den almindelige model til at samle folk i grupper er som følger:

1. Brugeren vælger i spillet, at vedkommende gerne vil spille multiplayer, og hvilken slags multiplayer brugeren ønsker (regler, scenarie osv.).
   
2. Spillet søger efter lobbyer, som har lignende sæt af regler ved at bruge lobbysøgnings-API'en.
   
3. Hvis en lobby bliver fundet, tilslutter spillet sig denne lobby. Hvis ingen lobby bliver fundet, opretter den i stedet en ny lobby.
   
4. Brugerne bliver i en lobby, indtil der er nok spillere klar til at starte spillet. Data kommunikeres mellem lobbyens medlemmer om, hvilke karakterer de ønsker at spille, eller andre brugerspecifikke indstillinger. Hvis der er regler, som skal håndhæves i lobbyen (for eksempel kun én bruger kan spille som en bestemt karakter), er der én og kun én lobbyejer, som du kan bruge til at mægle dette.
   
5. Der er muligvis en brugergrænseflade knyttet til lobbyen. Hvis der er, kan lobbyens datakommunikationsfunktioner bruges til at sende chatbeskeder mellem lobbymedlemmer. Stemmedata kan også sendes, men de skal sendes ved at bruge API'en for Steam-netværk.
   
6. Når spillet er klar til at starte, tilslutter alle brugerne sig til spilserveren eller opretter forbindelse til den bruger, som er vært for spillet, og forlader derefter lobbyen. Når alle brugere har forladt en lobby, destrueres den automatisk.

Søgning efter lobbyer

For at få dit spil til at søge efter en lobby skal du kalde ISteamMatchmaking::RequestLobbyList
.
Denne funktion er asynkron og returnerer et SteamAPICall_t-handle, som du kan bruge til at spore tilstanden for anmodningen. Afhængigt af brugernes forbindelse til Steams backend kan dette kald tage fra 300 ms til 5 sekunder at gennemføre og har en timeout på 20 sekunder.
Antallet af resultater, som returneres, er i LobbyMatchList_t-kaldsresultatet, som du derefter kan bruge ISteamMatchmaking::GetLobbyByIndex til at gentage over dem alle og få deres ID'er.
Op til 50 resultater kan returneres, men normalt er det ikke mere end et par stykker. Resultaterne bliver returneret sorteret ud fra geografisk afstand og baseret på alle sæt af filtre i nærheden. Som standard vil vi ikke returnere lobbyer, som allerede er fulde, og afstandsfiltret er sat til k_ELobbyDistanceFilterDefault (i nærheden). For at tilføje filtre, før du kalder RequestLobbyList, skal du kalde en eller flere af filterfunktionerne:

• ISteamMatchmaking::AddRequestLobbyListStringFilter – Tilføjer et filter, som sammenligner strenge.
  
• ISteamMatchmaking::AddRequestLobbyListNumericalFilter – Tilføjer et filter, som sammenligner numeriske strenge.
  
• ISteamMatchmaking::AddRequestLobbyListNearValueFilter – Sorterer resultaterne tættest på den angivne værdi.
  
• ISteamMatchmaking::AddRequestLobbyListFilterSlotsAvailable – Filtre til udelukkende at returnere lobbyer med det angivne antal åbne tilgængelige pladser.
  
• ISteamMatchmaking::AddRequestLobbyListDistanceFilter – Indstiller den fysiske afstand, som gælder for de lobbyer, vi søger efter. Dette er baseret på brugerens IP-adresse og et IP-placeringskort i Steams backend.
  
• ISteamMatchmaking::AddRequestLobbyListResultCountFilter – Sætter det maksimale antal af lobbyer, som skal returneres. Jo lavere antallet er, desto hurtigere er det at downloade lobbyens resultatoplysninger til klienten.

Sådan opretter du en lobby

Hvis du ikke kan finde en eksisterende lobby, som en bruger kan tilslutte sig, er det som regel her, at du opretter en lobby. Bare kald
ISteamMatchmaking::CreateLobby, og vent på, at kaldet er fuldført. Kaldsresultatet indikerer, hvorvidt det lykkedes, og hvis det lykkedes, vil det returnere Steam-ID'et fra lobbyen i en LobbyCreated_t-struktur, som kan bruges til at indstille metadata i lobbyen. Det første, du skal gøre, efter du har oprettet lobbyen, er at indstille data om lobbyen, så andre spilklienter kan bruge dataene til at søge efter den (se nedenfor).

Sådan tilslutter du dig en lobby

Hvis du har fundet en god lobby, enten fra en søgning eller fra en ven, kan du bruge ISteamMatchmaking::JoinLobby og vente på LobbyEnter_t-kaldsresultatet. Når du er i lobbyen, skal du bruge lobbydata-API'en til at få oplysninger omkring lobbyen for at finde ud af, hvad der skal vises (hvis der er et display).

Når en bruger tilslutter sig eller forlader en lobby, bogføres et LobbyChatUpdate_t-tilbagekald til alle medlemmer af denne lobby, inklusive ejeren.

For at gentage, hvilke brugere der i øjeblikket er i en lobby, skal du bruge:

• ISteamMatchmaking::GetNumLobbyMembers
  
• ISteamMatchmaking::GetLobbyMemberByIndex

For at få flere oplysninger om en anden bruger i lobbyen skal du bruge venne-API'en. Se Venner, invitationer og lobbyer for yderligere oplysninger.

Lobby-metadata

Lobby-metadata gør det muligt at indstille lobbyens vilkårlige tilstand, inklusive lobbyens navn, nuværende kort, spiltilstand, nuværende tilstand af spillet eller alt andet, du kan komme i tanke om.

En bruger får automatisk de nyeste lobbydata for enhver lobby, som brugeren er medlem af. For lobbyer, som returneres via søgeresultater, har brugeren lobbydata fra det tidspunkt, hvor søgningen blev udført. Hvis det er en vens lobby, vil der ikke være nogen lobbydata tilgængelige til at kigge på, før ISteamMatchmaking::RequestLobbyData er blevet kaldt og gennemført.

Hvis lobbydatene ændres for en lobby, vil alle lobbymedlemmer modtage et LobbyDataUpdate_t-tilbagekald (med dette tilbagekald kan du også se, om ISteamMatchmaking::RequestLobbyData-kald er gennemført).

Det følgende er det sæt af funktioner, som du kan bruge til at få og angive lobbydata. Kun lobbyens ejer kan indstille eller slette lobbydataene.

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

Funktioner, der gør iteration gennem metadata mulig (dette bruges typisk kun til fejlfindingsformål):

• ISteamMatchmaking::GetLobbyDataCount
  
• ISteamMatchmaking::GetLobbyDataByIndex

Lobbyer tillader også medlemmer at indstille deres egne metadata, som andre medlemmer kan modtage opdateringer til med de følgende funktioner.

• ISteamMatchmaking::GetLobbyMemberData
  
• ISteamMatchmaking::SetLobbyMemberData

Kommunikation indenfor en lobby

For at sende oplysninger rundt indenfor en lobby (chatbeskeder, signaler om spilstart osv.) skal du kalde ISteamMatchmaking::SendLobbyChatMsg. Dette sender en simpel binær besked til alle brugere i lobbyen. Lobbymedlemmer skal lytte efter tilbagekaldet ISteamMatchmaking::LobbyChatMsg_t. Efter at have modtaget tilbagekaldet kan du bruge ISteamMatchmaking::GetLobbyChatEntry for at hente indholdet i beskeden.

Venner, invitationer og lobbyer

Du kan finde alle de lobbyer, en brugers venner er i, med venne-API'en:

Du kan invitere en ven til en lobby med ISteamMatchmaking::InviteUserToLobby
. Brugeren får en chatdialogboks med et link til at tilslutte sig spillet. Hvis brugeren klikker på linket, og vedkommende ikke kører spillet i øjeblikket, vil det starte spillet med kommandolinjen:
+connect_lobby <64-bit lobby id>. Sørg for, at din app implementerer ISteamApps::GetLaunchCommandLine, så du kan deaktivere pop op-advarslen, når appen startes via en kommandolinje.

Hvis brugeren allerede er i et spil, vil et ISteamFriends::GameLobbyJoinRequested_t-tilbagekald blive slået op. Dette indeholder Steam-ID'et fra den lobby, som brugeren ønsker at tilslutte sig. Det er op til dig, om spillet skal overholde det eller ej.

Hvis du ønsker, at brugeren skal vælge fra en liste over venner til at invitere til en lobby, kan du kalde ISteamFriends::ActivateGameOverlayInviteDialog.
Dette vil aktivere overlayet i spillet i Steam, så det viser en dialogboks til at invitere venner til den nuværende lobby.

Godkendelse

Enhver bruger i en Steam-lobby er allerede fuldt ud godkendt med Steams backend. Der er ikke brug for, at spillet udfører yderligere godkendelsestrin med lobbybrugerne, medmindre det ser ud, som om de er VAC-udelukket (se Valves anti-cheat-teknologi). Hvis en bruger prøver på at logge ind fra en anden placering med den samme konto, vil brugerens tidligere login automatisk blive fjernet fra eksisterende lobbyer.

Oprydning

Når et spil er blevet startet, kan hver bruger bare forlade en lobby med:
ISteamMatchmaking::LeaveLobby
Når alle brugere har forladt lobbyen, vil den automatisk blive fjernet fra backend'en.

Tips til lobbyen

• Generelt skal der kun oprettes lobbyer, når det er nødvendigt. For eksempel når brugeren inviterer en ven til at spille eller udløser en manuel handling, som kræver en lobby.
  
• Opdater ikke metadataene for lobbyer ofte. Tilføj kun metadata og værdier, som bruges til søgning (for eksempel spiltype eller spillets tilstand). Du behøver ikke at indsætte antallet af spillere, da en lobbysøgning allerede vil søge efter lobbyer med tilgængelige pladser.
  
• Du skal ikke tilslutte dig lobbyer bare for at se deres metadata. Lobbymetadata kan downloades separat for alle lobbyer, som dit spil derefter kan bruge til enten at vise en liste over lobbyer, som en bruger kan vælge fra, eller spillet kan automatisk vælge, hvilket søgeresultat der skal tilsluttes.

Flere spørgsmål?

Stil spørgsmål i diskussionsforummet for Steam-matchmaking og lobbyer.