MatchVS [Java] 接入指引-对战引擎

MatchVS对战引擎

接入指引

（ForAndroid）

版本：V1.2.6

欢迎加入MatchVS开发者平台，本文档描述了MatchVS对战引擎（本文以下简称之为“MatchVS”）与游戏开发商（本文以下简称之为“开发者”）游戏接入的使用指引，供产品及技术人员参看。

请开发者在查看本文档后，及时反馈开发进度表（包含研发、联调与上线内测），以便我们安排人员技术支持与提前准备上线等事宜。

?MatchVS –对战引擎–产品技术文档

目录

MatchVS介绍 (5)

什么是MatchVS？ (5)

MatchVS能帮开发者做什么？ (5)

网络对战 (5)

社区化用户体系 (5)

增值服务 (5)

对战数据分析 (5)

快速开始 (6)

获取MatchVS开发包 (6)

接入功能介绍 (6)

如何选择接入功能？ (6)

成为开发者 (7)

为游戏获取MatchVS_APP_KEY (7)

对战前的准备 (7)

项目配置 (7)

用户登录 (8)

初始化引擎 (9)

注册对战事件监听 (9)

快速战斗 (10)

进入游戏大厅 (10)

匹配房间并快速开始游戏 (11)

进入房间 (11)

监听房间用户变化 (12)

准备/开始游戏 (13)

获取用户信息 (13)

数据传输 (15)

提高数据传输质量 (16)

结果仲裁 (17)

MatchVSScore？ (17)

让对战更有趣 (18)

不同的游戏场 (18)

比赛 (19)

货币&支付功能 (20)

如何充钱？ (20)

支付方式 (21)

关于计费点（chargePoint） (21)

关于平台币钻石 (21)

充值回调服务器 (21)

关于订单查询 (22)

使用K码 (22)

有了钱怎么花？ (23)

查看自己的背包 (23)

消费商品 (24)

兑换商品 (24)

其他货币&支付功能 (25)

运行环境切换 (26)

GL线程处理 (27)

GL线程自动切换 (27)

错误码 (27)

加入MatchVS对战平台大家庭 (28)

跨设备对战 (28)

对战社区整合 (28)

自定义排行榜 (28)

第三方账号支持 (28)

MatchVS介绍

什么是MatchVS？

MatchVS是一款全新的功能强大的对战引擎，它致力于向广大游戏开发者提供优质的游戏网络对战服务。使用了MatchVS的服务，游戏开发者可以将单机游戏快速便捷的改造为网络对战游戏。MatchVS不断优化网络结构，均衡负载，优化对战匹配及数据延迟，为开发者及玩家提供稳定高质量的游戏服务。

MatchVS能帮开发者做什么？

网络对战

MatchVS提供了一整套游戏的网络对战服务，从构建游戏大厅到匹配玩家（进入房间），从游戏数据传输到游戏结果仲裁。MatchVS细化了游戏网络对战的每一个环节，为开发者提供了方便简洁的接口。

在服务器方面，高性能的分布式架构，快速有效的扩容方案，保证网络服务的稳定及高效，开发者只用专注于游戏本质，于MatchVS共同向玩家提供优质的游戏体验。

社区化用户体系

MatchVS提供了一套用户体系供开发者使用，默认的游客账户静默登录，对用户零打扰，方便快捷。同时，MatchVS也整合了微信、百度等第三方账号，丰富用户的选择。另外，MatchVS特别为TV及智能盒子提供了二维码扫描登录，大大优化了登录体验。

MatchVS提供游戏对战排行，玩家也可以相互分享对战经历。在未来，MatchVS将不断完善社区化服务，为玩家及开发者提供更优质的服务。

增值服务

MatchVS支持并帮助开发者提供游戏增值服务。为此，MatchVS不断整合各种支付渠道，为开发者提供统一便捷的支付接口。开发者甚至可以选择通过MatchVS来管理游戏商品，游戏完全摆脱服务器开发，真正意义上做到只专注游戏质量。

对战数据分析

MatchVS将为开发者提供可视化的数据分析，从对战流程到用户分析，从消费数据到财务统计。

快速开始

获取MatchVS开发包

开发者可以从MatchVS平台网站或者官方客服处获取到最新的MatchVS开发包。

开发包包括如下内容：

docs（文档）

↓对战引擎接入指引vXXX.docx

↓接口说明-对战vXXX.docx

↓接口说明-用户vXXX.docx

↓接口说明-货币&支付vXXX.docx

libs（库）

↓afinal_0.5.1_bin.jar

↓gson-2.3.jar

↓MatchVSBasic.jar

↓MatchVSSDK.jar

↓MatchVSCurrency.jar

↓armeabi-v7a/libKOFrameWork.so

↓armeabi-v7a/libGameHelper.so

其中MatchVS*.jar和*.so 为MatchVS功能接口库，开发者可以根据需要选择引用。如果开发者使用了更高版本的afinal和gson，可以不用引入afinal和gson。

接入功能介绍

MatchVS开发包包含以下功能：

用户，包含用户登录、用户信息获取

对战引擎

货币&支付，包含支付及商品的兑换&消费，此功能可选。

如何选择接入功能？

MatchVS对战引擎基础库包含：

afinal_0.5.1_bin.jar

gson-2.3.jar

MatchVSBasic.jar

MatchVSSDK.jar

armeabi-v7a/libKOFrameWork.so

armeabi-v7a/libGameHelper.so

它们包含了MatchVS用户体系及对战引擎的全部功能，如果开发者还需要使用MatchVS的货币&支付功能，可以选择引入MatchVSCurrency.jar。

成为开发者

成为MatchVS开发者，获取MatchVS开发者的唯一ID (developerID)，在成为开发者后，可以向MatchVS提交游戏应用，MatchVS会为每一款游戏生成一个唯一的游戏ID (GameID)，到此，开发者可以开始为对战做准备了！

为游戏获取MatchVS_APP_KEY

(注：v1.2.6之前的版本，MatchVS采用KO_APP_KEY)

自v1.2.6开始，MatchVS的合作授权改为MatchVS_APP_KEY

开发者需要进入https://www.wendangku.net/doc/328133732.html,，注册成为MatchVS会员，并提交游戏信息，即可获取与游戏绑定的MatchVS_APP_KEY，需提交的游戏信息包括：

游戏名称，提交后不可修改

应用包名，如com.matchvs.game，提交后不可修改

合作方式，对战或联运，提交后不可修改

对战游戏，还需要设置对战结果配置及对战排行数据配置，详情见后文。

在提交上述内容后，会给合作商的游戏分配唯一的MatchVS_APP_KEY，此MatchVS_APP_KEY 用于识别唯一的MatchVS游戏。

注意：合作商在拥有多款不同的游戏时，需要为每一款游戏申请MatchVS_APP_KEY。

对战前的准备

项目配置

合作商根据需要将库文件拷贝如应用中的libs目录下，之后需要将申请到的MatchVS_APP_KEY增加到应用项目的AndroidManifest.xml中，并且申请网络访问权限，具体如下：

android:name="MatchVS_APP_KEY">

其中，meta-data中的android:value中填写游戏的MatchVS_APP_KEY

必要的权限

用户登录

项目配置好后，马上可以试试用户登录吧～

MatchVS的账户包含游客账户和第三方绑定账号，当没有使用第三方平台（如微信、百度等）登录方式登录用户系统时，MatchVS默认使用游客账号登录。

MatchVS账户类型由MatchVS在其社区应用中控制，开发者不用关心具体的登录方式。

用户登录的具体方法如下：

（此方法在v1.2.2之后不再推荐）

/**

* 登录

* @param pContext

* @param pLoginType登录类型

* @param pCallback登录事件回调

*/

MatchVSUserCenter.getInstance().login(

Context pContext,

int pLoginType,

final MatchVSCallbackpCallback

)

(v1.2.2 版之后推荐使用此方法)

/**

* 登录

* @param pContext

* @param pCallback登录事件回调

*/

MatchVSUserCenter.getInstance().login(

Context pContext,

final MatchVSCallback pCallback

)

/**

* 以游客方式登录

*/

MatchVSUserCenter.LOGIN_TYPE_GUEST;

/**

* 以百度助手插件方式登录

*/

MatchVSUserCenter.LOGIN_TYPE_BAIDU_APPSEARCH;

登录成功后，用户信息会通过回调通知给开发者，通知内容为MatchVSUser对象，其中包含了：

用户ID，唯一，开发者可以用来绑定应用原生账号

用户昵称，UTF8字符串

用户头像，HTTP URL

Token，用户授权Token，用于后续其他接口的调用

登录类型

注意：由于百度手机助手账号的特殊性，开发者在使用该类型账号测试登录时，会返回游客账号，只有当应用被MatchVS约定的方式从百度手机助手拉起时才会返回正确的百度账号，因此，在测试阶段使用百度手机助手账号登录时收到游客类型账号是正常的。

初始化引擎

对战开始之前的最后一项准备工作，初始化对战引擎！

对战引擎相关的功能接口只有在初始化工作完成之后才能使用。对战引擎的初始化在应用生命周期中仅需调用一次。建议开发者在Application创建的时候(onCreate)调用初始化方法。

初始化具体方法如下：

/**

* 初始化SDK

* @param pApplication

* @return

*/

MatchVSEngine.getInstance().init(Application pApplication);

注册对战事件监听

初始化引擎之后，开发者可以在任何需要监听对战事件的地方注册时间监听器，此后对战事件会通知的所有注册监听器上。

(MatchVS SDK v1.2.2 及以下版本)

/**

* 注册监听

* @param pListener

* @return

*/

MatchVSEngine.getInstance().addMatchVSEngineListener(

IMatchVSEngineListenerpListener);

注册的监听可以通过removeMatchVSEngineListener方法来注销，建议开发者在注册事件监听时注意Context等变量的正确使用，以避免内存泄露的隐患。

IMatchVSEngineListener的具体内容请参开文档《MatchVS [Java] 接口说明-对战》

(MatchVS SDK v1.2.4及以上版本)

从v1.2.4开始，增加了新的监听器IMatchVSEngineExListener，它继承自IMatchVSEngineListener，它为开发者提供新的监听回调，主要是涉及房间用户及其状态变化的监听。IMatchVSEngineExListener监听的实例依旧可以通过MatchVSEngine.getInstance().addMatchVSEngineListener进行设置，开发者可以根据需要选择使用任意监听器。

IMatchVSEngineExListener的具体内容请参开文档《MatchVS [Java] 接口说明-对战》

快速战斗

准备工作都有完成，下面让我们看看如何快速开始战斗吧！

进入游戏大厅

首先，开发者需要先登录游戏大厅（Game Lobby），游戏大厅是所有玩家汇聚的地方，用户在这里相互发现，匹配房间，继而共同进行游戏。

开发者在进入大厅时，需要填写必要的信息，以告诉大厅后续的匹配如何进行下去。

开发者I D：成为开发者时获取

用户ID：登录获取

游戏ID：成为开发者后，提交游戏应用时获取

游戏对战版本号：从1开始，不同的游戏对战版本之间不可对战

用户授权Token：登录获取

其中，游戏对战版本默认从1开始，当开发者游戏版本迭代后出现高版本与低版本无法共同对战时，需要考虑递增游戏对战版本号

进入大厅具体方法如下：

/**

* 用户进入游戏大厅

* @param pDevelopID开发者ID

* @param pUserID用户ID

* @param pGameID游戏ID

* @param pGameVersion游戏对战版本号

* @param pToken用户授权Token

* @throws NotInitException未初始化错误

*/

MatchVSEngine.getInstance().enterLobby(

int pDevelopID,

int pUserID,

int pGameID,

int pGameVersion,

String pToken);

成功进入游戏大厅后，引擎回通过监听通知到开发者，具体监听为：IMatchVSEngineListener.onEnterLobbyRsp(MatchVSLoginRsppLobbyLoginRsp);

示例代码：

@Override

publicvoid onEnterLobbyRsp(MatchVSLoginRsppMatchVSLoginRsp) {

if (pMatchVSLoginRsp.rtn == MatchVSLoginRsp.CODE_LOGIN_SUCCESS) {

//登录大厅成功

} else {

//登录大厅失败

}

}

匹配房间并快速开始游戏

进入大厅完毕，赶快寻找其他玩家对战吧～

进入房间

匹配用户，或称进入房间，开发者在进入大厅之后，可以使用房间匹配接口（enterRoom）快速进入房间，根据游戏应用的不同，房间限制的人数也不同，当房间人数达到上限，其他用户将无法进入。

// 随机进入房间

// 当参数pRoomID为0时表示随机匹配房间

MatchVSEngine.getInstance().enterRoom(pRoomID);

// 进入房间结果，通过IMatchVSEngineListener.onEnterRoom通知到开发者

代码示例(1)：

@Override

publicvoid onEnterRoom(int pRoomID) {

if (pRoomID> 0) {

// 匹配房间成功

} elseif (pRoomID< 0) {

// 匹配房间失败

}

}

监听房间用户变化

第一个进入房间的用户会自动成为房主，随后进入的每一个用户，都会通过监听通知到其他用户。相同，用户的离开也会同样周知房间内剩余的用户。

// 房间用户变更，通过IMatchVSEngineListener.onRoomUsersChanged通知到开发者

代码示例(2)：

（MatchVS SDK v1.2.2及以下IMatchVSEngineListener）

@Override

publicvoid onRoomUsersChanged(MatchVSRoomUserState[] pRoomUserStates) {

// 每次都返回所有的房间成员及状态

// MatchVSEngine.ROOM_USER_STATE_NONE = 0 普通状态

// MatchVSEngine.ROOM_USER_STATE_READY = 1 已准备

// MatchVSEngine.ROOM_USER_STATE_PLAYING = 2 游戏中

for (MatchVSRoomUserStateuserState : pRoomUserStates) {

Log.d("MatchVSEngine", https://www.wendangku.net/doc/328133732.html,er_id + ":" + userState.state);

}

}

（MatchVS SDK v1.2.4及以上IMatchVSEngine Ex Listener）

@Override

publicvoid onRoomUserJoin(int[] pUserIDs) {

// 返回新进入房间的用户ID列表

}

@Override

publicvoid onRoomUserLeave(int[] pUserIDs) {

// 返回退出房间的用户ID列表

}

@Override

publicvoid onRoomUserReady(int[] pUserIDs) {

// 返回房间已准备用户ID列表状态 0 > 1

}

@Override

publicvoid onRoomUserCancelReady(int[] pUserIDs) {

// 返回房间取消准备的用户ID列表状态 1 > 0

}

@Override

publicvoid onRoomUserStart(int[] pUserIDs) {

// 返回房间开始游戏用户ID列表状态 1 > 2

}

开发者通过以上监听，获取到状态变化的用户ID列表，通过用户ID，开发者可以通过如下接口获取用户详情及用户状态

// 获取用户详情，包含用户昵称及头像，此方法使用了缓存机制，提高获取速度

MatchVSEngine.getInstance().getUserDetails(pUserID, pMatchVSCallback);

// 获取用户ID列表中合法用户的状态

MatchVSEngine.getInstance().getUserState(pUserIDs);

// 获取角色用户ID，如获取P1的用户IDgetRoleUserID(1)，0为该角色未有用户加入

// 角色与开发者游戏支持的最大游戏用户相关，如2人，则Role包含{1, 2}

MatchVSEngine.getInstance().getRoleUserID(pRoleID);

当房主用户离开房间时，房间剩余用户中会诞生新的房主，这个事件同样会通过监听通知到所有房间内的用户。

// 房间房主变更，通过IMatchVSEngineListener.onRoomMasterChanged通知到开发者

代码示例(3)：

@Override

publicvoid onRoomMasterChanged(int pUserID) {

Log.d(TAG, "Current Master :" + pUserID);

}

准备/开始游戏

房间内的用户可以自动或主动准备游戏，这取决于开发者的游戏策略，自动或等待用户触发调用游戏准备接口(gameReady)，用户准备之后，用户状态同样会通过onRoomUsersChanged事件监听通知到所有用户（见代码示例(2)）。当所有用户状态都变为已准备后，需要让房主来调用游戏开始接口( gameStart)最终通知服务器开始游戏，当然，开发者也可以在代码里判断用户状态后自动由房主客户端调用开始接口。// 准备游戏

MatchVSEngine.getInstance().gameReady();

// 开始游戏

MatchVSEngine.getInstance().gameStart();

// 游戏开始后，服务器会通过监听IMatchVSEngineListener.onGameStart通知所有用户

代码示例(4)：

@Override

publicvoid onGameStart(long pRoundID) {

//pRoundID为每局游戏的流水号

Log.d(TAG, "onGameStart：" + pRoundID);

}

（MatchVS SDK v1.2.4新增）

开发者可以通过v1.2.4新接口判断房间用户是否全部准备

// 房主用户可以根据此方法判断其他用户是否准备

MatchVSEngine.getInstance().isRoomOtherUserReadyed();

获取用户信息

有时候，需要在房间显示其他用户的信息，如果做到呢？通过调用MatchVSUserCenter的相关接口即可达到目的。

如何获取其他用户的信息？

用户信息包含用户的昵称及头像，具体接口如下：

（MatchVS SDK v1.2.4新增）

v1.2.4 及以上版本可以使用如下接口获取用户详情及战绩详情

// 获取用户详情，包含用户昵称及头像，此方法使用了缓存机制，提高获取速度MatchVSEngine.getInstance().getUserDetails(pUserID, pMatchVSCallback);

（MatchVS SDK 全版本包含）

/**

* 批量获取用户信息

* @param pContext

* @param pGameID游戏ID

* @param pUserIDs用户ID列表

* @param pCallback结果回调

* @return

*/

MatchVSUserCenter.getInstance().queryUserDetails(

Context pContext,

int pGameID,

Integer[] pUserIDs,

final MatchVSCallback>pCallback);

代码示例(5)：

// 获取GameID为100011，用户{3232, 3995}的信息

MatchVSUserCenter.getInstance().queryUserDetails(

context, 100011, new Integer[]{3232, 3995},

new MatchVSCallback>() {

@Override

publicvoid onSuccess(String pRawJSON, ListpUserList) {

// pRawJSON用户数据列表JSON

// pUserList用户对象列表

}

@Override

publicvoid onFail(int pResultCode, String pMessage) {

// pResultCode错误码

// pMessage错误信息

}

});

如何获取用户战绩？

用户战绩包含用户在此游戏下的对战数据，具体接口如下：

/**

* 批量获取用户战绩信息

* @param pContext

* @param pGameID游戏ID

* @param pUserIDs用户ID列表

* @param pCallback结果回调

* @return

*/

MatchVSUserCenter.getInstance().queryUserBattleDetails(

Context pContext,

int pGameID,

Integer[] pUserIDs,

final MatchVSCallback>pCallback);

代码示例(6)：

// 获取GameID为100011，用户{3232, 3995}的战绩

MatchVSUserCenter.getInstance().queryUserBattleDetails(

context, 100011, new Integer[]{3232, 3995},

new MatchVSCallback>() {

@Override

publicvoid onSuccess(String pRawJSON, ListpBattleDetails) {

// pRawJSON用户战绩列表JSON

// pBattleDetails用户战绩列表

}

@Override

publicvoid onFail(int pResultCode, String pMessage) {

// pResultCode错误码

// pMessage错误信息

}

});

数据传输

当收到onGameStart回调监听，就意味着开发者可以开始进行游戏数据传输了。开发者此时可以从一个用户传输任何数据到其他用户。比如，游戏开始前的对时，游戏过程中的状态数据等。目前MatchVS提供了两种发送数据的方式( byte[] 和MatchVSBundle )，方法如下：

（MatchVS SDK v1.2.4新增）

/**

* 发送数据给房间其他人，可靠传输，无丢包

* @param pRoomUser默认是所有人

* @param pData数据

*/

MatchVSEngine.getInstance().sendReliableData(

MatchVSRoomUserpRoomUser, byte[] pData);

（MatchVS SDK所有版本包含如下接口）

/**

* 发送数据给房间其他人

* @param pRoomUser默认是所有人

* @param pData数据

*/

MatchVSEngine.getInstance().sendData(

MatchVSRoomUserpRoomUser, byte[] pData);

/**

* 发送数据给房间其他人

* @param pRoomUser默认是所有人

* @param pBundle数据

*/

MatchVSEngine.getInstance().sendData(

MatchVSRoomUserpRoomUser, MatchVSBundlepBundle);

MatchVSBundle是我们为Android开发者提供的一种便利的数据封装方式，其使用方式与android.os.Bundle基本相同，MatchVSBundle具体的介绍请参看《MatchVS [Java] 接口说明-对战》附件之“便利的数据封装”。

代码示例(7)：

//Client P1 发送数据

MatchVSRoomUser to = new MatchVSRoomUser();

to.roomid = roomID;

to.num = 0;//num=0时表示发送给所有人

https://www.wendangku.net/doc/328133732.html,erid = newint[] { userID_P2 };

//封装Bundle

MatchVSBundle bundle = new MatchVSBundle();

bundle.putString("a", "test");

bundle.putInt("x", 77);

bundle.putInt("y", 66);

//发送

MatchVSEngine.getInstance().sendData(to, bundle);

代码示例(8)：

//Client P2 接收数据

// 接受到其他用户的数据后，会通过监听IMatchVSEngineListener.onDataReceived通知开发者

@Override

publicvoid onDataReceived(int userid, byte[] pData) {

MatchVSBundle bundle = MatchVSBundle.deserialize(pData);

String a = bundle.getString("a");

int x = bundle.getInt("x");

int y = bundle.getInt("y");

}

提高数据传输质量

到此为止，开发者可以自由的在客户端之间交流游戏数据，同时为了保证游戏的流畅体验，开发者可以考虑加入一些游戏同步策略，诸如影子跟随，Step Lock等。为了保证服务质量，MatchVS要求开发者发送数据包的频次不超过每秒钟30次。超过频次的数据包会被错误处理，请开发者注意控制节奏。

结果仲裁

游戏玩了许久，如果结束一局游戏呢？

游戏的结果由开发者来判定，当游戏出现结果时，开发者需要通知服务器本局游戏结束（gameOver），同时向服务器上报本次游戏的结果。服务器确认游戏结束（onGameOver）后，会对本局游戏中所有的结果进行仲裁，最终返回游戏结果（onGameResult）到各个客户端。

代码示例(9)：

//游戏结束并上报游戏结果

MatchVSScore score = new MatchVSScore();

score.a = 1;

score.b = 0;

score.c = 0;

MatchVSEngine.getInstance().gameOver(score);

//所有用户调用gameOver后，服务器确认游戏结束

//游戏结束事件通过IMatchVSEngineListener.onGameOver通知开发者

@Override

publicvoid onGameOver(MatchVSScorepScore) {

//pScore为用户提交的成绩

//收到此监听，服务器确认本局游戏结束，结果仲裁中

}

// 服务器对游戏结果仲裁结束

//游戏结果事件通过IMatchVSEngineListener.onGameResult通知开发者

@Override

publicvoid onGameResult(int pResultCode, MatchVSScore[] pScores, String pMessage) { //pResultCode 0为正常，其他为结果仲裁发生错误

//pScores当局游戏所有参与玩家的结果

//pMessage文字信息

//收到此监听，服务器仲裁结果结束，开发者可以根据所有用户的结果构造结果UI

}

当然，开发者也许不需要MatchVS来处理游戏结果，那么在上报结果的时候使用gameOver的重载方法，如下：

// 游戏结束，但不需要结果仲裁

MatchVSEngine.getInstance().gameOver(score, false);

MatchVSScore？

看完“结果仲裁”前面的文字，那么问题来了，什么是MatchVSScore？如何创建它？

MatchVSScore是MatchVS对游戏定义的一种通用结果数据格式，它的内容会被记录在MatchVS的服务器，它包含如下内容：

scoreA：自定义分数A，计算方式（累加、取大、取小）可选

scoreB：自定义分数B，计算方式（累加、取大、取小）可选

scoreC：自定义分数C，计算方式（累加、取大、取小）可选

extend_0至extend_9：自定义数据0到9，计算方式（累加、取大、取小）可选

如何使用MatchVSScore呢？首先，开发者需要向MatchVS提交游戏结果的定义，即ABC三个自定义分数的含义及计算方式；extend_0至extend_9 用于给开发者存储其他数据，可选使用。在MatchVS收录了开发者的结果定义之后，开发者就可以在gameOver的时候正常提交游戏结果了。

举例A：

某格斗类型游戏

配置{ScoreA：胜，累加；ScoreB：负，累加; ScoreC：平，累加}

胜利方上报{ ScoreA:1, ScoreB:0, ScoreC:0}

失败方上报{ ScoreA:0, ScoreB:1, ScoreC:0}

玩家历史战绩{ ScoreA:178, ScoreB:59, ScoreC:30 }

举例B：

某过关类型游戏

配置{ScoreA：最高分，取大；ScoreB：最快耗时，取小; ScoreC：通关次数，累加}

结束上报{ ScoreA:78948624, ScoreB:660, ScoreC:1 }

玩家历史战绩{ ScoreA:88938659, ScoreB:659, ScoreC:15 }

MatchVS会根据开发者提交的结果定义进行仲裁，如举例A中的格斗游戏，如果P1和P2都上报了scoreA = 1，那么结果一定是出现了问题的。当然，仲裁服务的判断条件会更加复杂，判定规则也可以和开发者一同商定。对于扩展字段（extend），MatchVS不关心其内容，仅仅是根据设定计算方式进行记录，开发者可以灵活使用。

让对战更有趣

不同的游戏场

仅仅是随机匹配还不过瘾，那么可以试试在MatchVS定义不同的游戏场（BattleField），每个游戏场可以定义各种商品消费，所谓小赌怡情，游戏对战的时候增加一些筹码岂不快哉！

首先，开发者需要在MatchVS定义一些商品，在接入MatchVS的货币&充值功能后，MatchVS允许开发者操作使用这些商品。

开发者每定义一个游戏场，都可以设置该游戏场进入的门槛，即用户拥有某商品的数量限制；同时还可以设置该游戏场在一局游戏结束之后如何消费和奖励。

举个栗子：

某格斗游戏

游戏场名称：新手场

门槛：商品A数量在0到600才可进入

消费：参与者需要消耗100商品A

佣金：系统回收10商品A

奖励：赢者收获180商品A，相当于挣了80商品A

开发者在MatchVS定义了游戏场之后，可以通过如下接口来获取游戏场列表：

/**

* 获取游戏场列表，此功能所需数据需要在MatchVS开放平台提交

* @param pContext

* @param pGameID游戏ID

* @param pVersionID对战版本号

*/

MatchVSEngine.getInstance().getBattleFields(

Context pContext, int pGameID, int pVersionID);

游戏场的内容会通过监听IMatchVSEngineListener.onGetBattleFieldsResponse返回给开发者。开发者可以使用游戏场（BattleField）对象中的fieldID进行房间匹配，房间匹配的方法也不再是匹配房间并快速开始游戏中提到的enterRoom，而需使用enterRoomInField(int pRoomID, int pFieldID)

代码示例(10)：

// 请求游戏场列表

MatchVSEngine.getInstance().getBattleFields(this, 100011, 1);

// 在获取到游戏场列表后，通过监听IMatchVSEngineListener.onGetBattleFieldsResponse返回

@Override

publicvoid onGetBattleFieldsResponse(int pResultCode, BattleFields[] pFields, String pMsg) {

for (BattleFields field :pFields) {

// field. fieldID 游戏场ID

// field. Thresholds 门槛列表

// field. cost 消费列表

}

}

// 在游戏场中随机匹配房间

// 当参数pRoomID为0时表示随机匹配房间

MatchVSEngine.getInstance().enterRoomInField(pRoomID,pFieldID);

注意：进入房间后的处理与匹配房间并快速开始游戏中介绍的相同。

比赛

敬请期待！

货币&支付功能

如何充钱？

MatchVS将整合目前移动端各种流行的充值方式，如支付宝、百度、微信、天翼短代等。开发者在需要充值现金的时候调用充值接口( pay )即可进入充值流程，方法如下：

/**

* RMB充值，支持余额充值

* @param activity

* @param pChargeOrder

* @param pCallback

*/

publicvoid pay(

final Activity activity,

final ChargeOrder pChargeOrder,

final MatchVSCallbackpCallback);

充值订单（pChargeOrder）包含如下内容：

developerID 开发者ID

userID 登录的用户ID

token 登录的用户授权码

gameID 游戏ID

chargePoint 计费码计费代码在v1.2.2之后不再使用

openOrderID 开发者订单ID

openExtend 开发者扩展信息，在通知开发者时会原文返回

openNotifyURL 开发者充值回调地址

payType 支付类型，此值控制支付选择界面打开是的默认支付方式，值在1-12之间，手机推荐使用payType=1（支付宝-钱包），TV推荐使用payType=3（支付宝-扫码）

amount 充值金额，单位分

subject 充值主题，自定义文字

desciption 充值说明，自定义文字

needSpend 是否立即消费

openOrderID为开发者提供的订单ID，由开发者服务器生成，当充值成功后，MatchVS充值服务器会通知开发者openOrderID的充值结果；如果开发者没有自己的服务器接受订单通知，那么openOrderID可以选择填空（‘’），完成充值后可以通过订单查询接口查询充值结果。

openExtend为开发者扩展信息，开发者可以根据需要自由填写，在充值成功后，会原文通知到开发者的充值回调服务器。

needSpend为boolean型值，若其值为true，充值时会优先选择使用MatchVS平台币钻石进行充值，若平台币钻石不足时，将进行差额充值。使用needSpend=true的开发者，可以不用考虑MatchVS 平台币钻石的处理，只需要关心通知回调时的金额即可。