文档

# 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);
1
2
3
4
5
6
7
8
9
10

# isInRoom

# 接口描述

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

# 参数描述

无

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

# 返回值说明

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

# 使用示例

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

# onUpdate

# 接口描述

房间信息更新回调接口。

# 参数描述

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

# 返回值说明

无

# 使用示例

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

# 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));
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 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));
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 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));
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 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));
1
2
3
4
5
6
7
8
9
10
11
12

# 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();
        }
    });
1
2
3
4
5
6
7
8

# dismissRoom

# 接口描述

解散房间。

# 参数描述

参数名 类型/值 描述
para object 预留参数，传{}即可
callback MGOBE.types.ReqCallback<MGOBE.types.DismissRoomRsp> 响应回调函数
  • dismissRoom 调用结果将在 callback 中异步返回。解散成功后，房间内全部成员都会收到一条
  • 广播 onDismissRoom，roomInfo 属性将更新。
  • 只有房主有权限解散房间

# 返回值说明

无

# 使用示例

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

# 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));
1
2
3
4
5
6
7
8

# 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));
1
2
3
4
5

# 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));
1
2
3
4
5

# 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);
        }
    });
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 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));
1
2
3
4
5
6
7
8
9
10
11

# 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));
1
2
3
4
5
6
7
8

# onJoinRoom

# 接口描述

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

# 参数描述

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

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

# 返回值说明

无

# 使用示例

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

# onLeaveRoom

# 接口描述

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

# 参数描述

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

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

# 返回值说明

无

# 使用示例

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

# onDismissRoom

# 接口描述

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

# 参数描述

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

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

# 返回值说明

无

# 使用示例

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

# onChangeRoom

# 接口描述

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

# 参数描述

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

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

# 返回值说明

无

# 使用示例

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

# onRemovePlayer

# 接口描述

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

# 参数描述

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

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

# 返回值说明

无

# 使用示例

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

# 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("玩家下线");
    };
1
2
3
4

# onChangeCustomPlayerStatus

# 接口描述

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

# 参数描述

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

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

# 返回值说明

无

# 使用示例

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

← 匹配 →