Dokumentace systému Steamworks
Vyhledávání zápasů a lobby
Dokumentace systému Steamworks > Funkce > Multiplayer > Vyhledávání zápasů a lobby

Přehled

Peer-to-peer vyhledávání zápasů je vybudováno kolem konceptu lobby, kde lobby je entita připomínající chatovací místnost, která působí z backendových serverů služby Steam. Uživatelé mohou vytvářet nová lobby, spojovat data s lobby, vyhledávat lobby na základě těchto dat, připojovat se do lobby a sdílet informace s dalšími členy lobby. V jednom lobby se může nacházet až 250 uživatelů, ale běžně do nich hry umisťují od 2 do 16 uživatelů. Na základech tohoto systému stojí také vyhledávání zápasů podle dovedností.

API peer-to-peer vyhledávání zápasů je sada funkcí, které uživatelům umožňují nacházet další uživatele ke hraní. Všechny funkce vyhledávání zápasů shromažďuje rozhraní ISteamMatchmaking, na jehož stránce dokumentace se také dočtete podrobnosti o parametrech jednotlivých funkcí. Každé lobby má, stejně jako uživatelé a herní servery, přiřazeno unikátní Steam ID. Ukázková aplikace systému Steamworks má implementovaná plně funkční lobby.

Model fungování

Běžný model pro spojení skupin za účelem hraní vypadá následovně:
  1. Uživatel ve hře určí, že chce hrát režim pro více hráčů, a specifikuje podrobnosti zápasu (pravidla, scénáře apod.).
  2. Hra za pomoci API vyhledá lobby s podobnými specifikacemi.
  3. Pokud je lobby nalezeno, hra do něj uživatele připojí. Pokud lobby není nalezeno, hra vytvoří nové.
  4. Uživatel zůstane v lobby tak dlouho, dokud se nepřipojí dostatek dalších uživatelů pro zahájení zápasu. Mezi členy lobby jsou přeposílána data o tom, kdo bude hrát za jakou postavu a/nebo jiná nastavení specifická pro každého uživatele. Pokud existují nějaká pravidla, která mají být v lobby vynucena (např. jenom jeden uživatel může hrát za určitou postavu), rozhoduje o nich pouze vlastník lobby.
  5. S lobby může, ale nemusí být spojeno uživatelské rozhraní. Pokud je, lze pro posílání textových zpráv mezi členy lobby použít související komunikační funkce. Hlasová komunikace je také možná, ale pro tu musí být použity síťové funkce služby Steam.
  6. Jakmile je zápas připraven, všichni členové lobby se připojí na herní server, nebo na uživatele, který bude zápas hostovat, a poté lobby opustí. Jakmile lobby opustí všichni jeho členové, je automaticky zničeno.

Vyhledání lobby

Aby Vaše hra začala vyhledávat lobby, zavolejte funkci ISteamMatchmaking::RequestLobbyList.
Tato funkce je asynchronní a vrací popisovač „SteamAPICall_t“, pomocí kterého můžete sledovat stav žádosti. V závislosti na uživatelově spojení s backendem služby Steam může volání zabrat od 300 milisekund do 5 sekund, přičemž časový limit je 20 sekund.
Počet výsledků se nachází ve výsledku volání LobbyMatchList_t, který lze poté použít v ISteamMatchmaking::GetLobbyByIndex pro získání jejich ID.
Vráceno může být až 50 výsledků, ale běžně jich tolik nebývá. Vrácené výsledky jsou seřazeny podle geografické vzdálenosti a vztahují se na ně případné filtry vzdálenosti. Ve výchozím nastavení nejsou vracena plná lobby a filtr vzdálenosti je nastaven na k_ELobbyDistanceFilterDefault (poblíž). Pro přidání filtrů musíte před zavoláním funkce RequestLobbyList zavolat jednu nebo více z filtrovacích funkcí:

Vytvoření lobby

Když se Vám nepodaří najít stávající lobby, do kterého by se uživatel připojil, dalším krokem je typicky vytvoření nového lobby. Jednoduše zavolejte funkci ISteamMatchmaking::CreateLobby a počkejte na její dokončení. Výsledek volání indikuje, jestli bylo úspěšné, nebo ne, a pokud ano, ve struktuře LobbyCreated_t vrátí Steam ID lobby, které lze použít pro nastavení jeho metadat. Což je první věc, kterou chcete po vytvoření lobby udělat, aby ho mohli vyhledat také ostatní uživatelé (viz níže).

Připojení do lobby

Pokud jste našli dobré lobby, ať už vzešlé z vyhledávání, nebo od přítele uživatele, můžete zavolat funkci ISteamMatchmaking::JoinLobby a počkat na výsledek volání LobbyEnter_t. Jakmile se uživatel připojí do lobby, pomocí příslušného API získejte podrobnosti o lobby a o tom, co se má zobrazit (pokud vůbec něco).

Když se uživatel připojí do lobby, nebo lobby opustí, všichni členové lobby včetně vlastníka obdrží zpětné volání LobbyChatUpdate_t.

Pro práci s informacemi o tom, kteří uživatelé se aktuálně nachází v lobby, použijte následující funkce:

Pro získání dalších informací o konkrétním jiném členovi lobby budete muset využít API funkce Přátelé. Viz sekce Přátelé, pozvánky a lobby.

Metadata lobby

Metadata lobby Vám umožňují nastavit libovolný stav lobby, a to včetně názvu, aktuální mapy, herního módu, aktuálního stavu hry nebo čehokoli jiného.

Uživatel automaticky získá nejnovější data lobby, kterého je členem. Pro lobby vrácená vyhledáváním bude mít uživatel k dispozici data z okamžiku, kdy proběhlo hledání. Pokud se jedná o lobby přítele uživatele, nebudou k dispozici žádná data, dokud nedojde k zavolání a úspěšnému dokončení funkce ISteamMatchmaking::RequestLobbyData.

Pokud dojde ke změně dat lobby, všichni členové tohoto lobby obdrží zpětné volání LobbyDataUpdate_t (stejné zpětné volání, díky kterému se dozvíte, že bylo dokončeno volání ISteamMatchmaking::RequestLobbyData).

Následující sadu funkcí lze použít pro získání a nastavení dat lobby. Upozorňujeme, že data lobby může nastavit nebo odstranit pouze vlastník daného lobby.

Tyto funkce umožňují práci s metadaty (typicky pro účely debuggování):

A konečně, tyto funkce umožňují členům lobby nastavovat vlastní metadata, která uvidí ostatní členové:

Komunikace v rámci lobby

Pro odeslání informace v rámci lobby (textové zprávy, signálu zahájení zápasu apod.) musíte zavolat funkci ISteamMatchmaking::SendLobbyChatMsg, která všem členům lobby odešle prostou binární zprávu. Členové lobby musí nicméně naslouchat pro zpětné volání ISteamMatchmaking::LobbyChatMsg_t, po jehož obdržení mohou skrze funkci ISteamMatchmaking::GetLobbyChatEntry získat obsah zprávy.

Přátelé, pozvánky a lobby

Všechna lobby, v nichž se nachází přátelé daného uživatele, můžete najít pomocí API funkce Přátelé:
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() ) { // Pokud je „friendGameInfo.m_steamIDLobby“ platné lobby, můžete se do něj připojit, nebo přes „RequestLobbyData()“ získat jeho metadata. } }

Přítele lze do lobby pozvat pomocí funkce ISteamMatchmaking::InviteUserToLobby.
Tomuto uživateli se otevře dialogové okno konverzace s odkazem k připojení. Pokud uživatel na odkaz klikne a nemá aktuálně spuštěnou hru, bude spuštěna s následujícím příkazem:
+connect_lobby <64bitové ID lobby>. Ujistěte se však, že má Vaše hra implementovanou funkci ISteamApps::GetLaunchCommandLine, takže je možné zakázat vyskakovací upozornění při spuštění z příkazové řádky.

Pokud už se uživatel nachází ve hře, bude odesláno zpětné volání ISteamFriends::GameLobbyJoinRequested_t obsahující Steam ID lobby, do kterého se uživatel chce připojit. To, zdali bude požadavek respektován, záleží na Vaší hře.

Pokud chcete, aby uživatel mohl pozvat své přátele do lobby přímo ze seznamu přátel, můžete zavolat funkci ISteamFriends::ActivateGameOverlayInviteDialog,
která otevře překrytí služby Steam na dialogovém okně pro zvaní přátel.

Ověření

Každý uživatel, který se nachází v lobby, je už plně ověřen backendem služby Steam, takže Vaše hra nemusí provádět žádné další kroky, leda by si chtěla ověřit, zdali na uživatele nebyl uvalen ban ochrany VAC (viz dokumentace Valve Anti-Cheat). Pokud se uživatel pokusí přihlásit z jiné lokace pod stejným účtem, předchozí relace přihlášení bude automaticky odebrána ze všech stávajících lobby.

Úklid

Jakmile je zahájen zápas, každý uživatel může opustit lobby zavoláním této funkce:
ISteamMatchmaking::LeaveLobby
Jakmile lobby opustí všichni jeho členové, je v backendu automaticky zničeno.

Tipy pro lobby

  • Obecně platí, že lobby byste měli vytvořit, pouze když je třeba. Například když uživatel pozve přítele do hry nebo provede nějakou akci, pro kterou je lobby vyžadováno.
  • Neaktualizujte metadata lobby příliš často a přidávejte pouze metadata a hodnoty, které jsou používány pro hledání (např. herní mód nebo stav lobby). Počet uživatelů není nutné zadávat, jelikož při vyhledávání jsou standardně hledána lobby s volnými sloty.
  • Nepřipojujte se do lobby jen proto, abyste získali jejich metadata. Metadata lze stáhnout odděleně pro všechna lobby a tato data může Vaše hra poté použít pro zobrazení seznamu lobby, ze kterých si uživatel vybere, nebo ze kterých bude vybráno automaticky.

Máte jiný dotaz?

Zeptejte se v podfóru Multiplayer Matchmaking and Lobbies.
Steamworks je sada nástrojů a funkcí vytvořených společností Valve, které pomáhají s přípravou, distribucí a správou her ve službě Steam.