Steamworks 文獻庫
Steam Matchmaking & Lobbies

概覽

Steam 的點對點配對是建立於大廳的概念之上的。 大廳是 Steam 後端伺服器上與聊天室非常類似的實體。 使用者可以建立新大廳、將資料與大廳連結、以該資料搜索大廳、加入大廳,並與大廳中的其他使用者共用資訊。 每個大廳可以容納多達 250 位使用者,但多數遊戲裡一個大廳通常只會有 2 到最多 16 名玩家。 基於技術層級的配對便是建立在這個系統之上。

Steam 點對點配對 API 是能讓使用者找到其他使用者一起玩遊戲的一組函式。 配對函式都在 ISteamMatchmaking 之中。此 API 包含有各函式之參數的更多詳情。 大廳與玩家或遊戲伺服器一樣,通過獨特的 Steam ID 進行識別。 Steamworks 範例中有一整套關於大廳的可用實作。

配對流程

讓一組玩家共同玩遊戲的常規模型如下:
  1. 玩家在遊戲中選擇想進行哪種多人遊戲,以及多人模式的種類(如規則或情境等等)。
  2. 遊戲會利用大廳搜索 API 尋找規則相同的大廳。
  3. 如果找到大廳,遊戲便會讓玩家加入該大廳;如果找不到,便會建立新大廳。
  4. 使用者在大廳內等待,湊齊夠啟動遊戲的玩家。 大廳成員之間就希望玩的角色或其他的設定,點選玩家設置交流資料。 如果大廳中有需執行的規則(例如只有一個玩家能玩某個角色),則僅有一個大廳所有者能夠決斷。
  5. 大廳的玩家介面可有可無。如果有的話,便可使用大廳資料交流函式在大廳成員間發送聊天消息。 或是使用 Steam 網路連線 API 發送語音資料。
  6. 遊戲一旦就緒,玩家均加入遊戲伺服器,或連接至指定的主持遊戲的玩家處,之後離開大廳。 當所有玩家離開大廳後,大廳自動銷毀。

搜尋大廳

要讓遊戲搜索大廳,您需要呼叫:ISteamMatchmaking::RequestLobbyList
此非同步函式傳回 SteamAPICall_t 控制代碼,可用來追蹤要求的狀態。 依使用者與 Steam 後端的連線狀況,此呼叫可能需要 300 毫秒到 5 秒的時間,20 秒則超時。
LobbyMatchList_t 呼叫結果將傳回結果的數量,然後您可以逐一查看 ISteamMatchmaking::GetLobbyByIndex 獲得所有 ID。
可以傳回多達 50 個結果,但一般來說不會超過幾個。 結果將基於任何臨近位置篩選器,以地理距離為序傳回。 預設是不傳回已滿員的大廳,而距離篩選器則是設定為 k_ELobbyDistanceFilterDefault (附近)。 在呼叫 RequestLobbyList 之前,您需要選擇呼叫以下函式:

加入大廳

如果無法在既有大廳中找到使用者能加入的大廳,通常便需要建立一個大廳。 只需要呼叫
ISteamMatchmaking::CreateLobby ,待其完成。 呼叫結果將告訴您是否成功。如果成功,便會從 LobbyCreated_t 結構中傳回大廳的 SteamID,並可以用來設置該大廳的中繼資料。 您建立大廳之後的第一件事是設置該大廳的資料,以便其他遊戲用戶端能用來進行搜索(參見下文)。

加入大廳

如果您通過搜索或好友找到了合適的大廳,您可以使用 ISteamMatchmaking::JoinLobby,然後等待 LobbyEnter_t 呼叫結果。 一旦進入大廳,您會想要使用大廳資料 API 以獲得大廳詳情,以決定顯示些什麼(若有可顯示的資料)。

使用者加入或離開大廳時,該大廳內的所有成員都會收到 LobbyChatUpdate_t 回呼,包括大廳擁有者。

要逐一查詢目前在大廳中的使用者,使用:

要獲得更多大廳中其他使用者的資訊,您需使用好友 API。如需更多資訊,請見 好友、邀請、大廳

大廳中繼資料

大廳中繼資料允許您設置大廳的任意狀態,包括大廳名稱、當前地圖、遊戲模式、當前遊戲狀態,或其他內容。

使用者將自動獲得他們隸屬的任何大廳的最新大廳資料。 通過搜索結果傳回的大廳,使用者將獲得他們進行搜索當時的大廳資料。 如果為好友大廳,只有在呼叫並成功完成 ISteamMatchmaking::RequestLobbyData 後,才能查看大廳資料 。

如果大廳的資料發生了變動,所有大廳成員將收到 LobbyDataUpdate_t 回呼(此回呼與您獲知 ISteamMatchmaking::RequestLobbyData 呼叫已完成的方式一樣)。

以下的一組函式可以用來取得與設置大廳資料。 只有大廳擁有者能夠設置或刪除大廳資料。

以下函式能讓您逐一查詢中繼資料(通常僅用於除錯目的):

使用以下函式,大廳也允許成員設置屬於自己的中繼資料,供其他成員獲取更新。

大廳內交流

在大廳內發送資訊(聊天訊息、遊戲開始信號等),您需要呼叫 ISteamMatchmaking::SendLobbyChatMsg。這將向大廳內的所有使用者發送一條簡單的二進位消息。 大廳成員需要聽取 ISteamMatchmaking::LobbyChatMsg_t 回呼。 收到回呼後,您可以使用 ISteamMatchmaking::GetLobbyChatEntry 獲取訊息內容。

好友、邀請、大廳

使用好友 API,您可以找到使用者所有好友所處的大廳。
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 為有效大廳,您可加入或使用 RequestLobbyData() 來取得大廳的中繼資料 } }

使用 ISteamMatchmaking::InviteUserToLobby 便可邀請好友至大廳。
該使用者將收到一個帶有連結的聊天對話,以加入該遊戲。 如果該使用者點擊該連結,但當時並未執行該遊戲,將通過以下命令列啟動遊戲:
+connect_lobby <64-bit lobby id>. Be sure your app implements ISteamApps::GetLaunchCommandLine so you can disable the popup warning when launched via a command line.

If the user is already in a game, a ISteamFriends::GameLobbyJoinRequested_t callback will be posted, which contains the Steam ID of the lobby the user wishes to join. It's up to your game to decide to obey it or not.

If you want the user to select from a list of friends to invite to a lobby, you can call ISteamFriends::ActivateGameOverlayInviteDialog.
This will activate the Steam in-game overlay to a dialog designed for inviting friends to the current lobby.

驗證

Any user in a Steam lobby is already fully authenticated with the Steam back-end. There is no need for the game to do any more authentication steps with lobby users, unless it's looking to see if they're VAC banned (see Valve Anti-Cheat Technology). If a user tries to log in from a second location with the same account, their prior login will automatically be removed from any existing lobbies.

清理

Once the game has started, each user can just leave the lobby with:
ISteamMatchmaking::LeaveLobby
Once all the users have left, the lobby is automatically destroyed on the back-end.

大廳提示

  • 一般來說,大廳只有在必要時建立, 例如當使用者邀請好友玩遊戲,或是觸發了需要大廳才能進行的手動操作。
  • 切勿過於頻繁地更新大廳的中繼資料, 只需加入搜尋所需的中繼資料和數值(例如,遊戲類型或遊戲狀態)即可。 您不需要輸入玩家人數,因為大廳搜尋會主動搜索有名額的大廳。
  • 切勿僅為了查詢中繼資料而加入大廳。 所有大廳的中繼資料皆可分別下載,您的遊戲便可利用此資料列出可供使用者選擇的大廳,或者遊戲也可自動決定要加入哪一個搜尋結果。

更多問題?

Ask questions on the Steam Matchmaking & Lobbies discussion forum.