egret-docs-master

97 KiB

Raw Blame History

API 说明

MatchvsSDK 主要是由 MatchvsEngine（接口请求）类，和 MatchvsResponse（接口回调）类控制。先new这两个类的对象作为全局使用。例如：

let engine = new MatchvsEngine();
let response = new MatchvsResponse();

初始化

在连接至 Matchvs前须对SDK进行初始化操作。此时选择连接测试环境（alpha）还是正式环境（release）。环境说明。初始化请求接口有两个，如果你是使用 Matchvs 官网账号在 Matchvs 控制台创建的游戏（简称Matchvs云服务）使用 init 接口初始化，如果是使用 Matchvs 服务端引擎代码在自己自定的服务器上部署的游戏服务就使用（简称 Matchvs独立部署） premiseInit 接口初始化。

如果 Matchvs 服务正在升级，init 接口会放回 510 错误码，开发者可以选择是否需要展示“服务升级”的提示。

如果游戏属于调试阶段则连接至测试环境，游戏调试完成后即可发布到正式环境运行。

请求接口：init、premiseInit
回调接口：initResponse

init

初始化请求接口。

engine.init(pResponse: MatchvsResponse, pChannel: string, pPlatform: string, gameID: number, appKey: string, gameVersion: number, threshold ?:number): number

参数：

参数	类型	描述	示例值
response	MatchvsResponse	回调类型MatchvsResponse的对象	response
channel	string	渠道，固定值	"Matchvs"
platform	string	平台，选择测试(alpha)or正式环境(release)	"alpha"
gameID	number	游戏ID，在引擎官网创建游戏给出的ID	200103
appKey	string	游戏 App Key 官网生成
gameVersion	number	游戏版本，自定义，用于隔离匹配空间
threshold	number	延迟容忍,在有多个节点的情况下使用，如果使用默认节点请可以不传该值	0 或不传

response 中设置一些回调方法，在执行注册、登录、发送事件等操作对应的方法之后，reponse中的回调函数会被SDK异步调用。

注意发布之前须到官网控制台申请“发布上线”，申请通过后在调用init方法时传“release”才会生效，否则将不能使用release环境。

错误码：

错误码	含义
0	成功
-1	失败
-25	channel 非法，请检查是否正确填写为 “Matchvs”
-26	platform 非法，请检查是否正确填写为 “alpha” 或 “release”

premiseInit

使用独立部署的游戏调用此接口初始化SDK。

function engine.premiseInit(response:MatchvsResponse, endPoint:string, gameID:number, appKey: string):number

参数

参数	类型	描述	示例值
response	MatchvsResponse	回调类型MatchvsResponse的对象	response
endPoint	string	服务配置的域名地址	test.xxxxx.com
gameID	number	服务配置的游戏ID	123456
appKey	string	游戏 App Key 官网生成

返回值

错误码	含义
0	接口调用成功
-1	接口调用失败

initResponse

initResponse是 MatchvsResponse对象属性，在 engine.init 方法中传入的对象，init初始化完成之后，会异步回调 initResponse方法。

response.initResponse(status:number);

参数

参数	类型	描述	示例值
status	number	状态返回，200表示成功，其他失败	200

示例代码

class MsEngine {
    private static engine = new MatchvsEngine();
	private static response = new MatchvsResponse();
    
    private init(){
        this.response.initResponse = (status:number)=>{
            if(status == 200){
                //成功
            }else{
                //失败
            }
        }
        this.engine.init(this.response, "Matchvs", "alpha", 123456, "xxxxappkey", 1);
    }
}

反初始化

SDK反初始化工作，反初始化会让 init 中的 response 回调失效，也就是收不到任何的回调了。只有请求，没有回调。

请求接口： uninit
回调接口：无

uninit

engine.uninit()

错误码

错误码	含义
0	成功
-1	失败

注册用户

Matchvs提供的 userID 被用于在各个服务中校验连接的有效性，调试前开发者需要先获取到一个合法的userID。调用registerUser接口获取，在registerResponse回调返回。

每次调用 registerUser 接口都会生成新的 userID 为了节省资源消耗， userID和 token 有需要的可以缓存起来，在之后的应用启动中不必重复获取。如果你有自己的用户系统，可以将Matchvs 提供的 userID 和用户系统进行映射。可以参考 Matchvs 第三方账号绑定，让您的用户唯一对应一个userID，以节省资源。

为了资源节省，我们在registerUserResponse 回调前把userID信息缓存在本地，数据会暂存在浏览器中。所以使用同一个浏览器调用 registerUser 接口会返回相同的 userID信息。如果需要清除缓存的用户信息请调用 LocalStore_Clear() 接口。

请求接口：registerUser
回调接口：registerUserResponse

registerUser

engine.registerUser()

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化

registerUserResponse

registerUserResponse(userInfo:MsRegistRsp);

参数MsRegistRsp类的属性

属性	类型	描述	示例值
userID	number	用户ID	123456
token	string	用户Token	"XGBIULHHBBSUDHDMSGTUGLOXTAIPICMT"
name	string	用户名称	"张三"
avatar	string	头像	"http://pic.vszone.cn/upload/head/1416997330299.jpg"
status	number	接口回调状态码,0表示成功，其他失败	0 成功

注意：如果需要同时调试多个客户端，则需要打开多个不同的浏览器进行调试。

示例代码

class MsEngine {
	......
    private registerUser(){
        this.response.registerUserResponse = (userInfo:MsRegistRsp)=>{
            if(userInfo.status == 0){
                //成功
            }else{
                //失败
            }
        }
        this.engine.registerUser();
    }
}

登录Matchvs服务端，与Matchvs建立连接。服务端会校验游戏信息是否合法，保证连接的安全性。如果一个账号在两台设备上登录，则后登录的设备会连接失败，提示403错误。如果用户加入房间之后掉线，再重新登录进来，则roomID为之前加入的房间的房间号。

请求接口：login
回调接口：loginResponse

engine.login(userID: number, token: string, deviceID: string, nodeID?:number): number

参数

参数	类型	描述	示例值
userID	number	用户ID，调用注册接口后获取	123546
token	string	用户token，调用注册接口后获取	""
deviceID	string	设备ID，用于多端登录检测，请保证是唯一ID	""
nodeID	number	节点ID，有多节点的时候，使用getNodeList 获取有效节点，多节点情况说明

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化，请先调用初始化接口
-3	正在初始化
-5	正在登录
-6	已经登录，请勿重复登录
-11	正在登出

loginResponse

response.loginResponse(login:MsLoginRsp);

参数 MsLoginRsp 类的属性

属性	类型	描述	示例值
status	number	状态返回：200 成功；402 应用校验失败，确认是否在未上线时用了release环境，并检查gameID、appkey 和 secret ；403 检测到该账号已在其他设备登录； 404 无效用户；500 服务器内部错误	200
roomID	string	房间号（预留断线重连）	210039

示例代码

class MsEngine {
	......
    private login(){
        this.response.registerUserResponse = (login:MsLoginRsp)=>{
            if(userInfo.status == 200){
                //成功
            }else{
                //失败
            }
        }
        this.engine.login(1234, "xxxxxtoken", "v");
    }
}

登出

退出登录，断开与Matchvs的连接。

请求接口：logout
回调接口：logoutResponse

logout

engine.logout(cpProto:string):number

参数

参数	类型	描述	示例值
cpProto	string	负载信息	""

返回值

错误码	含义
0	成功
-1	失败
-4	未登录

logoutResponse

response.logoutResponse(status:number);

参数

参数	类型	描述	示例值
status	number	状态返回，200表示成功；500 服务器内部错误	200

加入房间

登录游戏后，需要与其他在线玩家一起对战，先要进行进入房间，类似英雄联盟这样的匹配功能将若干用户匹配至一个房间开始一局游戏，Matchvs 提供4中加入房间的方法。

请求接口：
- joinRandomRoom：随机接入房间。
- joinRoomWithProperties：自定义属性匹配。
- createRoom：创建房间。
- joinRoom: 指定由createRoom接口创建房间的房间号加入房间。
回调接口：
- joinRoomResponse：自己加入房间收到回调。
- joinRoomNotify：其他人加入房间收到回调。
- crateRoomResponse：调用 createRoom 接口收到的回调。

joinRandomRoom

当房间里人数等于maxPlayer时，房间人满。系统会将玩家随机加入到人未满且没有 joinOver 的房间。如果不存在人未满且没有joinOver的房间，则系统会再创建一个房间，然后将玩家加入到该房间。玩家 userProfile 的值可以自定义，接下来会通过回调函数（如 joinRoomResponse ）传给其他客户端。

engine.joinRandomRoom(maxPlayer:number, userProfile:string):number

参数

参数	类型	描述	示例值
maxPlayer	number	房间内最大玩家数	3
userProfile	string	玩家简介	""

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-8	已经在房间中
-20	1 <maxPlayer超出范围，maxPlayer须≤100
-21	userProfile 过长，不能超过512个字符

joinRoomWithProperties

joinRoomWithProperties(matchinfo:MsMatchInfo, userProfile:string, watchSet?: MVS.MsWatchSet ):number

参数

参数	类型	描述	示例值
matchinfo	MsMatchInfo	配置信息
userProfile	string	玩家简介	""
watchSet	MVS.MsWatchSet	观战信息

MsMatchInfo 的属性

属性	类型	描述	示例值
maxPlayer	number	玩家最大人数	3
mode	number	模式可默认填0	0
canWatch	number	是否可以观战 1-可以 2-不可以	1
tags	object	匹配属性值	{title:"Matchvs",name:"demo"}
visibility	number	是否可见 0-不可见 1-可见	1
roomProperty	string	自定义房间附加信息	“roomProperty”

MVS.MsWatchSet 的属性

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

ags为匹配标签，开发者通过设置不同的标签进行自定义属性匹配，相同MsMatchInfo的玩家将会被匹配到一起。

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-8	已经在房间中
-21	userProfile 过长，不能超过512个字符
-20	1 <maxPlayer超出范围，maxPlayer须≤100

createRoom

开发者可以在客户端主动创建房间，创建成功后玩家会被自动加入该房间，创建房间者即为房主，如果房主离开房间则Matchvs会自动转移房主并通知房间内所有成员，开发者通过设置CreateRoomInfo创建不同类型的房间。创建房间成功，如果需要再次创建房间需要调用离开房间接口(leaveRoom)先离开当前房间。

engine.createRoom(createRoomInfo:MsCreateRoomInfo, userProfile:string, watchSet?:MVS.MsWatchSet): number

参数

参数	类型	描述	示例值
createRoomInfo	MsCreateRoomInfo	创建房间的信息
userProfile	string	玩家简介	""
watchSet	object	观战服务参数,创建房间时，如果没有设置 watchSet 参数，则默认是不可观战的， watchSet 参数要与MsCreateRoomInfo的canWatch参结合使用，如果没有设置观战参数，再获取房间列表的时候 canWatch参数需要设置0或者2。

MsCreateRoomInfo 的属性

属性	类型	描述	示例值
roomName	string	房间名称	“MatchvsRoom”
maxPlayer	number	最大玩家数	3
mode	number	模式	1
canWatch	number	是否可以观战 1-可以 2-不可以	2
visibility	number	是否可见默认0不可见 1可见	1
roomProperty	string	房间属性	“roomProperty”

MVS.MsWatchSet

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

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-8	已在房间
-21	userProfile 过长，不能超过512

createRoomResponse

response.createRoomResponse(rsp:MsCreateRoomRsp);

MsCreateRoomRsp 属性

参数	类型	描述	示例值
status	number	状态返回，200表示成功；400 客户端参数错误；500 服务器内部错误	200
roomID	string	房间号	"210039"
owner	number	房主	210000

joinRoom

客户端可以通过调用该接口加入指定房间，roomID为加入指定房间的房间号，指定房间号必须是由 createRoom接口创建的房间。

engine.joinRoom(roomID:string,userProfile:string):number

参数

参数	类型	描述	示例值
roomID	string	房间号	"1344333"
userProfile	string	玩家简介	""

返回值

同 joinRandomRoom

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-8	已经在房间中
-21	userProfile 过长，不能超过512个字符

joinRoomResponse

response.joinRoomResponse(status:number, roomUserInfoList:Array<MsRoomUserInfo>, roomInfo:MsRoomInfo);

参数

参数	类型	描述	示例值
status	number	状态返回，200表示成功；400 客户端参数错误；404 指定房间不存在；405 房间已满；406 房间已joinOver ；500 服务器内部错误	200
roomUserInfoList	Array	房间内玩家信息列表
roomInfo	MsRoomInfo	房间信息构成的对象

MsRoomUserInfo 的属性

属性	类型	描述	示例值
userID	number	用户ID	32322
userProfile	string	玩家简介	""

MsRoomInfo 的属性

属性	类型	描述	示例值
roomID	string	房间号	238211
roomProperty	string	房间属性	""
owner	number	房间创建者的用户ID	0

如果本房间是某个玩家调用joinRandomRoom随机加入房间时创建的，那么roomInfo中的owner为服务器随机指定的房主ID。在调用engine.createRoom主动创建房间时owner为创建房间者（即房主）的ID。以上两种情况下，如果房主离开房间，服务器均会指定下一个房主，并通过leaveRoomNotify通知房间其他成员。
roomUserInfoList 用户信息列表是本玩家加入房间前的玩家信息列表，不包含本玩家。
roomUserInfoList中的玩家的userProfile的值来自于其他客户端调用joinRandomRoom时传递的userProfile的值。

joinRoomNotify

response.joinRoomNotify(roomUserInfo:MsRoomUserInfo);

参数

参数	类型	描述	示例值
roomUserInfo	MsRoomUserInfo	房间新加的用户的信息

某个玩家加入房间之后，如果该房间后来又有其他玩家加入，那么将会收到回调通知，response.joinRoomNotify方法会被SDK调用，调用时传入的roomUserInfo是新加入的其他玩家的信息，不是本玩家的信息。
roomUserInfo的属性与response.joinRoomResponse中的roomUserInfoList中的元素包含的属性相同。

示例代码

class MsEngine {
	......
    private joinRoom(){
        this.response.joinRoomResponse = (status:number, roomUserInfoList: Array <MsRoomUserInfo>, roomInfo:MsRoomInfo)=>{
            if(status == 200){
                //成功
            }else{
                //失败
            }
        }
        this.response.joinRoomNotify = (roomUserInfo:MsRoomUserInfo)=>{
            //roomUserInfo.userID 加入房间
        }
        this.engine.joinRandRoom(3, "hello matchvs");
    }
}

关闭房间

一般在匹配到用户，开始游戏之前要关闭房间，防止有其他玩家中途加入。

请求接口：joinOver
返回接口：
- joinOverResponse ：自己关闭房间回调
- joinOverNotify : 别人关闭房间回调

joinOver

engine.joinOver(cpProto:string):number

参数

参数	类型	描述	示例值
cpProto	string	负载信息	""

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-6	不在房间
-21	cpProto过长，不能超过 1024 字符

joinOverResponse

客户端调用engine.joinOver发送关闭房间的指令之后，SDK异步调用reponse.joinOverResponse方法告诉客户端joinOver指令的处理结果。

response.joinOverResponse(rsp:MsJoinOverRsp);

MsJoinOverRsp的属性

属性	类型	描述	示例值
status	number	状态返回，200表示成功；400 客户端参数错误；404 用户或房间不存在；403 该用户不在房间；500 服务器内部错误	200
cpProto	string	负载信息

joinOverNotify

当有人调用了 joinOver 接口，同一房间的其他用户就会收到这个回调信息。

response.joinOverNotify(notifyInfo:MsJoinOverNotifyInfo);

参数 MsJoinOverNotifyInfo 的属性

属性	类型	描述
roomID	string	房间ID
srcUserID	number	发起关闭房间玩家ID
cpProto	string	负载信息

示例代码

class MsEngine {
	......
    private joinOver(){
        this.response.joinOverResponse = (rsp:MsJoinOverRsp)=>{
            if(rsp.status == 200){
                //成功
            }else{
                //失败
            }
        }
        this.response.joinOverNotify = (notifyInfo:MsJoinOverNotifyInfo)=>{
            //notifyInfo.srcUserID 关闭房间 notifyInfo.roomID
        }
        this.engine.joinOver("hello matchvs");
    }
}

离开房间

客户端调用该接口通知服务端该客户端对应的用户要离开房间。当所有玩家离开房间后，房间会被自动销毁。

请求接口：leaveRoom
返回接口：
- leaveRoomResponse：自己离开房间回调
- leaveRoomNotify: 其他玩家离开房间回调

leaveRoom

engine.leaveRoom(cpProto:string):number

参数

参数	类型	描述	示例值
cpProto	string	负载信息	""

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-21	userProfile 过长，不能超过1024

leaveRoomResponse

客户端调用engine.leaveRoom发送关闭房间的指令之后，SDK异步调用reponse.leaveRoomResponse方法告诉客户端leaveRoom指令的处理结果。

response.leaveRoomResponse(rsp:MsLeaveRoomRsp);

参数MsLeaveRoomRsp的属性

属性	类型	描述	示例值
status	number	状态返回，200表示成功；400 客户端参数错误；404 房间不存在；500 服务器内部错误	200
roomID	string	房间号	317288
userID	number	用户ID	317288
cpProto	string	负载信息

leaveRoomNotify

当同房间中的其他玩家调用leaveRoom发送离开房间的指令之后，本客户端将会收到回调通知，response.leaveRoomNotify方法会被SDK调用，调用时传入的roomUserInfo是离开房间的玩家的信息。

response.leaveRoomNotify(leaveRoomInfo:MsLeaveRoomNotify);

参数 MsLeaveRoomNotify 属性

参数	类型	描述	示例值
userID	number	房间号	200
roomID	string	刚刚离开房间的用户的信息
owner	number	房主
cpProto	string	附加信息

roomUserInfo 的属性与response.joinRoomResponse中的roomUserInfoList中的元素包含的属性相同。

示例代码

class MsEngine {
	......
    private leaveRoom(){
        this.response.leaveRoomResponse = (rsp:MsLeaveRoomRsp)=>{
            if(rsp.status == 200){
                //成功
            }else{
                //失败
            }
        }
        this.response.leaveRoomNotify = (leaveRoomInfo:MsLeaveRoomNotify)=>{
            //leaveRoomInfo.srcUserID 离开房间 leaveRoomInfo.roomID
        }
        this.engine.leaveRoom("hello matchvs");
    }
}

获取房间列表

调用createRoom创建房间可以使用 getRoomList 或者 getRoomListEx 接口获取房间列表，由系统创建的房间是不能被获取的。getRoomList 接口参数要简单一些，对应的 getRoomListResponse 回调信息也少很多。 getRoomListEx 接口请求返回的信息要多一些，支持房间信息排序等功能。

请求接口：getRoomList，getRoomListEx
回调接口：getRoomListResponse , getRoomListExResponse

getRoomList

获取主动创建房间的列表信息，简单版。

engine.getRoomList(filter:MsRoomFilter):number

MsRoomFilter 的属性

参数	类型	描述	示例值
maxPlayer	number	最大玩家数	maxPlayer:3;mode:0;canWatch:0
mode	number	模式	0
canWatch	number	是否可以观战 1-可以 2-不可以	2
roomProperty	string	房间属性	“roomProperty”

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-8	已在房间
-21	filter 过长，总字节不能超过1024

getRoomListResponse

response.getRoomListResponse(status:number, roomInfos:Array<MsRoomInfoEx>);

参数

参数	类型	描述	示例值
status	number	状态返回，200表示成功；500 服务器内部错误	200
roomInfos	Array	房间信息列表

MsRoomInfoEx 的属性

属性	类型	描述	示例值
roomID	string	房间ID	"123456786"
roomName	string	房间名称	“matchvsRoom”
maxPlayer	number	最大人数	3
mode	number	模式	0
canWatch	number	是否可以观战 1-可以 2-不可以	2
roomProperty	string	房间属性	“roomProperty”

getRoomListEx

获取房间列表信息扩展版，可获得更多的房间信息。

engine.getRoomListEx(filter:MsRoomFilterEx);

参数 MsRoomFilterEx 属性

参数	类型	描述	示例值
maxPlayer	number	房间最大人数 (0-全部)	3
mode	number	模式（0-全部）*创建房间时，mode最好不要填0	2
canWatch	number	是否可以观战（0-全部 1-可以 2-不可以）	1
roomProperty	string	房间属性	“roomProperty”
full	number	0-全部 1-满 2-未满	0
state	number	0-全部 1-开放 2-关闭	0
sort	number	0-不排序 1-创建时间排序 2-玩家数量排序 3-状态排序	0
order	number	0-ASC 1-DESC	0
pageNo	number	页码	0
pageSize	number	每一页的数量	10
getSystemRoom	number	是否获取系统创建的房间,0玩家创建,1系统创建,2玩家+系统创建	2

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-21	filter 过长，总字节不能超过1024

获取房间列表参数必须和 createRoom 接口创建的房间参数一致而且 createRoom 中的参数 visibility 必须设置为1(可见)。比如：createRoom 参数结构如下：

var createRoomInfo = new MsCreateRoomInfo("Matchvs",3, 0, 0, 1, "mapA")

那么getRoomList 参数结构应该如下：

var filter = new MsRoomFilterEx(
	    createRoomInfo.maxPlayer, 		//maxPlayer
        createRoomInfo.mode,		    //mode
        createRoomInfo.canWatch,		//canWatch
        createRoomInfo.roomProperty,    //roomProperty
        0, 	//full 0-未满
        1,  //state 0-全部，1-开放 2-关闭
        0,  //sort 0-不排序 1-创建时间排序 2-玩家数量排序 3-状态排序 都可以
        0,  //order 0-ASC  1-DESC 都可以
        0,  //pageNo 从0开始 0为第一页
        3,  //pageSize 每页数量 大于0
        );

getRoomListExResponse

response.getRoomListExResponse(rsp:MsGetRoomListExRsp);

参数 MsGetRoomListExRsp 的属性

参数	类型	描述	示例值
status	number	状态 200 成功；500 服务器内部错误	200
total	number	房间总数量	2
roomAttrs	Array	房间信息列表	[]

参数 MsRoomAttribute 的属性

参数	类型	描述	示例值
roomID	string	房间号	“”
roomName	string	房间名称	“roomName”
maxPlayer	number	最大人数	3
gamePlayer	number	游戏人数	2
watchPlayer	number	观战人数	1
mode	number	模式	0
canWatch	number	是否可以观战 1-可以 2-不可以	2
roomProperty	string	房间属性	“roomProperty”
owner	number	房主	326541
state	number	房间状态 1-开放 2-关闭	1
createTime	string	创建时间

参数total 与 roomAttrs 列表length 可能会不同，但是 total 会 >= roomAttrs 列表的 length。

示例代码

class MsEgine {
    ......
    private getRoomListEx():void{
        this.response.getRoomListExResponse = (rsp:MsGetRoomListExRsp)=>{
            if(status == 200){
                //获取成功
            }else{
                //获取失败
            }
        };
        let filter = new MsRoomFilterEx(3, 0, 0, "matchvs", 0, 1, 0, 0, 0, 3);
       	this.engine.getRoomListEx(filter);
    }
}

获取房间详情

在获取房间列表扩展接口会返回房间一些信息，但是在房间里面后房间信息可能会有变动，或者在显示房间列表后想查看更多信息，可以使用获取房间详情接口。只可获取 createRoom 接口创建的房间。

请求接口：getRoomDetail
回调接口：getRoomDetailResponse

getRoomDetail

engine.getRoomDetail(roomID:string)

参数

参数	类型	描述	示例值
roomID	string	房间ID	“16323532544156875354”

返回值

错误码	含义
0	调用成功
-1	调用失败
-2	未初始化
-4	未登陆
-7	正在加入房间
-3	正在初始化

getRoomDetailResponse

response.getRoomDetailResponse(rsp:MsGetRoomDetailRsp);

参数 MsGetRoomDetailRsp 的属性

参数	类型	描述
status	number	接口状态 200 成功；404 房间不存在；500 服务器内部错误
state	number	房间状态 1-开放 2-关闭
maxPlayer	number	最大人数
mode	number	模式
canWatch	number	是否可以观战 1-可以 2-不可以
roomProperty	string	房间属性
owner	number	房主
createFlag	number	创建方式 0-未知 1-系统创建 2-玩家创建
userInfos	Array	用户列表信息
watchinfo	object	观战信息
brigades	Array	组队列表信息

MsRoomUserInfo 的属性

属性	类型	描述	示例值
userID	number	用户ID	32322
userProfile	string	玩家简介	""

watchinfo 属性

属性	类型	描述	示例值
curWatch	number	房间当前观战者人数	3
persistent	boolean	观战信息是否持久保存	false
maxWatch	number	最大观战人数	6
delayMS	number	延迟时间，可观看延迟多久的数据（单位毫秒）	6000
cacheTime	number	缓存时间，游戏最大能缓存多久的数据(单位毫秒)	60000

brigades 属性

属性	类型	描述	示例值
brigadeID	number	大队伍的ID	1
teamList	Array	小队伍信息列表

teamList 数据项属性

属性	类型	描述	示例值
teamID	string	小队伍ID号	131113213211323121231
capacity	number	小队伍人数	5
mode	number	自定义参数	0
owner	number	队长	123456
playerList	Array	队伍成员

设置房间属性

创建房间时需要传入房间属性参数，当房间创建好后可以调用 setRoomProperty 接口修改房间的属性。比如：房间地图，房间人员的等级要求等等。

请求接口：setRoomProperty
回调接口：setRoomPropertyResponse，setRoomPropertyNotify

setRoomProperty

engine.setRoomProperty(roomID:string, roomProperty:string):number

参数

参数	类型	描述	示例值
roomID	string	房间号	"654354323413134354"
roomProperty	string	要修改的房间属性	“changeRoomProperty”

返回值

错误码	含义
0	调用成功
-1	调用失败
-2	未初始化
-3	正在初始化
-4	未登陆
-7	正在加入房间
-10	正在登出
-11	正在离开房间
-21	roomProperty 长度过长，不能超过1023字符

setRoomPropertyResponse

response.setRoomPropertyResponse(rsp:MsSetRoomPropertyRspInfo);

参数 MsSetRoomPropertyRspInfo 的属性

参数	类型	描述	示例值
status	number	状态值，200成功；400 客户端参数错误；404 房间不存在；500 服务器内部错误	200
roomID	string	房间号	"654354323413134354"
userID	number	玩家	123
roomProperty	string	修改后的属性值	“changeRoomProperty”

setRoomPropertyNotify

房间有人调用 setRoomProperty 接口，其他人就会收到 setRoomPropertyNotify接口的回调。

response.setRoomPropertyNotify(notify:MsRoomPropertyNotifyInfo);

参数 MsRoomPropertyNotifyInfo 的属性

参数	类型	描述	示例值
roomID	string	房间号	"654354323413134354"
userID	number	玩家	123
roomProperty	string	修改后的属性值	“changeRoomProperty”

示例代码

class MsEngine{
    ......
    private setRoomProperty(roomID){
        this.response.setRoomPropertyResponse = (rsp:MsSetRoomPropertyRspInfo)=>{
            if(rsp.status == 200){
                //设置成功
            }else{
                //设置失败
            }
        }
        this.response.setRoomPropertyNotify = (notify:MsRoomPropertyNotifyInfo)=>{
            //notify.userID 有人修改了房间的属性，属性值为 notify.roomProperty
        }
        
        this.engine.setRoomProperty(roomID,"属性A");
    }
    ......
}

消息发送

在游戏中，玩家之间相互同步信息，把自己的位置，得分等情况发送给其他玩家，让其他玩家能够同步修改自己的信息。一个房间消息的总传递速率是每秒500次，500次是指房间 所有人接收和发送的总次数 。

注意给GameServer发送消息调用sendEventEx()。

请求接口：sendEvent、sendEventEx
回调接口：sendEventResponse、sendEventNotify、gameServerNotify (gameServer 推送的消息回调)

sendEvent

    /**
     * 发送消息，retuen 值 sequence 与接口回调 sendEventResponse 收到的 sequence 对应
     * 网络消息传递存在延时，不确定 sendEventResponse 是再哪一次 sendEvent 发送的，通过 sequence 确定。
     * @param {string|Uint8Array} data 要发送的数据
     * @param {boolean} isBinary 是否以二进制发送,如果是,data必须是Uint8Array类型
     * @returns {{sequence: number, result: number}}
     */
    sendEvent(data:string|Uint8Array,isBinary?:boolean):any

返回值

返回值为一个对象，该对象包含以下属性：

属性	类型	描述	示例值
result	number	错误码，0表示成功，其他表示失败	0
sequence	number	事件序号，作为事件的唯一标识。客户端发送消息后收到的sendEventResponse 也会收到 sequence 标识，通过此标识来确定这个sendEventResponse 是由哪次sendEvent 发送的。主要用于在游戏中做信息同步的时候，网络传输都有延迟会出现sendEvent与sendEventResponse 收到顺序不同。	231212

result 说明

返回码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-6	未加入房间
-21	data 过长, data长度不能超过1024个字符

消息会发给房间里除自己外 其他所有成员。同一客户端多次调用 sendEvent 方法时，每次返回的 sequence都是唯一的。但同一房间的不同客户端调用 sendEven t时生成的 sequence 之间会出现重复。可以发送二进制数据，开发者可以将数据用json、pb等工具先进行序列化，然后将序列化后的数据通过SendEvent的一系列接口发送。

sendEventEx

sendEvent 是 sendEventEx 接口的二次封装，只是 sendEvent 接口默认把消息发送给了房间其他人。如果需要把消息发送房间指定人员，或者只想把消息发送给 gameServer 那么就需要使用 sendEventEx 这个接口。想了解 gameServer 查看 gameServer 文挡

engine.sendEventEx(msgType:number, data:string, destType:number, userIDs:Array <number> ):any

提示：senEventEx 参数示例说明

//发送给房间中的全部玩家，destType = 1, userIDs = [] var data = mvs.engine.sendEventEx(0,msg,1,[]); console.log("发送信息 result"+ data.result); } //发送指定玩家 123456，destType = 0, userIDs = [123456] var data = mvs.engine.sendEventEx(0,msg,0,[123456]); console.log("发送信息 result"+ data.result); } //发送排除 123456 玩家，destType = 1, userIDs = [] var data = mvs.engine.sendEventEx(0,msg, 1,[123456]); console.log("发送信息 result"+ data.result); }

返回值

返回值为一个对象，该对象包含以下属性：

属性	类型	描述	示例值
result	number	错误码，0表示成功，其他表示失败	0
sequence	number	事件序号，作为事件的唯一标识	231212

result 说明

返回码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-6	未加入房间
-21	data 过长， data长度不能超过1024个字符
-23	msgType 非法
-24	desttype 非法

同一客户端多次调用engine.sendEvent方法时，每次返回的sequence都是唯一的。但同一房间的不同客户端调用sendEvent时生成的sequence之间会出现重复。

sendEventResponse

response.sendEventResponse(rsp:MsSendEventRsp);

MsSendEventRsp 的属性

属性	类型	描述	示例值
status	number	状态返回，200表示成功；521 gameServer不存在，请检查是否已开启本地调试或在正式环境发布运行gameServer	200
sequence	number	事件序号，作为事件的唯一标识，可以参考sendEvent，对这个字段的详细说明	231212

说明

客户端调用engine.sendEvent或engine.sendEventEx 发送消息之后，SDK异步调用reponse.sendEventResponse 方法告诉客户端消息是否发送成功。

sendEventNotify

response.sendEventNotify(eventInfo:MsSendEventNotify);

MsSendEventNotify的属性

参数	类型	描述	示例值
srcUserID	number	推送方用户ID，表示是谁发的消息	321
cpProto	string	消息内容，对应sendEvent中的msg参数	"hello"

gameServerNotify

开发者有使用 gameServer 的时候，如果有gameServer发送消息到客户端就会收到这个回调，回调的 srcUserID 是固定为0。

response.gameServerNotify(eventInfo:MsGameServerNotifyInfo);

参数 MsGameServerNotifyInfo属性

参数	类型	描述	示例值
srcUserID	number	gameServer推送时这个值为0	0
cpProto	string	推送的消息内容	“gameServer”

示例代码

class MsEngine{
    ......
    public constructor(){
        this.response.sendEventResponse = (rsp:MsSendEventRsp)=>{
            if(rsp.status == 200){
                //发送成功
            }else{
                //发送失败
            }
        };
        
        this.response.sendEventNotify = (eventInfo:MsSendEventNotify)=>{
            //eventInfo.srcUserID 发送数据 eventInfo.cpProto
        };
        this.response.gameServerNotify = (eventInfo:MsSendEventNotify)=>{
            //gameServer 推送了消息 eventInfo.cpProto
        };
    }
    public sendEventEx(){
        //这里发给其他用户和 gameServer
        this.engine.sendEventEx(0, data, 2, [123.456.789]);
    }
    ......
}

玩家断线错误提示

在游戏中如果自己断线了就会收到 errorResponse 的错误码为1001的消息，如果是其他玩家掉线了就会收到 networkStateNotify 的回调消息。通过这个接口就可以知道其他玩家的网络状态啦。断线后会有20秒内还可以调用 reconnect 接口重新连接进入房间。

注意：不要在 errorResponse 接口内直接调用 reconnect 接口，不然会出现死循环问题。

errorResponse

在调用Matchvs SDK 所有接口是，如果服务有异常就会触发 errorResponse 接口。通过错误码判断是属于哪一个类型的错误，比如 1001 是网络错误。

response.errorResponse(errCode:number, errMsg:string)

参数

参数	类型	描述	示例值
errCode	number	错误码	1001
errMsg	string	错误描述	网络错误

networkStateNotify

其他用户断线了会触发 networkStateNotify 接口。根据接口参数 state 判断其他玩家当前的状态。

response.networkStateNotify(netnotify:MsNetworkStateNotify);

参数 MsNetworkStateNotify 的属性

参数	类型	描述
roomID	string	房间ID
userID	number	断开网络的玩家ID
state	number	网络断开状态1-网络异常，正在重连 2-重连成功 3-重连失败，退出房间
owner	number	房主ID

示例代码

class MsEngine{
    ......
    public constructor(){
        this.response.networkStateNotify = ( netnotify:MsNetworkStateNotify )=>{
            if(state == 1){
                //netnotify.userID 用户掉线
            }else if(state == 2){
                //netnotify.userID 用户重新登录了游戏，但是还没有重连进房间
            }else{
                //netnotify.userID 用户已经退出房间了
            }
        };
        
        this.response.errorResponse = (errCode:number, errMsg:string)=>{
            //发生错误 errCode + errMsg
        };
    }
}

踢除玩家

在房间没有关闭状态下，在房间中的任何人都可以把其他人踢出房间。参数 userID 可以是房间内任意一个，自己也可以剔除自己。主要剔除方式由开发者自己制定。

请求接口：kickPlayer
回调接口：kickPlayerResponse

kickPlayer

engine.kickPlayer(userID:number, cpProto:string);

参数

参数	类型	描述	示例值
userID	number	被踢除玩家ID	655444
cpProto	string	附加消息	“kick”

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-6	未加入房间
-21	data 过长，不能超过1024个字符

kickPlayerResponse

response.kickPlayerResponse(rsp:MsKickPlayerRsp);

参数 MsKickPlayerRsp 的属性

参数	类型	描述
status	number	接口状态 200 成功； 400 客户端参数错误；404 用户或房间不存在
owner	nunber	房主ID
userID	number	被踢玩家ID

kickPlayerNotify

response.kickPlayerNotify(knotify:MsKickPlayerNotify)

参数 MsKickPlayerNotify 的属性

参数	类型	描述
userID	number	被踢玩家ID
srcUserID	number	发起踢人玩家ID
cpProto	string	附加消息
owner	number	房主ID

示例代码

class MsEngine{
    ......
    public constructor(){
        this.response.kickPlayerResponse = ( rsp:MsKickPlayerRsp )=>{
            if(rsp.status == 200){
                //rsp.userID 用户被踢掉
            }else{
                //用户踢除失败
            }
        };
        
        this.response.kickPlayerNotify = (knotify:MsKickPlayerNotify)=>{
            //srcUserID 把userID 踢掉了
        };
    }

    public kickPlayer(){
        this.engine.kickPlayer(123,"不想和你一起玩")
    }
}

分组订阅

分组订阅功能就是群组功能，使用 subscribeEventGroup 接口加入订阅组。一个玩家可以订阅多个分组。

请求接口：subscribeEventGroup
回调接口：subscribeEventGroupResponse

subscribeEventGroup

engine.subscribeEventGroup(confirms:Array<string>, cancles:Array<string>):number

参数

参数	类型	描述	示例值
confirms	Array	要订阅的组名	["1344333","matchvs1"]
cancles	Array	要取消订阅的组名	["matchvs","4654"]

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-6	未加入房间
-20	confirms 和 cancles 不能都为空

subscribeEventGroupResponse

response.subscribeEventGroupResponse(status:number, groups:Array<string>);

参数

参数	类型	描述	示例值
status	number	状态值：成功200，其他失败	200
groups	Array	订阅的组	["MatchVS"]

示例代码

class MsEngine{
    ......
    public constructor(){
        this.response.subscribeEventGroupResponse = ( status:number, groups:Array <string> )=>{
            if(status == 200){
                //订阅成功
            }else{
                //订阅失败
            }
        };
    }

    public subscribeEventGroup(){
        this.engine.subscribeEventGroup(["MatchVS"],[]);
    }
}

分组订阅消息发送

加入同一个组的玩家是可以相互广播消息，其他没有加入该组的玩家是收不到组消息的。发送组消息使用 sendEventGroup 接口。消息分组发送可以根据 groups 参数发送多个分组。

请求接口：sendEventGroup
回调接口：sendEventGroupResponse

sendEventGroup

engine.sendEventGroup(groups:Array<string>, data:string):number

参数

参数	类型	描述	示例值
data	string	发送的数据	“hello matchvs”
groups	Array	发送的分组	["MatchVS"]

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-6	未加入房间
-20	groups 不能都为空
-21	data 过长（1K）

sendEventGroupResponse

调用 sendEventGroup 接口发送消息成功会收到sendEventGroupResponse的回调。dstNum表示这个分组消息会有多少个人收到。

response.sendEventGroupResponse(status:number);

参数

参数	类型	描述	示例值
status	number	状态值 200成功，其他失败	200
dstNum	number	将被发送给多少个客户端	3

sendEventGroupNotify

多个用户在同一个分组时，有一个用户发送消息，那么其他用户就会收到 sendEventGroupNotify 的异步回调。

response.sendEventGroupNotify(srcUid:number, groups:Array<string>, cpProto:string);

参数

参数	类型	描述	示例值
srcUserID	number	消息来源用户	277773
groups	Array	消息来源分组	["MatchVS"]
cpProto	string	负载消息	"test"

示例代码

class MsEngine{
    ......
    public constructor(){
        this.response.sendEventGroupResponse = ( status:number)=>{
            if(status == 200){
                //成功
            }else{
                //失败
            }
        };
        this.response.sendEventGroupNotify = (srcUserID:number, groups:Array<string>, cpProto:string)=>{
            //有人发送组消息
        };
    }

    public sendEventGroup(){
        this.engine.sendEventGroup(["MatchVS"], "hello matchvs");
    }
}

帧同步

Matchvs提供了帧同步的功能，开发者可以让房间内的玩家保持帧同步。 Matchvs 所提供的帧同步能力，让您可以根据游戏需要，直接设置同步帧率，比如10帧每秒，然后您可以调用发送帧同步数据的接口来发送逻辑帧数据。 Matchvs 会缓存每100毫秒的数据，将这100毫秒的数据作为一帧发给各个客户端。

请求设置帧同步：setFrameSync
帧同步设置回调：setFrameSyncResponse
设置帧同步异步回调：setFrameSyncNotify
发送帧同步请求：sendFrameEvent
发送帧同步回调：sendFrameEventResponse
帧数据更新回调：frameUpdate

setFrameSync

设置帧同步速率，发送帧同步消息之前一定要先设置帧同步。帧同步最大值为20。也就是 50ms 发送一次数据。

engine.setFrameSync(frameRate:number，enableGS?:number, other?:any ):number

参数

参数	类型	描述	示例值
frameRate	number	帧率: 0关闭。其他值表示帧率	10
enableGS	number	是否启用gameServer帧同步 0-启用 1-不启用	0
other	object	其他数，目前包含一个值：cacheFrameMS断线后缓存帧数据的时间，只有帧同步有效，单位毫秒，最多有效一个小时	{cacheFrameMS:10000}

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-6	未加入房间
-20	frameRate 不能超过 20，不能小于0

setFrameSync 设置帧率，参数值设置 0表示关闭，参数值大于0表示打开，不调用为关闭。帧率须能被1000整除

setFrameSyncResponse

response.setFrameSyncResponse(rsp:MsSetChannelFrameSyncRsp);

参数 MsSetChannelFrameSyncRsp的属性

参数	类型	描述	示例值
status	number	状态：200 成功；519 重复设置；500 帧率需被1000整除	200

setFrameSyncNotify

设置帧同步异步回调同时会回调给自己。可能是gameServer 设置的帧同步，也可以是玩家设置的帧同步。

response.setFrameSyncNotify(rsp:MVS.MsSetFrameSyncNotify);

参数 MsSetFrameSyncNotify属性

参数	类型	描述	示例值
frameRate	number	帧率	10
startIndex	number	序号	1
timestamp	string	时间戳
enableGS	number	是否启用gameServer帧同步 0-启用 1-不启用	0
cacheFrameMS	number	断线后缓存帧数据的时间，只有帧同步有效，单位毫秒，最多有效一个小时	10000

sendFrameEvent

发送帧同步数据，调用 sendFrameEvent 接口之前一定要先设置帧率。

    /**
     * 发送帧同步消息
     * @param {string|Uint8Array} cpProto
     * @param {MVS.FrameOpt} op  0-只发送客户端 1-只发送GS 2-客户端和GS
     * @param {boolean} isBinary 是否以二进制发送,如果是,cpProto必须是Uint8Array类型
     * @returns {number}
     */
    sendFrameEvent(cpProto:string|Uint8Array, op?:number, isBinray?:boolean):number

返回值

错误码	含义
0	成功
-1	失败
-2	未初始化
-3	正在初始化
-4	未登录
-7	正在创建或者进入房间
-6	未加入房间
-21	cpProto 过长，不能超过1024字符

sendFrameEventResponse

帧消息发送回调，用来检测帧消息是否发送成功。

response.sendFrameEventResponse(rsp:MsSendFrameEventRsp);

MsSendFrameEventRsp 的属性

参数	类型	描述	示例值
status	number	状态值 200成功	200

frameUpdate

帧消息下发，根据设置的帧率来下发玩家发送的帧消息，比如设置的帧率为10(100ms/次) ，那么frameUpdate接口会 100ms 触发一次，把在这段时间缓存的所有数据一次性下发（包括自己发送的帧消息）。

response.frameUpdate(data:MsFrameData);

参数 MsFrameData 的属性

参数	类型	描述
frameIndex	number	帧序号
frameItems	Array	同步帧内的数据包数组
frameWaitCount	number	同步帧内的数据包数组数量

MsFrameItem 的属性

参数	类型	描述
srcUserID	number	用户ID
cpProto	string	附加消息
timestamp	string	时间戳

示例代码

class MsEngine{
    ......
    public constructor(){
        this.response.setFrameSyncResponse = ( rsp:MsSetChannelFrameSyncRsp)=>{
            if(rsp.status == 200){
                //设置帧率成功
            }else{
                //设置帧率失败
            }
        };
        this.response.sendFrameEventResponse = (rsp:MsSendFrameEventRsp)=>{
            if(rsp.status == 200){
                //发送帧消息成功
            }else{
                //发送帧消息失败
            }
        };
        this.response.frameUpdate = (data:MsFrameData)=>{
            //收到帧数据，这里处理
        };
    }
    public setFrameSync(){
        this.engine.setFrameSync(10,0, {cacheFrameMS:10000});
    }

    public sendFrameEvent(){
        this.engine.sendFrameEvent("hello matchvs");
    }
}

断线重连

用户断线后可以调用次接口进行重连，重连具体教程可以参考断线重连详细文档。

请求重连接口：reconnect, setReconnectTimeout，getOffLineDataResponse
重连回调接口：reconnectResponse, setReconnectTimeoutResponse，getOffLineDataResponse

reconnect

用户在中途断线后服务器会默认保存用户20秒在房间状态，20秒内用户可以重新登录连接到原来的房间里面。
在游戏里面如果网络断开，可以调用 reconnect 函数重新连接，断线重新连接分为两种情况，第一种没有重新启动程序：在游戏进行时网络断开，直接调用 reconnect 重新连接到游戏。第二种重新加载程序：先调用login 然后判断 loginResponse 中的参数 roomID 是否为0 如果不为 0 就调用reconnect 重连到房间
reconnect 接口调用，其他玩家收到 netWorkStateNotify 接口信息，接口详情请看netWorkStateNotify的接口说明。

engine.reconnect():number;

参数

无

返回值

错误码	含义
0	成功
-1	其他错误
-2	未初始化
-9	正在重连

reconnectResponse

response.reconnectResponse(status:number, roomUserInfoList:Array<MsRoomUserInfo>, roomInfo:MsRoomInfo);

参数

参数	类型	描述	示例值
status	number	状态返回，200表示成功， 201-重连房间失败但是处于登录状态，其他失败	200
roomUserInfoList	Array	房间内玩家信息列表
roomInfo	MsRoomInfo	房间信息构成的对象

MsRoomUserInfo 的属性

属性	类型	描述	示例值
userID	number	用户ID	32322
userProfile	string	玩家简介	""

MsRoomInfo 的属性

属性	类型	描述	示例值
roomID	string	房间号	238211
roomProperty	string	房间属性	""
owner	number	房间创建者的用户ID	0

setReconnectTimeout

用户进入房间后默认断线20秒会被剔除，在用户加入房间之前调用这个接口，服务就会从新设置断线重连时间，设置范围为 -1到600 秒 如果设置的值为-1, 则在用户断开就马上被踢出房间;设置为0则20秒后踢出。

setReconnectTimeout(timeout:number):number

参数

参数	类型	描述	示例值
timeout	number	断线重连超时时间	60

返回值

返回码	说明
0	接口调用成功
-2	未初始化
-3	正在初始化
-4	未登录
-5	正在登录
-7	正在创建房间，或者正在加入游戏房间
-6	没有进入房间
-10	正在离开房间
-11	正在登出
-12	正在加入观战房间
-27	timeout 超出范围 0=< timeout <=600
-30	设置的 rType 值与当前模式冲突。

setReconnectTimeoutResponse

设置重连时间回调

response.setReconnectTimeoutResponse(status:number):void

参数

参数	类型	描述	示例值
status	number	状态值 200 设置成功	200

getOffLineData

获取断线期间的帧数据，只有在开启了帧同步的时候使用，调用这个接口后，在断线期间游戏的数据会通过 frameUpdate 接口返回指定时间内的数据。

engine.getOffLineData(cacheFrameMS:number)

参数

参数	类型	描述	示例值
cacheFrameMS	number	获取断线多久之内的缓存数据，上限为1个小时与setFrameSync 接口中的参数同步最好，cacheFrameMS 为-1 代表获取缓存这个房间里面所有的缓存帧数据，同时 setFrameSync 接口也要设置为 -1	10000

返回码

略可参考其他接口的返回码。

getOffLineDataResponse

调用 getOffLineData 接口获取断线期间的帧数据，这个接口会返回是否调用成功通知和，缓存的帧数据数量。

response.getOffLineDataResponse(rsp)

参数 rsp 属性

属性	类型	描述	示例值
status	number	状态值	200
frameCount	number	当前游戏帧索引号	10
msgCount	number	消息数量	20

重新打开房间

请求接口：joinOpen
回调接口：joinOpenNotify、joinOpenResponse

joinOpen

设置房间重新打开,允许他人匹配加入当前房间, 注意 在房间的情况才可以调用,否则函数直接返回错误码

	/**
     * 设置允许房间加人
     * @param {number} cpProto
     * @returns {number}
     */
    joinOpen(cpProto:string):number

参数

cpProto: 附带信息,会通过joinOpenNotify广播给其他人

返回值

0为正确,其他请参考错误码

joinOpenNotify&joinOpenResponse

参数

//数据结构
declare class MsReopenRoomResponse {
    public status  : number;
    public cpProto : string;
	constructor(status:number, cpProto:string)
}
declare class MsReopenRoomNotify{
    public roomID  : string;
    public userID  : number;
    public cpProto : string;
	constructor(roomID:string,userID:number, cpProto:string)
}

	
 /**
 * 允许房间加人的通知
 * @param {MsReopenRoomNotify} data
 */
joinOpenNotify(data:MsReopenRoomNotify);
	
 /**
 * 设置允许房间加人的结果
 * @param {MsReopenRoomResponse} data
 */
joinOpenResponse(data:MsReopenRoomResponse);

MsReopenRoomResponse

属性	类型	描述	示例值
status	number	接口调用的服务器返回码,200为正确	200
cpProto	string	调用者附带的信息	""

MsReopenRoomNotify

属性	类型	描述	示例值
roomID	string	房间号	"123123123"
cpProto	string	调用者附带的信息	""
userID	number	调用者用户ID	0

示例代码

 		var checkbox = new eui.CheckBox();
        checkbox.label = "允许加入";
        checkbox.addEventListener(egret.Event.CHANGE, e => {
            checkbox.label = checkbox.selected ? "允许加入" : "不允许加入";
            checkbox.selected ? GameData.engine.joinOpen("x") : GameData.engine.joinOver("x");
        }, this);
        checkbox.x = 50;
        checkbox.y = 50;
        this.addChild(checkbox);

        GameData.response.joinOpenNotify = function (d) {
            Toast.show(d.userID + " 设置了允许房间加人");
            checkbox.selected = true;
        }
        GameData.response.joinOpenResponse = function (d) {
            Toast.show(" 设置允许房间加人 " + (d.status == 200 ? "success" : "fail"));
            checkbox.selected = ((d.status == 200)?true:checkbox.selected);
        }
        GameData.response.joinOverNotify = function (d) {
            Toast.show(d.srcUserID + " 设置了不允许房间加人");
            checkbox.selected = false;
        }
        GameData.response.joinOverResponse = function (d) {
            Toast.show(" 设置不允许房间加人 " + (d.status == 200 ? "success" : "fail"));
            checkbox.selected = ((d.status == 200)?false:checkbox.selected);
        }

获取观战房间列表

请求接口：getWatchRoomList
回调接口：getWatchRoomsResponse

getWatchRoomList

获取可以观战房间的列表信息。可观战的房间是由 createRoom 接口创建，并且 canWatch 参数配置为可观战模式。

engine.getWatchRoomList(filter:MsRoomFilterEx)

参数 MsRoomFilterEx

参数	类型	描述	示例值
maxPlayer	number	房间最大人数 (0-全部)	3
mode	number	模式（0-全部）*创建房间时，mode最好不要填0	0
canWatch	number	是否可以观战 0-全部 1-可以 2-不可以	1
roomProperty	string	房间属性	“roomProperty”
full	number	0-全部 1-满 2-未满	0
state	number	0-全部 1-开放 2-关闭	0
sort	number	0-不排序 1-创建时间排序 2-玩家数量排序 3-状态排序	0
order	number	0-ASC 1-DESC	0
pageNo	number	页码，0为第一页	0
pageSize	number	每一页的数量应该大于 0	10

返回值

返回码	说明
0	接口调用成功
-2	未初始化
-3	正在初始化
-4	未登录
-5	正在登录
-7	正在创建房间，或者正在加入游戏房间
-11	正在登出
-12	正在加入观战房间

getWatchRoomsResponse

获取观战列表房间回调

getWatchRoomsResponse(rooms:MsGetRoomListExRsp);

参数

参数	类型	说明	示例值
rooms	MsGetRoomListExRsp	获取观战房间列表回调信息

MsGetRoomListExRsp

参数	类型	说明
status	number	接口调用状态 200 成功，其他值请看错误码说明
total	number	房间
roomAttrs	Array	房间信息列信息

MsRoomAttribute 属性可以参考 getRoomListExResponse 接口。

示例代码

class MsEngine {
    public GetWatchRooms(){
        this.response.getWatchRoomsResponse = (rooms)=>{
            if(status == 200){
                console.log("当前房间数量："，total);
                roomAttrs.forEach((e)={
                    console.log("房间信息："，JSON.stringify(e));
                });
            }
        }
        
        var filter = new MsRoomFilterEx(3, 0, 1, "roomProperty", 0, 1, 0, 0, 0, 3);
        engine.getWatchRoomList(filter);
    }
}

加入观战房间

请求接口：joinWatchRoom
回调接口：joinWatchRoomResponse, joinWatchRoomNotify

joinWatchRoom

加入观战房间请求接口，观战房间必须是在 getWatchRoomsResponse 接口中获取到的房间。

joinWatchRoom(roomID:string, userProfile:string):number

参数

参数	类型	说明	示例值
roomID	string	有效的房间号 (房间必须是可观战房间)在调用createRoom的时候设置
userProfile	string	附加信息

返回值

返回码	说明
0	接口调用成功
-2	未初始化
-3	正在初始化
-4	未登录
-5	正在登录
-7	正在创建房间，或者正在加入游戏房间
-8	已经在(观战)房间
-10	正在离开房间
-11	正在登出
-12	正在加入观战房间
-14	正在观战离开房间

joinWatchRoomResponse

加入观战房间回调函数，调用 joinWatchRoom 接口后通过这个接口告知加入结果

joinWatchRoomResponse(rsp:MVS.MsJoinWatchRoomRsp):void

参数

参数	类型	说明	示例值
rsp	MVS.MsJoinWatchRoomRsp

MVS.MsJoinWatchRoomRsp

参数	类型	说明	示例值
status	number	状态值 200 成功，其他错误值请看错误码文档	200
roomStatus	number	当前房间状态
reserved
wathchInfo	MVS.MsLiveWatchInfo	观战房间信息

MVS.MsLiveWatchInfo

参数	类型	说明
roomID	string	房间ID
startTS	string	游戏开始时间
delayMS	number	延迟时间（观战延缓的时间，不与游戏当前进度同步）
cacheMS	number	缓存时间
maxAudiences	number	最大观战
curAudiences	number	当前观战
peakAudiences	number
lastAudiences	MVS.MsLiveAudience	观战列表信息

MVS.MsLiveAudience

参数	类型	说明	示例值
userID	number	用户ID	123456
profile	string	用户附带消息	“hello”
enterTime	string	进入时间

joinWatchRoomNotify

加入观战房间异步回调

joinWatchRoomNotify(user:MsRoomUserInfo):void

参数

参数	类型	说明	示例值
user	MsRoomUserInfo	用户信息

MsRoomUserInfo

属性	类型	描述	示例值
userID	number	用户ID	32322
userProfile	string	玩家简介	""

示例代码

class MsEngine{
    public JoinWatch(){
        this.response.joinWatchRoomResponse = (status)=>{
            if(status == 200){
                console.log("加入观战房间成功");
            }
        }
        this.response.joinWatchRoomNotify = (user)=>{
            console.log("用户加入观战：",user.userID);
            console.log("用户加入观战时附带的信息：",user.userProfile);
        }
        
        let resNo = this.engine.joinWatchRoom("12345678900000000", "nickName+avatar");
        if(resNo = 0){
            console.log("OK");
        }
    }
}

获取观战数据

请求接口：setLiveOffset
回调接口：setLiveOffsetResponse, liveFrameUpdate

setLiveOffset

设置观战数据偏移位置，指定从哪里开始播放。

setLiveOffset(offsetMS:number):number

参数

参数	类型	说明	示例值
offsetMS	number	偏移时间，-1 表示从头， 0 表示不追， >0 表示最近多少ms	-1

返回值

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

setLiveOffsetResponse

设置观战数据偏移位置接口请求回调函数。

setLiveOffsetResponse(status:number):void

参数

参数	类型	说明	示例值
status	number	200 成功，其他错误值请看错误码文档	200

liveFrameUpdate

设置观战数据偏移值后，在游戏中对战的数据就会通过这个接口根据游戏的帧率返回数据。游戏帧率设置是 setFrameSync 接口。

liveFrameUpdate(data:MsFrameData):void

参数

参数	类型	说明	示例值
data	MsFrameData	游戏帧数据

MsFrameData

参数	类型	描述
frameIndex	number	帧序号
frameItems	Array	同步帧内的数据包数组
frameWaitCount	number	同步帧内的数据包数组数量

MsFrameItem 的属性

参数	类型	描述
srcUserID	number	用户ID
cpProto	string	附加消息
timestamp	string	时间戳

示例代码

class MsEngine{
    public SetLiveOffset(){
        this.response.setLiveOffsetResponse = (status)=>{
            if(status == 200){
                console.log("设置观战数据偏移位置成功");
            }
        }
        
        this.response.liveFrameUpdate = (data)=>{
            var i = 0;
            while ( i < data.frameItems.length){
                console.log("[Rsp]liveFrameUpdate cpProto:"+ data.frameItems[i++].cpProto );
            }
        }
        
        var resNo = this.engine.setLiveOffset(-1);
        if(resNo == 0){
            console.log("OK");
        }
    }
}

角色游戏与观战切换

请求接口：changeRole
回调接口：changeRoleResponse

changeRole

游戏角色与观战者角色的身份转换请求接口。在游戏中，如果需要转换为观战者就需要调用该接口，反之如果观战者需要加入游戏中也要调用此接口。切换角色的时候会在产生changeRole 回调后，根据不同的模式分别触发 joinRoomResponse 和joinWatchRoomResponse 回调接口。

changeRole(userProfile:string, rType:number):number

参数

参数	类型	描述	示例值
userProfile	string	附带消息，默认填空值	""
rType	number	要转换的模式，0-切换到游戏模式，1-切换到观战模式，这是一个可选参数，如果不填该参数，接口会根据你当前处于什么模式自动转换。	1

返回值

返回码	说明
0	接口调用成功
-2	未初始化
-3	正在初始化
-4	未登录
-5	正在登录
-7	正在创建房间，或者正在加入游戏房间
-6	没有进入房间
-10	正在离开房间
-11	正在登出
-12	正在加入观战房间
-30	设置的 rType 值与当前模式冲突。
-1	其他错误

changeRoleResponse

切换角色游戏模式与观战模式请求接口回调

changeRoleResponse(status:MVS.MsChangeRoleRsp):void

参数

参数	类型	描述	示例值
rsp	MVS.MsChangeRoleRsp	角色切换回调信息

MVS.MsChangeRoleRsp

参数	类型	描述	示例值
status	number	200 成功，其他错误值请看错误码文档	200
targetRoomType	number	当前的模式 0-游戏模式 1-观战模式	0

示例代码

class MsEngine{
    pbulic ChangeRole(){
        this.response.changeRoleResponse = (rsp)=>{
            if(rsp.status == 200){
                console.log("成功切换到");
            }
        }
        var resNo = this.engine.changeRole("ChangeRole",1);
        if(resNo == 0){
            console.log("OK");
        }
    }
}

离开观战房间

请求接口：leaveWatchRoom
回调接口：leaveWatchRoomResponse

leaveWatchRoom

离开观战房间请求接口。

leaveWatchRoom(cpProto:string):number

参数

参数	类型	描述	示例值
cpProto	string	附加值默认填空值	“”

返回值

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

leaveWatchRoomResponse

离开观战房间回调

leaveWatchRoomResponse(status:number):void

参数

参数	类型	描述	示例值
status	number	200 成功，其他错误值请看错误码文档	200

leaveWatchRoomNotify

离开观战房间请求异步回调，其他观战者可收到这个回调。

leaveWatchRoomNotify(user:MVS.MsExitLiveRoomNotify):void

参数

参数	类型	描述	示例值
user	MVS.MsExitLiveRoomNotify	离开房间的用户信息

MVS.MsExitLiveRoomNotify

属性	类型	描述	示例值
userID	number	用户ID	32322
userProfile	string	玩家简介	""

代码示例

class MsEngine{
    public LeaveWatchRoom(){
        this.response.leaveWatchRoomNotify = (user)=>{
            console.log("用户离开观战：",user.userID)；
            console.log("用户离开时附带的信息：",user.userProfile)
        }
        
        this.response.leaveWatchRoomResponse = (status)=>{
            if(status == 0){
                console.log("退出观战房间成功");
            }
        }
        
        let resNo = this.engine.leaveWatchRoom("leaveWatchRoom");
        if(resNo == 0){
            console.log("ok");
        }
    }
}

日志开关

MatchvsLog.closeLog()

关闭Matchvs日志输出。

MatchvsLog.openLog()

打开Matchvs日志输出。

CHANGELOG

时间：2018.08.20

版本：v.3.7.4.0

1、QQ玩一玩适配
2、新增503、504等错误码描述。
3、新增cocos、egret渠道游戏账号区分。

时间：2018.07.13

TSSDK版本：v3.7.3.0+

1. 新增 joinRoomResponse 接口参数 state
2. 所有包含userId参数的数据类型都新增了一个userID字段，原来userId也存在，建议使用userID。

时间：2018.05.29

TSSDK版本：v1.6.202

1. 新增joinOpen 房间重新打开功能
2. 修复微信小游戏真机断线问题
3. 调整微信小游戏适配机制,只需引用matchvs.all.js,不再引用matchvs.all.weixin.js
4. 修复Egret打包H5平台 `找不到 wx define` 的问题
5. 修复uninit后不能后登录的问题
6. 修复被kickPlayer后不能进入房间,返回-8或-10的问题.
7. 代码优化,减少代码体积

时间：2018.05.02

TSSDK版本：v1.6.1+

1、新增日志控制类型 MatchvsLog,用于打开或者关闭 sdk 的日志输出

时间：2018.05.29

TSSDK版本：v1.6.202

1. 新增joinOpen 房间重新打开功能
2. 修复微信小游戏真机断线问题
3. 调整微信小游戏适配机制,只需引用matchvs.all.js,不再引用matchvs.all.weixin.js
4. 修复Egret打包H5平台 `找不到 wx define` 的问题
5. 修复uninit后不能后登录的问题
6. 修复被kickPlayer后不能进入房间,返回-8或-10的问题.
7. 代码优化,减少代码体积

时间：2018.04.17 TSSDK版本：JSSDK_v1.6.x

1、新增断线重连接口 reconnect 和回调接口 reconnectResponse

时间：2018.04.13

TSSDK版本：JSSDK_v1.5.X

内容：

1、新增 功能接口 setRoomProperty 和回调 setRoomPropertyResponse、setRoomPropertyNotify 。

时间：2018.03.30

TSSDK版本：JSSDK_v1.4.x

内容：

1、新增 getRoomListEx 和 getRoomListExResponse接口
2、新增 getRoomDetail 和 getRoomDetailResponse接口
3、新增 joinOverNotify 接口
4、优化 kickPlayerResponse 接口，添加参数 被踢者userID
5、添加 netWorkStateNotify 异步回调接口说明
6、添加 gameServerNotify 接收gameServer 推送消息接口
7、优化 .d.ts 文件 中 sendEventGroupNotify 返回参数与 js文件不一致问题。
8、新增接口调用错误码返回

97 KiB Raw Blame History Unescape Escape

API 说明

初始化

init

参数：

错误码：

premiseInit

参数

返回值

initResponse

参数

示例代码

反初始化

uninit

错误码

注册用户

registerUser

返回值

registerUserResponse

参数MsRegistRsp类的属性

示例代码

登录

login

参数

返回值

loginResponse

参数 MsLoginRsp 类的属性

示例代码

登出

logout

参数

返回值

logoutResponse

参数

加入房间

joinRandomRoom

参数

返回值

joinRoomWithProperties

参数

MsMatchInfo 的属性

MVS.MsWatchSet 的属性

返回值

createRoom

参数

MsCreateRoomInfo 的属性

MVS.MsWatchSet

返回值

createRoomResponse

MsCreateRoomRsp 属性

joinRoom

参数

返回值

joinRoomResponse

参数

MsRoomUserInfo 的属性

MsRoomInfo 的属性

joinRoomNotify

参数

示例代码

关闭房间

joinOver

参数

返回值

joinOverResponse

MsJoinOverRsp的属性

joinOverNotify

参数 MsJoinOverNotifyInfo 的属性

示例代码

离开房间

leaveRoom

参数

返回值

leaveRoomResponse

参数MsLeaveRoomRsp的属性

leaveRoomNotify

参数 MsLeaveRoomNotify 属性

示例代码

获取房间列表

getRoomList

97 KiB

Raw Blame History