发现问题,我要反馈

组队匹配

组队示例

当前页面是组队相关的API说明。我们同样是以 MatchvsEngine 和 MatchvsResponse 的对象 engine 和 response 来说明。

Response 是发起方在调用接口后,自己收到的回调;Notify是发起方调用接口后,小队其他成员收到的通知。

组队匹配信息可以使用getRoomDetail 接口查看房间是否有组队。请求接口返回码可以参考 错误码说明

名词概念

对函数和回调函数中函数做统一说明

属性 类型 描述 示例值
team/teaminfo object 队伍信息
team.teamID string 队伍ID "131113213211323121231"
team.password string 队伍权限值 1ab2
team.capacity number 队伍人数容量 3
team.mode number 组队模式,匹配条件 由开发者自己定义,作为
team.owner number 队长 123456
team.visibility number 0-不可见 1-可见 1
status number 加入队伍状态值 200
user object 玩家 {userID:""}
userList array 队伍玩家列表 [{userID:""},{}]
userID number 玩家ID 2356
userProfile string 玩家自定义信息 如玩家头像

函数返回码

返回码 说明
0 接口调用成功
-2 未初始化
-3 正在初始化
-4 未登录
-5 正在登录
-7 正在创建房间,或者正在加入游戏房间
-6 不在观战房间
-10 正在离开房间
-11 正在登出
-12 正在加入观战房间
-13 队伍正在匹配中

创建队伍

组队匹配需要调用这个接口先创建一支队伍。

  • 请求接口:createTeam
  • 回调接口:createTeamResponse

开发者可以创建一个带密码的小队,并指定小队的人数上限(如5v5,则小队人数上限为5,玩家可以再邀请4个好友一起组成小队)。

可以定义组队模式,比如基础模式,进阶模式等。在创建小队时,设置用户信息,之后有玩家加入小队时,可以直接获取到该用户信息。

玩家A创建小队成功后,A会收到小队ID,将小队ID分享给好友,好友即可通过ID+密码进入小队。(不需要密码可以全部默认设置为同一个值。)

每个小队会有一个队长,一般是创建小队的那个玩家,如果队长掉线/离开小队,则队长会随机转移给小队内其他玩家。新的队长信息可以在 leaveTeamNotify里获取。

createTeam


    /**
     * 创建组队
     * @param {MVS.MsCreateTeamInfo} teaminfo
     * @returns {number}
     * @memberof MatchvsEngine
     */
    createTeam(teaminfo: MVS.MsCreateTeamInfo):number

createTeamResponse


    /**
     * 创建组队同步放回信息
     * @param {*} rps
     * @param {number} rps.status
     * @param {string} rps.teamID
     * @param {number} rps.owner
     * @memberof MatchvsResponse
     */
    createTeamResponse(rps:any):void

示例代码

var req = {
    password:"ok",
    capacity:2,
    mode:0,
    visibility:1,
    userProfile:"temamode"
};
engine.createTeam(req)
response.createTeamResponse = function(rsp){
    console.log("[RSP]createTeamResponse:"+JSON.stringify(rsp));
};

加入队伍

要邀请好友加入队伍,使用 createTeam 接口创建的队伍信息,调用 joinTeam 接口就可以加入指定的队伍。队伍中其他玩家会收到 joinTeamNotify 接口的通知。

  • 请求接口:joinTeam
  • 回调接口:joinTeamResponse, joinTeamNotify

加入小队时,可以携带头像、昵称等信息。

队员加入后,会收到已在小队里的所有成员列表信息以及小队信息。其他玩家会收到该队员加入的通知。

joinTeam

    /**
     * 加入组队队伍,队伍必须是由 createTeam 接口创建的
     * @param {MVS.MsJoinTeamInfo} teaminfo
     * @returns {number}
     * @memberof MatchvsEngine
     */
    joinTeam(teaminfo:MVS.MsJoinTeamInfo):number

joinTeamResponse

调用加入队伍接口,自己会收到这个接口通知

    /**
     * 加入队伍返回信息
     * @param {*} rsp
     * @param {*} rsp.team //队伍信息
     * @param {number} rsp.team.teamID 队伍号
     * @param {string} rsp.team.password 队伍验证信息
     * @param {number} rsp.team.capacity 队伍人数容量
     * @param {number} rsp.team.mode 模式-开发者自定义的值
     * @param {number} rsp.team.owner 队长
     * @param {number} rsp.status 加入队伍状态值
     * @param {Array<any>} rsp.userList [{userID:, userProfile:,}]
     * @memberof MatchvsResponse
     */
    joinTeamResponse(rsp:any):void

joinTeamNotify

有人加入队伍,队伍中其他玩家会收到 joinTeamNotify 接口的通知

    /**
     *
     * @param {string} notify.teamID
     * @param {number} notify.status
     * @param {number} notify.userID
     * @param {String} notify.teamProperty
     */
    leaveTeamNotify (notify):void

示例代码

response.joinTeamResponse = function(rsp){
    console.log("[RSP]joinTeamResponse:"+JSON.stringify(rsp));
};

response.joinTeamNotify = function(rsp){
    console.log("[RSP]joinTeamNotify:"+JSON.stringify(rsp));
};
var req ={
    teamID: PutIn("teamID"),
    password: PutIn("teamPwd"),
    userProfile:"i come team 哈哈"
};
console.log("[REQ]STJoinTeam:"+engine.joinTeam(req));

离开队伍

在队伍中如果要离开队伍就调用 leaveTeam 接口,其他人会收到 leaveTeamNotify 接口通知,自己收到 leaveTeamResponse 通知

  • 请求接口:leaveTeam
  • 回调接口:leaveTeamResponse, leaveTeamNotify

leaveTeam

    /**
     * 离开组队队伍
     * @returns {number}
     * @memberof MatchvsEngine
     */
    leaveTeam():number

leaveTeamResponse


    /**
     * 离开队伍回调信息
     * @param {*} rsp
     * @param {number} rsp.userID 离开者ID
     * @param {number} rsp.teamID 离开的队伍号
     * @param {number} rsp.status 状态值 200 成功
     * @memberof MatchvsResponse
     */
    leaveTeamResponse(rsp:any):void

leaveTeamNotify


    /**
     * 有人离开队伍,其他人收到的通知接口
     * @param {*} notify
     * @param {number} notify.teamID 离开的队伍
     * @param {number} notify.userID 离开者
     * @param {number} notify.owner 队长
     * @param {String} notify.teamProperty 队伍属性
     * @memberof MatchvsResponse
     */
    leaveTeamNotify(notify:any):void

示例代码

response.leaveTeamResponse = function(rsp){
    console.log("[RSP]leaveTeamResponse:"+JSON.stringify(rsp));
};
response.leaveTeamNotify = function(notify){
    console.log("[RSP]leaveTeamNotify:"+JSON.stringify(notify));
};
console.log("[REQ]STLeaveTeam:"+engine.leaveTeam());

##队伍与队伍匹配

加入了队伍后,可以发起队伍匹配,队伍匹配的队伍成员数和队伍数量可在调用匹配的时候调用,如需要做5v5对战,则队伍成员数设置5,队伍数量设置2。队伍匹配调用 teamMatch 接口。teamMatch 接口可以由队伍中任意一个人调用。

  • 请求接口:teamMatch
  • 回调接口:teamMatchResponse, teamMatchStartNotify, teamMatchResultNotify

说明

匹配规则:你可以为每个小队设置一个权值,这个权值代表该小队的实力水平,如段位等级为3。然后设置小队实力的匹配范围,如2,则在匹配时,会为该小队寻找 3±2 段位(即1--5)的其他小队进行匹配。如果是不同模式,可以用 mode 区分,相同 mode 的小队才会被匹配到一起。匹配时会以modecond为匹配依据。

权重规则weightRule 用于小队合成大队后计算大队的段位,目前默认为 0 ,即求平均。如,team1 段位为 2,team2 段位为4,则合成大队后,大队权重为平均值 3 。如相应支持更多的合成后计算规则,可以进入技术支持群QQ:450335262 进行反馈。

匹配时,会自动根据设置的队伍数量及每队人数进行小队间的组合,最终会尽量保障两边队伍段位均衡。如5v5,team1(playerA)、team2(player B C D E)、team3(player F G )、team4(player H I J)发起匹配,最终结果可能是 A B C D E ,F G H I J 两队。

你可以设置一个等待超时时间,如10秒,如果10秒之内未匹配到合适的其他小队,会返回匹配失败。

发起匹配后,其他队员会收到开始匹配的通知,匹配成功/失败的通知也会相继收到。

小队匹配支持人满和人不满模式,人满即 5v5 ,则最终匹配结果肯定是 5v5 ,否则会匹配失败;人不满即 5v5 ,在超时之前可能只能匹配到 2v3 ,则依然匹配成功,你可以再自行添加机器人。

teamMatch

    /**
     * 加入的队伍之后,可以由队伍中的任何一个人发起队伍匹配
     * @param {MVS.MsTeamMatchInfo} matchInfo
     * @returns {number}
     * @memberof MatchvsEngine
     */
    teamMatch(matchInfo:MVS.MsTeamMatchInfo):number

参数 info 属性

info 是 MVS.MsTeamMatchInfo 类型。

属性 类型 描述 示例值
roomName string 房间名称 “matchvs”
maxPlayer number 房间最大人数 10
canWatch number 是否可以观战 1-可以观战 02不可以观战。 1
mode number 玩家自定义数据 0
visibility number 房间是否可见(是否可以被getRoomListEx查看到)。0-不可见 1- 可见 1
roomProperty string 房间自定义信息 "房间信息"
watchSet MVS.MsWatchSet 观战设置,canWatch 设置为1的时候有效
cond MVS.MsTeamMatchCond 匹配设置

参数 MVS.MsWatchSet属性

属性 类型 描述 示例值
cacheMS number 缓存多久的数据 6*1000(6分钟)
maxWatch number 最大人数 3
delayMS number 观看延迟多久后的数据 2000
persistent boolean 是否持久缓存 false

参数 MVS.MsTeamMatchCond属性

属性 类型 描述 示例值
teamNum number 需要的队伍的数量 2
teamMemberNum number 每支队伍的队员数 5
timeout number 匹配的超时时间,指匹配多久就视为超时,没有匹配到。接口teamMatchResultNotify会报422错误 20
weight number 权值 10
weightRange number 匹配范围 5
weightRule number 匹配规则, 默认是0(求平均) 0
full number 是否人满匹配,0-人不满也可以匹配,1-人满匹配 (人不满匹配不到会超时报422错误码) 0

teamMatchResponse

发送匹配的人会收到这个接口的回调,告诉自己队伍正在匹配中。其他人会收到 teamMatchStartNotify 的通知。

    /**
     * 队伍中发起匹配者会收到这个回调,表示正在匹配中
     * @param {*} rsp
     * @param {number} rsp.status 匹配状态
     * @memberof MatchvsResponse
     */
    teamMatchResponse(rsp:any):void

teamMatchStartNotify

在队伍中有人调用了匹配接口,其他人就会收到这个接口的通知,队伍开始进入匹配啦。

    /**
     * 队伍中如果有人发起匹配,其他人会收到这个开启匹配的通知
     * @param {*} rsp
     * @param {*} rsp.teamID 队伍号
     * @param {*} rsp.userID 发起匹配者ID
     * @memberof MatchvsResponse
     */
    teamMatchStartNotify(rsp:any):void

teamMatchResultNotify

队伍匹配结果通过这个接口通知队伍中的所有人。注意:匹配成功但并不是加入了房间,收到匹配成功后,马上给其他玩家发送消息是不可行的。匹配成功后SDK会自动处理加入房间的逻辑,开发者不用额外的调用加入房间接口,只需要处理,joinRoomResponse 接口和 joinRoomNotify 接口即可,通过这个两个接口判断是否所有人都加入了房间,如果需要检查谁掉线了可以处理 networkStateNotify 接口。

    /**
     * 发起匹配后,队伍中所有人都会收到匹配结果通知
     * @param {*} rsp
     * @param {number} rsp.status 配置的状态,200 成功,422 超时
     * @param {Array<any>} rsp.brigades 配置到队伍,大队伍列表信息
     * @param {number} rsp.brigades.brigadeID 大队伍ID号
     * @param {Array<any>} rsp.brigades.playerList 小队伍玩家列表
     * @param {number} rsp.brigades.playerList.userID 小队伍玩家ID
     * @param {string} rsp.brigades.playerList.userProfile 小队伍玩家自定义数据
     * @memberof MatchvsResponse
     */
    teamMatchResultNotify(rsp:any):void

数据示例:

{
  "status": 200,
  "brigades": [
    {
      "brigadeID": 1,
      "playerList": [
        {
          "userID": 388139,
          "userProfile": "temamode"
        },
        {
          "userID": 388138,
          "userProfile": "i come team 哈哈"
        }
      ]
    },
    {
      "brigadeID": 2,
      "playerList": [
        {
          "userID": 388149,
          "userProfile": "temamode"
        },
        {
          "userID": 388148,
          "userProfile": "i come team 哈哈"
        }
      ]
    }
  ],
  "roomInfo": {
    "roomID": "1722967918502744099",
    "roomProperty": "STTeamMatch",
    "ownerId": 388138,
    "owner": 388138,
    "state": 0
  }
} 

示例代码

response.teamMatchResponse = function(rsp){
    console.log("[RSP]teamMatchResponse:"+JSON.stringify(rsp));
};
response.teamMatchResultNotify = function(notify){
    console.log("[RSP]TeamMatchResultNotify:"+JSON.stringify(notify));
};
response.teamMatchStartNotify = function(notify){
    console.log("[RSP]TeamMatchStartNotify:"+JSON.stringify(notify));
};

var cond ={
    teamNum:2,
    MemberNum:2,
    timeout:15,
    weight:15,
    weightRange:5,
    weightRule:0,
    full:0
};
var info = new MVS.MsTeamMatchInfo("STTeamMatch", 10, 1, 0,1,"STTeamMatch",
           new MVS.MsTeamMatchCond(cond.teamNum, cond.MemberNum, cond.timeout, cond.weight, cond.weightRange, cond.weightRule, cond.full), 
           new MVS.MsWatchSet(600000, 3, 60000, true)
);
console.log("[REQ]STTeamMatch:"+engine.teamMatch(info));

cancelTeamMatch

开始匹配后,在还没有匹配到队伍的情况下可以取消当前匹配。这个时候所有小队伍内的玩家都会从匹配列表中移除,触发取消匹配的人收到 cancelTeamMatchResponse 回调,其他人收到 cancelTeamMatchNotify 的回调。

    /**
     * 取消组队匹配,只有在组队匹配的时候才能调用这个接口
     * @param {object} args
     * @param {string} args.cpProto 取消组队匹配时携带的消息 长度不能超过 1024/B
     */
    cancelTeamMatch(args:object):number

cancelTeamMatchResponse

调用取消匹配接口 cancelTeamMatch 时会收到这个接口的回调。

    /**
     * 取消组队匹配返回,但调用 cancelTeamMatch 接口后,通过这个接口接收服务的结果
     * @param {number} rsp.status
     */
    cancelTeamMatchResponse(rsp:any);

cancelTeamMatchNotify

有队员调用取消匹配接口 cancelTeamMatch 时,其他队员会收到这个接口的回调

    /**
     * 取消组队匹配时
     * @param {any} notify 
     * @param {number} notify.userID 取消组队匹配的玩家ID
     * @param {string} notify.teamID 当前的队伍号
     * @param {string} notify.cpProto 取消时附带的消息
     */
    cancelTeamMatchNotify(notify:any);

示例代码

response.cancelTeamMatchResponse = function(rsp){
    console.log("[RSP]cancelTeamMatchResponse:"+JSON.stringify(rsp));
};
response.cancelTeamMatchNotify = function(notify){
    console.log("[RSP]cancelTeamMatchNotify:"+JSON.stringify(notify));
};
engine.cancelTeamMatch({cpProto:"cancel team match"});

组队对内管理

kickTeamMember

踢出内成员,在组队期间如果没有开始组队匹配可以使用这个接口踢出其他玩家,不可以踢出自己。

    /**
     * 剔除队伍中的指定玩家,队伍中任何人都可以剔除任意人,但是不能剔除自己。
     * @param {object} args
     * @param {number} args.userID 要剔除的玩家
     * @param {number} args.cpProto 剔除玩家时携带的信息,长度不能超过 1024/B
     */
    kickTeamMember(args:object):number

kickTeamMemberResponse

调用踢人接口会收到这个接口的回调。

    /**
     * 调用 kickTeamMember 接口后,通过这个接口获取服务的结果
     * @param {any} rsp
     * @param {number} rsp.status 状态 200 表示成功
     * @param {Array<number>} rsp.members 队伍内剩下的玩家
     * @param {number} rsp.owner 当前队伍中队长
     * @param {string} rsp.teamID 当前队伍号
     */
    kickTeamMemberResponse(rsp:any);

kickTeamMemberNotify

有别的玩家调用了踢人接口,那么另外其他玩家会收到这个接口的回调。

    /**
     * 收到踢人通知,当队伍中有人触发踢人接口,其他人就会收到这个接口的通知
     * @param {any} notify 
     * @param {string} notify.teamID 当前队伍号
     * @param {number} notify.userID 当前发起踢人的玩家号
     * @param {number} notify.dstUserID 被踢的玩家号
     * @param {number} notify.owner 当前队伍的队长
     * @param {Array<number>} notify.members 队伍中剩下的玩家
     * @param {string} notify.cpProto 踢人时携带的消息
     */
    kickTeamMemberNotify(notify:any);

示例代码

response.kickTeamMemberResponse = function(rsp){
    console.log("[RSP]kickTeamMemberResponse:"+JSON.stringify(rsp));
};
response.kickTeamMemberNotify = function(notify){
    console.log("[RSP]kickTeamMemberNotify:"+JSON.stringify(notify));
};
engine.kickTeamMember({userID:userid, cpProto:"kick team member"});

小对内通信

sendTeamEvent

在组队期间,可以使用这个接口发送消息给其他的队内成员,自己收到 sendTeamEvent 的回调,其他成员收到 sendTeamEventNotify的回调,类似 sendEvent接口的使用,这个接口有对消息发送的频率做了限定,目前限定每秒不能超过20次。同时消息长度也有限定不能超过 1KB。只有在队伍中才能发送消息。

    /**
     * 组队时,进入到同一个队伍中的玩家,可以通过这个接口来发送消息。这个消息发送频率是有限制 50ms/条。
     * @param {object} args
     * @param {number} args.dstType 0-包含dstUids  1-排除dstUids
     * @param {number} args.msgType 0-只发client  1-只发gs  2-client和 gs 都发
     * @param {Array<number>} args.dstUserIDs 指定的用户列表 配合 dstType 使用
     * @param {string} args.data 发送的数据 长度不能超过 1024/B
     */
    sendTeamEvent(args:object):number

sendTeamEventResponse

发送队内消息回调,发送者收到的回调

    /**
     * 在队伍中发送消息回调,调用sendTeamEvent 接口后,这个接口收到发送的结果
     * @param {any} rsp
     * @param {number} rsp.status 发送队伍消息的结果,200 成功。
     * @param {Array<number>} rsp.dstUserIDs 发送消息给了哪些玩家。
     */
    sendTeamEventResponse(rsp:any);

sendTeamEventNotify

有别的玩家调用了发送消息接口,那么另外其他玩家会收到这个接口的回调。

    /**
     * 接收忘记发送队伍消息,当其他玩家在队伍中发送消息时,其他指定的玩家就能收到这个接口的回调
     * @param {any} notify
     * @param {any} notify.userID 发送消息的玩家ID
     * @param {any} notify.teamID 当前队伍号
     * @param {string} notify.cpProto 收到的数据
     */
    sendTeamEventNotify(notify:any);

示例代码

response.sendTeamEventResponse = function(rsp){
    console.log("[RSP]sendTeamEventResponse:"+JSON.stringify(rsp));
};
response.sendTeamEventNotify = function(notify){
    console.log("[RSP]sendTeamEventNotify:"+JSON.stringify(notify));
};
engine.sendTeamEvent({msgType:0, dstType:1, data:data, dstUserIDs:[]});

队伍属性

setTeamProperty

设置队伍属性,对全员可见,主体是小队

    /**
     * 设置队伍属性,对全员可见,主体是小队
     * @see {string} setTeamUserProfile
     * @param teamProperty
     * @returns {number}
     */
    setTeamProperty(teamProperty:string):number;

setTeamPropertyResponse

    /**
     * @see setTeamProperty
     * @param {number} rsp.status
     * @param {string} rsp.teamID
     * @param {number} rsp.userID
     * @param {String} rsp.teamProperty
     */
    setTeamPropertyResponse(rsp): void

setTeamPropertyNotify

    /**
     * @see setTeamUserProfile
     * @param {string} notify.teamID
     * @param {number} notify.userID
     * @param {String} notify.teamProperty
     */
    setTeamPropertyNotify(notify): void

队伍成员属性

setTeamUserProfile

设置小队中自己的私有属性,主体是队伍成员,对其他成员可见

    /**
     * 设置小队中自己的私有属性,主体是队伍成员,对其他成员可见
     * @see {string} setTeamProperty
     * @param userProfile
     * @returns {number}
     */
    setTeamUserProfile (userProfile:string):number;

setTeamUserProfileResponse

    /**
     * @see setTeamUserProfile
     * @param {number} rsp.status
     * @param {string} rsp.teamID
     * @param {number} rsp.userID
     * @param {String} rsp.teamProperty
     */
    setTeamUserProfileResponse(rsp):void

setTeamUserProfileNotify

 /**
     * @see setTeamProperty
     * @param {string} notify.teamID
     * @param {number} notify.userID
     * @param {String} notify.teamUserProfile
     */
    setTeamUserProfileNotify(notify): void

掉线异常处理

teamNetworkStateNotify

当队伍中有成员与服务器断开连接时回调

/**
 * 当队伍中有成员与服务器断开连接时,回调
 * @param notify
 * @param {number} notify.userID 掉线的userID
 */
teamNetworkStateNotify(notify:any);

setTeamReconnectTimeout

有必要重连时, 在login后调用此函数

    /**
     * 设置组队匹配断线后允许的重连进入小队的时间, 单位秒,范围(1~60)
     * @param {number} timeout 单位秒
     */
    setTeamReconnectTimeout (timeout:number):number;

    /**
     * @see setTeamReconnectTimeout
     * @param {number} status 200表示成功
     */
    setTeamReconnectTimeoutResponse(status:number);
最后更新于 13th Jun 2019