游戏房间概述

游戏房间为多人在线游戏提供实时对战通道：你的服务端创建房间、给玩家签发加入票据，玩家用客户端 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 自行实现客户端

游戏房间概述 ​

谁负责什么 ​

使用条件 ​

基本概念 ​