Wprowadzenie

Model peer-to-peer wyszukiwania gier na Steam opiera się na pomyśle poczekalni. Poczekalnia jest obiektem znajdującym się na serwerach Steam i przypomina pokój czatowy. Użytkownicy mogą sami stworzyć nową poczekalnię, powiązać dane z poczekalnią, szukać poczekalni w oparciu o te dane oraz współdzielić informacje z innymi użytkownikami poczekalni. Każda poczekalnia może mieć do 250 użytkowników, choć zazwyczaj większość gier ma od 2 do 16 graczy. Wyszukiwanie gier w oparciu o umiejętność graczy jest zbudowane na bazie tego systemu.

API wyszukiwania gier na Steam w modelu peer-to-peer jest zestawem funkcji umożliwiających użytkownikom znalezienie innych graczy, z którymi mogą zagrać. Wszystkie funkcje wyszukiwania gier znajdują się w API ISteamMatchmaking, które zawiera szczegóły parametrów każdej funkcji. Poczekalnie posiadają unikalny identyfikator w postaci Steam ID, podobnie jak użytkownicy czy serwery gier. W przykładzie Steamworks można odnaleźć w pełni funkcjonującą implementację poczekalni.

Przebieg procesu wyszukiwania gier

Zazwyczaj dobieranie ze sobą graczy przebiega w następujący sposób:

1. Użytkownik wybiera grę, w którą chce zagrać w trybie wieloosobowym, a następnie decyduje o rodzaju rozgrywki (np. wybiera zasady, scenariusz itd).
   
2. Gra wyszukuje poczekalni, które mają podobny zestaw zasad, za pomocą API wyszukiwania poczekalni.
   
3. Jeśli poczekalnia zostanie znaleziona, to gra się z nią połączy; w przeciwnym wypadku — zostanie stworzona nowa poczekalnia.
   
4. Użytkownicy pozostają w poczekalni do momentu pojawienia się wystarczającej liczby użytkowników potrzebnych do rozpoczęcia gry. Między członkami poczekalni przekazywane są np. dane używanej postaci lub inne ustawienia użytkownika. Jeżeli istnieją zasady w poczekalni, które muszą być narzucone z góry (np. tylko jeden użytkownik może wybrać jakąś postać), rozstrzygnięcie tych kwestii należy tylko do właściciela poczekalni.
   
5. Interfejs poczekalni jest opcjonalny. Jeśli istnieje, to można użyć funkcji wymiany danych do wysyłania wiadomości czatu między członkami poczekalni. Istnieje również możliwość przesyłania danych głosowych, ale do tego celu należy skorzystać z tego API.
   
6. Kiedy gra będzie gotowa do uruchomienia, wszyscy użytkownicy dołączają do serwera gry lub łączą się z użytkownikiem hostującym, po czym opuszczają poczekalnię. Poczekalnia zostaje usunięta natychmiast po tym, jak użytkownicy ją opuszczą.

Wyszukiwanie poczekalni

Aby gra wyszukała poczekalni, musisz wywołać funkcję ISteamMatchmaking::RequestLobbyList
Funkcja ta jest asynchroniczna i zwraca uchwyt SteamAPICall_t, którego możesz użyć do śledzenia stanu żądania. W zależności od tego, jak użytkownik łączy się z platformą Steam, to wywołanie może zająć od 300 ms do 5 s. Zostanie automatycznie zakończone po 20 s.
Liczba zwracanych rezultatów znajduje się wyniku wywołania LobbyMatchList_t, który możesz wykorzystać w funkcji ISteamMatchmaking::GetLobbyByIndex, by iterować po nich oraz uzyskać ID rezultatów.
Zazwyczaj na liście nie pojawia się więcej niż kilka rezultatów, choć ich maksymalna liczba wynosi 50. Rezultaty są zwracane według odległości geograficznej i są oparte o wszelkie ustawione szczegółowe filtry. Domyślnie nie będą zwracane poczekalnie, które są już pełne, a filtr odległości jest ustawiony na k_ELobbyDistanceFilterDefault (bliskie). Aby dodać filtry, przed wywołaniem RequestLobbyList musisz wywołać przynajmniej jedną z poniższych funkcji filtrowania:

• ISteamMatchmaking::AddRequestLobbyListStringFilter — dodaje filtr porównania stringów.
  
• ISteamMatchmaking::AddRequestLobbyListNumericalFilter — dodaje filtr porównania numerycznego.
  
• ISteamMatchmaking::AddRequestLobbyListNearValueFilter — sortuje wyniki od najbardziej zbliżonych do określonej wartości.
  
• ISteamMatchmaking::AddRequestLobbyListFilterSlotsAvailable — filtruje wyniki tak, by zwracać poczekalnie z określoną liczbą wolnych miejsc.
  
• ISteamMatchmaking::AddRequestLobbyListDistanceFilter — ustawia fizyczną odległość, w zakresie której wyszukiwane będą poczekalnie. Opiera się to na adresie IP użytkownika oraz mapie lokacji IP na serwerze Steam.
  
• ISteamMatchmaking::AddRequestLobbyListResultCountFilter — ustawia maksymalną liczbę zwracanych poczekalni. Im niższa liczba, tym szybciej klient pobiera rezultaty i szczegóły poczekalni.

Tworzenie poczekalni

Nowa poczekalnia jest tworzona, gdy nie możesz znaleźć odpowiedniej dla użytkownika wśród tych już istniejących. Po prostu wywołaj funkcję
ISteamMatchmaking::CreateLobby i poczekaj na jej ukończenie. Rezultat wywołania wskaże, czy zadanie powiodło się. Jeśli tak, to zostanie zwrócone SteamID poczekalni w strukturze LobbyCreated_t, której można użyć do ustawienia metadanych poczekalni. Po utworzeniu poczekalni należy ustawić jej dane, by inne klienty gier mogły ją znaleźć (zobacz niżej).

Dołączanie do poczekalni

Jeżeli znalazłeś(-aś) dobrą poczekalnię (z wyszukiwania lub poprzez znajomego) możesz użyć ISteamMatchmaking::JoinLobby i poczekać, by otrzymać rezultat wywołania o nazwie LobbyEnter_t. Po wejściu do poczekalni użyj API danych poczekalni, by uzyskać szczegóły na jej temat i zdecydować, które z nich powinny być wyświetlane (jeżeli coś faktycznie można wyświetlić).

Kiedy użytkownik dołącza do poczekalni lub opuszcza ją, wywołanie zwrotne LobbyChatUpdate_t jest wysyłane do wszystkich członków poczekalni, w tym do jej właściciela.

Aby iterować po użytkownikach znajdujących się w poczekalni, użyj:

• ISteamMatchmaking::GetNumLobbyMembers
  
• ISteamMatchmaking::GetLobbyMemberByIndex

Aby uzyskać więcej informacji na temat innego użytkownika w poczekalni, należy użyć API znajomych – przejdź tutaj.

Metadane poczekalni

Metadane poczekalni pozwalają ci dowolnie ustawić jej stan, w tym jej nazwę, obecną mapę, tryb gry, obecny stan gry i wszystko, co tylko możesz wymyślić.

Użytkownik otrzyma najbardziej aktualne dane każdej poczekalni, której jest członkiem. Dla poczekalni zwróconych w wyniku wyszukiwania użytkownik otrzyma ich dane w oparciu o czas, w którym wykonano wyszukiwanie. Jeśli będzie to poczekalnia znajomego, dane te nie będą dostępne do momentu, gdy funkcja ISteamMatchmaking::RequestLobbyData zostanie wywołana i zakończy się pomyślnie.

Jeśli dane poczekalni zostaną zmienione, użytkownicy poczekalni otrzymają wywołanie zwrotne LobbyDataUpdate_t (dzięki niemu będą mieli pewność, że wywołanie ISteamMatchmaking::RequestLobbyData zakończyło się powodzeniem).

Oto zestaw funkcji, których możesz użyć, aby ustawić dane poczekalni lub uzyskać do nich dostęp. Tylko właściciel poczekalni może je ustawić lub usunąć.

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

Funkcje, które mogą ci pomóc iterować po metadanych (używane zazwyczaj tylko do debugowania):

• ISteamMatchmaking::GetLobbyDataCount
  
• ISteamMatchmaking::GetLobbyDataByIndex

Dzięki następującym funkcjom poczekalnie pozwalają również użytkownikom ustawić ich własne metadane, a innym członkom aktualizować ich stan.

• ISteamMatchmaking::GetLobbyMemberData
  
• ISteamMatchmaking::SetLobbyMemberData

Komunikacja w obrębie poczekalni

Aby wysłać informację w obrębie poczekalni (wiadomość na czacie, sygnał do rozpoczęcia gry itp.), należy wywołać funkcję ISteamMatchmaking::SendLobbyChatMsg, która prześle prosty komunikat binarny do wszystkich użytkowników w poczekalni. Członkowie poczekalni muszą nasłuchiwać wywołania zwrotnego ISteamMatchmaking::LobbyChatMsg_t. Po otrzymaniu wywołania zwrotnego możesz następnie użyć ISteamMatchmaking::GetLobbyChatEntry, by uzyskać zawartość komunikatu.

Znajomi, zaproszenia i poczekalnie

Za pomocą API znajomych możesz znaleźć wszystkie poczekalnie, w których członkami są znajomi użytkownika:

Możesz zaprosić znajomego do poczekalni za pomocą ISteamMatchmaking::InviteUserToLobby.
Użytkownik otrzyma powiadomienie z odnośnikiem, który pozwoli mu rozpocząć grę. Jeżeli użytkownik kliknie w ten odnośnik i nie będzie obecnie grał w grę, gra uruchomi się z następującą komendą:
+connect_lobby <64-bit lobby id>. Upewnij się, że twoja aplikacja implementuje ISteamApps::GetLaunchCommandLine, dzięki czemu możesz wyłączyć wyskakujące okienko z ostrzeżeniem po uruchomieniu z wiersza poleceń.

Jeżeli użytkownik jest już w grze, zostanie wysłane wywołanie zwrotne ISteamFriends::GameLobbyJoinRequested_t zawierające ID Steam poczekalni, do której chce dołączyć użytkownik. Od twojej gry zależy, czy z niego skorzystać, czy nie.

Jeśli chcesz, by użytkownik mógł zaprosić do poczekalni znajomych ze swojej listy, możesz wywołać ISteamFriends::ActivateGameOverlayInviteDialog.
Uruchomi to nakładkę Steam wraz z oknem dialogowym stworzonym do zapraszania znajomych do obecnej poczekalni.

Uwierzytelnianie

Każdy użytkownik w poczekalni Steam jest w pełni uwierzytelniony do korzystania z serwerów Steam. Gra nie musi podejmować żadnych dalszych działań mających na celu uwierzytelnienie użytkowników poczekalni, chyba że chodzi o sprawdzenie, czy nie nałożono na niego blokady VAC (zobacz: technologia Valve Anti-Cheat). Jeżeli użytkownik będzie próbował połączyć się z innego miejsca poprzez to samo konto, jego wcześniejsza sesja wygaśnie we wszystkich poczekalniach, których był członkiem.

Oczyszczanie

Po rozpoczęciu gry każdy użytkownik może opuścić poczekalnię poprzez:
ISteamMatchmaking::LeaveLobby
Poczekalnia zostanie automatycznie usunięta z serwera zaraz po tym, jak wszyscy użytkownicy ją opuszczą.

Wskazówki dotyczące poczekalni

• Poczekalnie powinny być tworzone tylko wtedy, gdy zaistnieje taka potrzeba, np. gdy użytkownik zaprosi znajomego do gry albo podejmie działanie, które wymaga istnienia poczekalni.
  
• Nie aktualizuj zbyt często metadanych poczekalni. Dodawaj tylko metadane i wartości, które są wykorzystywane przy wyszukiwaniu (np. rodzaj lub stan gry). Nie trzeba wprowadzać informacji o liczbie graczy, gdyż wyszukiwarka samoistnie szuka poczekalni z wolnymi miejscami.
  
• Nie dołączaj do poczekalni wyłącznie w celu uzyskania ich metadanych. Metadane każdej z poczekalni można pobierać osobno, przez co gra może je wykorzystać albo do wyświetlenia listy poczekalni (by użytkownik sam ją wybrał), albo do zdecydowania, gdzie użytkownik powinien się znaleźć.

Masz inne pytania?

Jeśli masz jakieś pytania, możesz je zadać na forum dyskusyjnym dotyczącym wyszukiwania gier i poczekalni Steam.