房间管理相关接口

最近更新时间:2019-06-21 20:07:03

roomInfo

对象描述

房间信息。

参数描述

说明:

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

networkState

对象描述

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

参数描述

说明:

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

initRoom

接口描述

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

参数描述

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

说明:

  • initRoom 会更新 Room 实例的 roomInfo,接受 MGOBE.types.RoomInfo 或 { id: string; } 类型的参数。
  • 如果不传参数,该方法将清空 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);

isInRoom

接口描述

判断玩家是否在该 Room 实例中。

参数描述

说明:

isInRoom 方法本质上是检查 roomInfo.playerList 中是否存在玩家 ID。如果存在,就返回 true。

返回值说明

返回值类型为 boolean,表示玩家是否在该room实例中。

使用示例

    const room = new Room();
    room.isInRoom(); // 返回 false,因为 room 还是一个空房间

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 通过 init 方法初始化 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));

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);
    };