Steamworks 文獻庫
Steam 遊戲配對與大廳

概覽

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>. 請確保您的應用程式實作了 ISteamApps::GetLaunchCommandLine,以停用透過命令列啟動時的彈出式警告。

如果使用者已經在遊戲中,將送出 ISteamFriends::GameLobbyJoinRequested_t 回呼,當中包含使用者希望加入的大廳的 Steam ID。 這將由您的遊戲決定是否接受。

如果您希望使用者從好友名單選擇邀請加入大廳的玩家,您可以呼叫 ISteamFriends::ActivateGameOverlayInviteDialog
這將啟動 Steam 遊戲中的內嵌介面,叫出專門用於邀請好友至目前大廳的對話方塊。

驗證

Steam 大廳中所有使用者都已經過 Steam 後端完全驗證。 遊戲無須再對大廳使用者進行任何驗證步驟,除非是為了檢查使用者是否遭 VAC 封鎖(見 Valve 反作弊技術)。 如果使用者嘗試使用同一個帳戶從另一個地點登入,則先前的登入階段將自動從任何既有大廳移除。

清理

遊戲開始後,各使用者利用此函式即可離開大廳:
ISteamMatchmaking::LeaveLobby
所有使用者皆離開後,大廳將從後端自動銷毀。

大廳提示

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

更多問題?

請至 Steam 遊戲配對與大廳討論區提問。