房间管理相关接口

最近更新时间:2020-07-03 11:10:09

roomInfo 属性

对象描述

房间信息。

参数描述

说明:

roomInfo 为 Room 实例的属性,类型为 MGOBE.types.RoomInfo,调用 Room 相关的接口会导致该属性发生变化。

使用示例

// 打印 Room 实例的 roomInfo 属性
// 如需更新该属性,可以使用 getRoomDetail 方法
console.log(room.roomInfo);

networkState 属性

对象描述

该属性为只读属性,用于获取客户端本地 SDK 网络状态。

参数描述

说明:

  • 该属性类型为 { COMMON: boolean, RELAY: boolean } 。COMMON 表示房间网络状态;RELAY 表示帧同步网络状态。为 true 时表示网络已连接,为 false 时表示网络未连接。
  • 该网络状态与玩家信息中的网络状态(Player.commonNetworkState/Player.relayNetworkState)概念不同,前者表示本地 socket 状态,后者表示玩家在 MGOBE 后台中的状态。
  • 本地 socket 网络状态变化时,onUpdate 将被触发。

返回值说明

使用示例

// 打印 Room 实例的 networkState 属性
console.log(room.networkState);

// 判断本地连接是否正常
if (room.networkState.COMMON) {
    console.log("连接正常");
}

initRoom

接口描述

初始化 Room 实例的房间信息,即更新 roomInfo 属性。

参数描述

参数名 类型/值 描述
roomInfo MGOBE.types.RoomInfo 或 { id: string } 初始化参数,id表示房间id
说明:

  • initRoom 会更新 Room 实例的 roomInfo,接受 MGOBE.types.RoomInfo 或 { id: string; } 类型的参数。
  • 如果参数为 MGOBE.types.RoomInfo 类型,SDK 将自动更新 WebSocket 连接。如果参数为 { id: string; } 类型,需要调用 getRoomDetail 或 joinRoom 方法,才能更新 WebSocket 连接,否则可能不能及时收到房间广播。
  • 如果不传参数,该方法将清空 Room 实例的 roomInfo 属性,此时调用 getRoomDetail 方法将查询玩家所在的房间。
  • 当玩家需要加入指定 ID 房间时,需要使用该接口初始化 Room 实例的 roomInfo 属性,然后才能通过调用 joinRoom 方法加入该 Room 实例所代表的房间。

返回值说明

使用示例

const room = new Room();

// 示例1:不传 roomInfo 参数
// 该 Room 实例房间信息被清除,room.getRoomDetail 将查询玩家所在的房间
room.initRoom();

// 示例2:指定房间 ID
// 该 Room 实例代表 ID 为 xxx 的房间,room.getRoomDetail 将查询 xxx 房间信息
const roomInfo = { id: "xxx" };
room.initRoom(roomInfo);

onUpdate

接口描述

房间信息更新回调接口。

参数描述

参数名 类型/值 描述 可选
room Room 更新的 Room 实例
说明:

  • onUpdate 表明 Room 实例的 roomInfo 信息发生变化,这种变化原因包括各种房间操作、房间广播、本地网络状态变化等。
  • 开发者可以在该接口中更新游戏画面,或者使用 networkState 属性判断网络状态。

返回值说明

使用示例

room.onUpdate = (_) => {
    console.log(_ === room); // true, 参数 _ 等于 room
    console.log("房间信息更新", room.roomInfo);
};

createRoom

接口描述

创建房间。

参数描述

参数名 类型/值 描述
createRoomPara MGOBE.types.CreateRoomPara 创建房间参数
callback MGOBE.types.ReqCallback<MGOBE.types.CreateRoomRsp> 响应回调函数
说明:

  • createRoom 调用结果将在 callback 中异步返回。操作成功后,roomInfo 属性将更新。
  • 创建房间成功后,玩家自动进入该房间,因此无法继续调用 joinRoom、matchPlayers 等方法,可以利用房间 ID 邀请其他玩家进入该房间。

返回值说明

使用示例

const playerInfo = {
    name: "Tom",
    customPlayerStatus: 1,
    customProfile: "https://xxx.com/icon.png",
};

const createRoomPara = {
    roomName: "房间名",
    maxPlayers: 4,
    roomType: "2V2",
    isPrivate: false,
    customProperties: "WAIT",
    playerInfo,
};

room.createRoom(createRoomPara, event => console.log(event));

createTeamRoom

接口描述

创建团队房间。

参数描述

参数名 类型/值 描述
createTeamRoomPara MGOBE.types.CreateTeamRoomPara 创建团队房间参数
callback MGOBE.types.ReqCallback<MGOBE.types.CreateRoomRsp> 响应回调函数
说明:

  • createTeamRoom 调用结果将在 callback 中异步返回。操作成功后,roomInfo 属性将更新。
  • 创建房间成功后,玩家自动进入该房间,因此无法继续调用 joinRoom、matchPlayers 等方法。
  • 参数中的“房间最大玩家数量”要求能被“队伍数量”整除,创建成功后每个队伍的“队伍最小人数”为1,“队伍最大人数”为整除结果。

返回值说明

使用示例

const playerInfo = {
    name: "Tom",
    customPlayerStatus: 1,
    customProfile: "https://xxx.com/icon.png",
};

const createTeamRoomPara = {
    roomName: "房间名",
    maxPlayers: 4,
    roomType: "2V2",
    isPrivate: false,
    customProperties: "WAIT",
    playerInfo,
    teamNumber: 2,
};

room.createTeamRoom(createTeamRoomPara, event => console.log(event));

joinRoom

接口描述

加入房间。

参数描述

参数名 类型/值 描述
joinRoomPara MGOBE.types.JoinRoomPara 加入房间参数
callback MGOBE.types.ReqCallback<MGOBE.types.JoinRoomRsp> 响应回调函数
说明:

  • joinRoom 调用结果将在 callback 中异步返回。
  • 该接口加入的房间是 Room 实例所代表的房间,如果该 Room 实例的 roomInfo 不存在 roomId,则需要使用 roomId 通过 initRoom 方法初始化 Room 实例。
  • 加房成功后,房间内全部成员(包含调用者)都会收到一条玩家加入房间广播 onJoinRoom,roomInfo 属性将更新。

返回值说明

使用示例

const playerInfo = {
    name: "Tom",
    customPlayerStatus: 1,
    customProfile: "https://xxx.com/icon.png",
};

const joinRoomPara = {
    playerInfo,
};

// 示例1:加入指定 ID 的房间
const room1 = new MGOBE.Room();
room1.initRoom({ id: "xxx" });
room1.joinRoom(joinRoomPara, event => console.log(event));

// 示例2:加入没有房间信息的房间
const room2 = new MGOBE.Room();
// 加房失败,找不到房间信息
room2.joinRoom(joinRoomPara, event => console.log(event));

joinTeamRoom

接口描述

加入团队房间。

参数描述

参数名 类型/值 描述
joinTeamRoomPara MGOBE.types.JoinTeamRoomPara 加入团队房间参数
callback MGOBE.types.ReqCallback<MGOBE.types.JoinRoomRsp> 响应回调函数
说明:

  • joinTeamRoom 调用结果将在 callback 中异步返回。
  • 与 joinRoom 类似,该接口加入的房间是 Room 实例所代表的房间。teamId 为 roomInfo.teamList 中定义的队伍 ID。

返回值说明

使用示例

const playerInfo = {
    name: "Tom",
    customPlayerStatus: 1,
    customProfile: "https://xxx.com/icon.png",
};

const joinTeamRoomPara = {
    playerInfo,
    teamId: "1",
};

room.joinTeamRoom(joinTeamRoomPara, event => console.log(event));

leaveRoom

接口描述

退出房间。

参数描述

参数名 类型/值 描述
para object 预留参数,传{}即可
callback MGOBE.types.ReqCallback<MGOBE.types.LeaveRoomRsp> 响应回调函数
说明:

  • leaveRoom 调用结果将在 callback 中异步返回。退出成功后,房间内剩余成员(不含调用者)都会收到一条玩家退出房间广播 onLeaveRoom,roomInfo 属性将更新,roomInfo.playerList 中将没有该玩家信息。
  • 退房后,如果房间内还剩下其他玩家,则该 room 实例仍然代表退房前的房间,可以继续调用 room.initRoom() 清除房间信息。

返回值说明

使用示例

room.leaveRoom({}, event => {
    if (event.code === 0) {
        // 退房成功
        console.log("退房成功", room.roomInfo.id);
        // 可以使用 initRoom 清除 roomInfo
        room.initRoom();
    }
});

dismissRoom

接口描述

解散房间。

参数描述

参数名 类型/值 描述
para object 预留参数,传{}即可
callback MGOBE.types.ReqCallback<MGOBE.types.DismissRoomRsp> 响应回调函数
说明:

  • dismissRoom 调用结果将在 callback 中异步返回。解散成功后,房间内全部成员(不含调用者)都会收到一条解散房间广播 onDismissRoom,roomInfo 属性将更新。
  • 只有房主有权限解散房间。

返回值说明

使用示例

room.dismissRoom({}, event => {
    if (event.code === 0) {
        console.log("解散成功");
    }
});

changeRoom

接口描述

修改房间信息。

参数描述

参数名 类型/值 描述
changeRoomPara MGOBE.types.ChangeRoomPara 修改房间参数
callback MGOBE.types.ReqCallback<MGOBE.types.ChangeRoomRsp> 响应回调函数
说明:

  • changeRoom 调用结果将在 callback 中异步返回。修改成功后,房间内全部成员都会收到一条修改房间广播 onChangeRoom,roomInfo 属性将更新。
  • 只有房主有权限修改房间

返回值说明

使用示例

const changeRoomPara = {
    roomName: "房间名",
    owner: "xxxxxx",
    isPrivate: false,
    customProperties: "xxxxxx",
};

room.changeRoom(changeRoomPara, event => console.log(event));

changeCustomPlayerStatus

接口描述

修改玩家自定义状态。

参数描述

参数名 类型/值 描述
changeCustomPlayerStatusPara MGOBE.types.ChangeCustomPlayerStatusPara 修改玩家状态参数
callback MGOBE.types.ReqCallback<MGOBE.types.ChangeCustomPlayerStatusRsp> 响应回调函数
说明:

  • 修改玩家状态是修改 PlayerInfo 中的 customPlayerStatus 字段,玩家的状态由开发者自定义。
  • 修改成功后,房间内全部成员都会收到一条修改玩家状态广播 onChangeCustomPlayerStatus,roomInfo 属性将更新。
  • 每个玩家只能修改自己的状态,调用结果将在 callback 中异步返回。

返回值说明

使用示例

const changeCustomPlayerStatusPara = {
    customPlayerStatus: 2,
};

room.changeCustomPlayerStatus(changeCustomPlayerStatusPara, event => console.log(event));

removePlayer

接口描述

移除房间内玩家。

参数描述

参数名 类型/值 描述
removePlayerPara MGOBE.types.RemovePlayerPara 移除房间内玩家参数
callback MGOBE.types.ReqCallback<MGOBE.types.RemovePlayerRsp> 响应回调函数
说明:

  • 调用结果将在 callback 中异步返回。移除玩家成功后,房间内全部成员都会收到一条移除玩家广播 onRemovePlayer,roomInfo 属性将更新。
  • 只有房主有权限移除其他玩家

返回值说明

使用示例

const removePlayerPara = {
    removePlayerId: "xxxxxx",
};

room.removePlayer(removePlayerPara, event => console.log(event));

getRoomDetail

接口描述

获取 Room 实例的房间信息。

参数描述

参数名 类型/值 描述
callback MGOBE.types.ReqCallback<MGOBE.types.GetRoomByRoomIdRsp> 响应回调函数
说明:

  • 该接口获取的是 Room 实例的房间信息,调用结果将在 callback 中异步返回。
  • 如果该 Room 实例中的 roomInfo 属性没有 ID,该接口将查询玩家所在的房间。
  • 如果 roomInfo 属性含有 ID,则查询该 ID 对应的房间信息。
  • 操作成功后,roomInfo 属性将更新。
  • 如果需要获取指定 ID 的房间信息,可以使用 getRoomByRoomId 方法。

返回值说明

使用示例

// 示例1:查询room实例的信息
room.getRoomDetail(event => {
    if (event.code === 0) {
        console.log("房间名", event.data.roomInfo.name);
    }
});

// 示例2:查询玩家所在房间信息
room.initRoom();// 或者 room.initRoom({ id: "" });
room.getRoomDetail(event => {
    if (event.code === 0) {
        console.log("房间名", event.data.roomInfo.name);
    }
});

getRoomByRoomId

接口描述

根据房间 ID 获取房间。

参数描述

参数名 类型/值 描述
getRoomByRoomIdPara MGOBE.types.GetRoomByRoomIdPara 获取房间参数
callback MGOBE.types.ReqCallback<MGOBE.types.GetRoomByRoomIdRsp> 响应回调函数
说明:

  • 调用结果将在 callback 中异步返回。
  • 该接口为 Room 的静态方法,只能通过 Room.getRoomByRoomId 方式调用,Room 实例无法直接访问该方法。
  • 如果参数中的 roomId 为空字符串,将查询玩家所在的房间。

返回值说明

使用示例

// 示例1:查询指定房间id的信息
const getRoomByRoomIdPara1 = {
    roomId: "800000",
};
MGOBE.Room.getRoomByRoomId(getRoomByRoomIdPara1, event => console.log(event));

// 示例2:查询玩家所在房间信息
const getRoomByRoomIdPara2 = {
    roomId: "",
};
MGOBE.Room.getRoomByRoomId(getRoomByRoomIdPara2, event => console.log(event));

getMyRoom

接口描述

查询玩家所在的房间信息。

参数描述

参数名 类型/值 描述
callback MGOBE.types.ReqCallback<MGOBE.types.GetRoomByRoomIdRsp> 响应回调函数
说明:

  • 调用结果将在 callback 中异步返回。
  • 该接口为 Room 的静态方法,只能通过 Room.getMyRoom 方式调用,Room 实例无法直接访问该方法。

返回值说明

使用示例

MGOBE.Room.getMyRoom(event => {
    if (event.code === 0) {
        console.log("玩家在房间内", event.data.roomInfo);
        const room = new MGOBE.Room(event.data.roomInfo);
    }
});

getRoomList

接口描述

获取房间列表。

参数描述

参数名 类型/值 描述
getRoomListPara MGOBE.types.GetRoomListPara 获取房间列表参数
callback MGOBE.types.ReqCallback<MGOBE.types.GetRoomListRsp> 响应回调函数
说明:

  • 调用结果将在 callback 中异步返回。
  • 该接口为 Room 的静态方法,只能通过 Room.getRoomList 方式调用,Room 实例无法直接访问该方法。

返回值说明

使用示例

const getRoomListPara = {
    pageNo: 1,
    pageSize: 10,
};

// 不要使用 room.getRoomList
// 直接使用 Room 对象
MGOBE.Room.getRoomList(getRoomListPara, event => console.log(event));

onJoinRoom

接口描述

新玩家加入房间广播回调接口。

参数描述

参数名 类型/值 描述
event MGOBE.types.BroadcastEvent<MGOBE.types.JoinRoomBst> 回调参数
说明:

onJoinRoom 广播表示该房间有新玩家加入。房间内全部成员都会收到该广播。

返回值说明

使用示例

room.onJoinRoom = event => console.log("新玩家加入", event.data.joinPlayerId);

onLeaveRoom

接口描述

玩家退出房间广播回调接口。

参数描述

参数名 类型/值 描述
event MGOBE.types.BroadcastEvent<MGOBE.types.LeaveRoomBst> 回调参数
说明:

onLeaveRoom 广播表示该房间有玩家退出。房间内全部成员都会收到该广播。

返回值说明

使用示例

room.onLeaveRoom = event => console.log("玩家退出", event.data.leavePlayerId);

onDismissRoom

接口描述

房间被解散广播回调接口。

参数描述

参数名 类型/值 描述
event MGOBE.types.BroadcastEvent<MGOBE.types.DismissRoomBst> 回调参数
说明:

onDismissRoom 广播表示房主解散了该房间。房间内全部成员都会收到该广播。

返回值说明

使用示例

room.onDismissRoom = event => console.log("房间已被房主解散");

onChangeRoom

接口描述

房主修改房间信息广播回调接口。

参数描述

参数名 类型/值 描述
event MGOBE.types.BroadcastEvent<MGOBE.types.ChangeRoomBst> 回调参数
说明:

onChangeRoom 广播表示房主修改了该房间属性。房间内全部成员都会收到该广播。

返回值说明

使用示例

room.onChangeRoom = event => console.log("房间属性变更", event.data.roomInfo);

onRemovePlayer

接口描述

房间内玩家被移除广播回调接口。

参数描述

参数名 类型/值 描述
event MGOBE.types.BroadcastEvent<MGOBE.types.RemovePlayerBst> 回调参数
说明:

onRemovePlayer 广播表示有玩家被房主移除。房间内全部成员都会收到该广播。

返回值说明

使用示例

room.onRemovePlayer = event => console.log("玩家被移除", event.data.removePlayerId);

onChangePlayerNetworkState

接口描述

房间内玩家网络状态变化广播回调接口。

参数描述

参数名 类型/值 描述
event MGOBE.types.BroadcastEvent<MGOBE.types.ChangePlayerNetworkStateBst> 回调参数
说明:

  • onChangePlayerNetworkState 广播表示 ID 为 changePlayerId 的玩家网络状态发生变化。
  • 玩家在房间中、帧同步中的网络变化都会触发该广播,因此 networkState 将有四种情况,分别表示房间中上下线、帧同步中上下线。

返回值说明

使用示例

room.onChangePlayerNetworkState = event => {
    if (event.data.networkState === MGOBE.ENUM.NetworkState.COMMON_OFFLINE)
        console.log("玩家下线");
};

onChangeCustomPlayerStatus

接口描述

玩家自定义状态变化广播回调接口。

参数描述

参数名 类型/值 描述
event MGOBE.types.BroadcastEvent<MGOBE.types.ChangeCustomPlayerStatusBst> 回调参数
说明:

onChangeCustomPlayerStatus 广播表示房间内 ID 为 changePlayerId 的玩家状态发生变化。玩家状态由开发者自定义。

返回值说明

使用示例

room.onChangeCustomPlayerStatus = event => {
    console.log("玩家状态变化", event.data.changePlayerId);
};
目录