遊戲房間概述

遊戲房間為多人線上遊戲提供即時對戰通道：你的服務端建立房間、給玩家簽發加入票據，玩家用客戶端 SDK 直連就近的遊戲節點，收發操作和幀；對局結束時，你的服務端收到帶結算結果和每個玩家線上時長的回撥。每個房間最多 10 人，適合對戰、競技、派對這類小房間玩法。

一局遊戲從建房到結束：

bash

# 1. 你的服务端：匹配成功后建房，房间 ID 用你自己的对局 ID
curl -X PUT "$IM_API/$ORG/$APP/game/rooms/rank-8812" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{"max_players":2,"start_mode":"all_ready","tick_rate":30}'

# 2. 你的服务端：给两个玩家签发加入票据，经你的业务接口分别交给他们
curl -X POST "$IM_API/$ORG/$APP/game/rooms/rank-8812/tickets" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{"users":[{"username":"alice"},{"username":"bob"}]}'

# 3. 玩家的客户端：登录 IM 后 im.game.join('rank-8812', { ticket }) 加入，准备、对战

# 4. 你的服务端：对局结束时带上结算结果结束房间，随后收到 game_room.closed 回调
curl -X POST "$IM_API/$ORG/$APP/game/rooms/rank-8812/close" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{"reason":"对局结束","result":{"winner":"alice"}}'

完整的可執行步驟見快速開始。

要做什麼	看哪裡
跑通第一局	快速開始
建房、籤票據、開局、結束、移出玩家	服務端介面
接收房間建立、玩家進出、對局結束	回撥事件
玩家在網頁或 Cocos（Web 平臺）中加入和對戰	Web 客戶端接入
玩家在 Unity 遊戲（iOS、Android、PC）中加入和對戰	Unity 客戶端接入
用沒有 SDK 的引擎（Godot、Unreal、原生 App 等）自己實現客戶端	傳輸協議
在控制台開通、檢視房間和用量，瞭解計費和上限	控制台、計費與限制

誰負責什麼

角色	做什麼	用什麼
你的服務端	匹配、建房、簽發加入票據、判定勝負、結束房間、移出作弊的玩家	服務端介面（App Token），或服務端 SDK 的 `game` 模組
玩家的遊戲客戶端	加入房間、準備、每幀傳送操作、按幀推進遊戲	客戶端 SDK（Web、Unity 已提供，其他引擎可按傳輸協議自行實現，見平臺支援）
遊戲節點（平臺提供）	收集各座位的操作，按固定幀率廣播；斷線重連、補幀、快照	不需要你部署
IM（平臺提供）	校驗票據、分配座位、排程節點、統計線上時長、發回調	不需要你部署

遊戲的規則、畫面和勝負判定都在你的客戶端和服務端裡，遊戲節點只轉發資料，不理解你的遊戲。

使用條件

平臺開放了遊戲房間，並且沒有單獨關閉你的應用；
應用的套餐包含「遊戲房間」；
應用狀態正常；
至少有一個可用的大區（有可排程的遊戲節點）。

在控制台應用的「遊戲房間」頁可以看到是否滿足、缺哪一項，見控制台。

基本概念

房間：你的服務端用自己的房間 ID（1–64 位字母、數字、_、-）建立，一般直接用對局 ID。同一個 ID 同參數重複建立得到同一個房間，所以匹配服務超時重試不會建出兩個房間。房間結束後這個 ID 不能再用。

座位：每個房間有 max_players 個座位（1–10），編號從 0 開始。籤票據時可以指定座位，不指定時玩家加入時分到最小的空座位。

加入票據：你的服務端為某個使用者簽發、交給這個使用者的一次性憑證，預設 120 秒有效（30–600 秒）。同一使用者再籤一次，之前沒用的票據作廢。access_mode 為 open 的房間不需要票據，本應用的任何登入使用者都能加入。

同步方式：

`sync_mode`	適合	節點做什麼
`frame`（預設）	動作、格鬥、MOBA 這類需要所有人畫面一致的遊戲	每秒 `tick_rate` 幀（10、15、20、30、60，預設 30），每幀把各座位這一幀的操作打包廣播；客戶端按幀推進同一套邏輯
`relay`	棋牌、回合制、派對小遊戲	不推進幀，只轉發玩家之間的自定義訊息

開局方式：

`start_mode`	什麼時候開局
`auto`（預設）	第一個玩家連上游戲節點就開局
`all_ready`	已連上、未離開的玩家全部呼叫 `ready()` 後開局。不等座位坐滿：人沒到齊時先不要讓玩家準備
`manual`	你的服務端呼叫開局介面

斷線重連：玩家斷線後在 reconnect_window_seconds（預設 60，0–300）內回來，回到原來的座位，缺的幀自動補齊；超過視窗算離開。SDK 自動重連，你不需要寫程式碼。

房間的狀態

`status`	含義
`open`	已建立，等待開局；玩家可以加入
`playing`	對局中；玩家仍然可以加入空座位
`closing`	正在結束：已通知遊戲節點，玩家收到結束通知
`closed`	已結束，`close_reason` 為結束原因

房間會在以下情況自動結束，不需要你呼叫介面：

`close_reason`	什麼時候
`closed_by_server`	你的服務端呼叫了結束介面
`closed_by_console`	在控制台結束
`closed_by_platform`	平臺運營結束
`expired`	超過 `max_duration_seconds`（預設 3600 秒）
`empty`	所有玩家都離開或斷線，超過重連視窗後再過 60 秒
`node_lost`	遊戲節點故障，失去聯絡
`node_draining`	遊戲節點下線維護

無論哪種原因，房間結束時都會發出 game_room.closed 回撥。

平臺支援

平臺	狀態
Web（TypeScript，`@deeprespond/im-web` 1.1.0 起，含 React、Vue 繫結）	已提供，見 Web 客戶端接入。瀏覽器使用 WebSocket
Cocos Creator（Web 平臺）	使用 Web SDK
Unity（C#，iOS / Android / PC，`cn.deeprespond.im.game` 1.0.0）	已提供，見 Unity 客戶端接入。先用 UDP，連不上時改用 WebSocket
微信小遊戲	開發中
Android、iOS 原生、Flutter	規劃中
服務端 SDK：Go、Node.js、Python、Java	已提供 `game` 模組，見服務端介面
其他引擎和語言（Godot、Unreal、原生 App 等）	按傳輸協議用 WebSocket 自行實現客戶端

遊戲房間概述 ​

誰負責什麼 ​

使用條件 ​

基本概念 ​