egret-docs-master/extension/matchvs/guide/team
guofei 4fe0162b34 fist commit 2024-06-19 13:32:32 +08:00
..
README.md fist commit 2024-06-19 13:32:32 +08:00

README.md

组队示例

当前页面是组队相关的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 段位为 2team2 段位为4则合成大队后大队权重为平均值 3 。如相应支持更多的合成后计算规则可以进入技术支持群QQ450335262 进行反馈。

匹配时会自动根据设置的队伍数量及每队人数进行小队间的组合最终会尽量保障两边队伍段位均衡。如5v5team1playerA、team2player B C D E、team3player F G 、team4player 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*10006分钟
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

setTeamUserProfileNotify

 /**
     * @see setTeamProperty
     * @param {string} notify.teamID
     * @param {number} notify.userID
     * @param {String} notify.teamUserProfile
     */
    setTeamUserProfileNotify(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

setTeamPropertyNotify

    /**
     * @see setTeamUserProfile
     * @param {string} notify.teamID
     * @param {number} notify.userID
     * @param {String} notify.teamProperty
     */
    setTeamPropertyNotify(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);