matchvs [c ] 接入指引-对战引擎

MATCHVS对战引擎接入指引（FORCOCOS2DX）版本V126欢迎加入MATCHVS开发者平台，本文档描述了MATCHVS对战引擎（本文以下简称之为“MATCHVS”）与游戏开发商（本文以下简称之为“开发者”）游戏接入的使用指引，供产品及技术人员参看。请开发者在查看本文档后，及时反馈开发进度表（包含研发、联调与上线内测），以便我们安排人员技术支持与提前准备上线等事宜。MATCHVS对战引擎产品技术文档修订历史记录日期版本说明作者2015/12/29V124新建MATCHVSCOM2015/12/29V126完善文档、SAMPLE运行指引MATCHVSCOM目录MATCHVS介绍5什么是MATCHVS5MATCHVS能帮开发者做什么5网络对战5社区化用户体系5增值服务5对战数据分析5快速开始6获取MATCHVS开发包6接入功能介绍6如何选择接入功能6ANDROID6WINDOW（VISIOSTUDIO）7IOS_MACXCODE7成为开发者7为游戏获取MATCHVS_APP_KEY7对战前的准备8项目配置8库引用8初始化10JNI代理服务10初始化服务模块10登录用户11对战事件11快速战斗11进入游戏大厅11匹配房间并快速开始游戏12进入房间12监听房间用户变化13准备/开始游戏14获取用户信息14数据传输15提高数据传输质量16结果仲裁16MATCHVSSCORE16让对战更有趣17不同的游戏场17比赛18货币PUBLICCLASSAPPACTIVITYEXTENDSCOCOS2DXACTIVITYOVERRIDEPROTECTEDVOIDONCREATEBUNDLESAVEDINSTANCESTATEMATCHVSSERVICEINITSERVICEGETAPPLICATIONCONTEXT,/推荐使用APPLICATIONCONTEXT/102000,/游戏ID/1,/游戏版本/1/开发者ID/SUPERONCREATESAVEDINSTANCESTATE/注游戏版本一般为1，如果开发者需要区别不同版本的对战可以申请增加初始化服务模块在C使用MATCHVS用户、用户及对战接口时，需要先初始化服务模块，注册事件回调。初始化方法在应用声明周期中仅需调用一次，开发者可以在游戏初始化时进行。CMATCHVSUSERGETINSTANCEINITWITHCALLBACKNEWUSERCALLBACKCMATCHVSPAYGETINSTANCEINITWITHCALLBACKNEWPAYCALLBACKCMATCHVSLOBBYGETINSTANCEINITWITHCALLBACKNEWLOBBYCALLBACKCLASSUSERCALLBACKPUBLICCMATCHVSUSERCALLBACK/开发者实现回调接口CLASSPAYCALLBACKPUBLICCMATCHVSPAYCALLBACK/开发者实现回调接口CLASSLOBBYCALLBACKPUBLICCMATCHVSLOBBYCALLBACK/开发者实现回调接口登录用户项目配置好后，马上可以试试用户登录吧MATCHVS的账户包含游客账户和第三方绑定账号，当没有使用第三方平台（如微信、百度等）登录方式登录用户系统时，MATCHVS默认使用游客账号登录。MATCHVS账户类型由MATCHVS在其社区应用中控制，开发者不用关心具体的登录方式。登录用户的具体方法是/登录用户，C代码CMATCHVSUSERGETINSTANCELOGIN/如果开发者已经在上层使用JAVA接口进行登录，同样可以通过这个C方法获取到登录信息/JAVA层接口使用请查阅SDKFORANDROIDJAVA相关文档登录成功后，用户信息会通过回调CMATCHVSUSERCALLBACK通知给开发者，通知内容为CMATCHVSUSERINFO对象，其中包含了用户ID，唯一，开发者可以用来绑定应用原生账号用户昵称，UTF8字符串用户头像，HTTPURLTOKEN，用户授权TOKEN，用于后续其他接口的调用游戏ID及开发者ID注意仅在登录用户完成后，才可以继续使用后续的接口对战事件开发者通过实现CMATCHVSLOBBYCALLBACK接口，并注册到CMATCHVSLOBBY中，即可就收到对战事件回调通知。回调具体内容请参开文档MATCHVSC接口说明对战AUTHI32DEVELOPID1/开发者ID/AUTHI32GAMEID102000/游戏ID/AUTHI32VERSIONGAME1/游戏版本/登录完成后，通过回调方法（CMATCHVSUSERCALLBACKONLOGINBACKWITHINFO）获取到用户信息CMATCHVSLOBBYGETINSTANCEGAMELOGIN/登录大厅成功后，会通过（CMATCHVSLOBBYCALLBACKONLOGINBACK）回调给开发者MS_INT32_TLOBBYCALLBACKONLOGINBACKMATCHVSLOGINRSPPRSPIFPRSPI32RET200/登录成功，此后可以进入房间开始游戏/开发者可以者这里触发调整UI，显示快速匹配按钮等RETURNMATCHVS_OK匹配房间并快速开始游戏进入大厅完毕，赶快寻找其他玩家对战吧进入房间匹配用户，或称进入房间，开发者在进入大厅之后，可以使用房间匹配接口（ROOMIN）快速进入房间，根据游戏应用的不同，房间限制的人数也不同，当房间人数达到上限，其他用户将无法进入。/快速加入房间，此方法会随机匹配一个最优玩家CMATCHVSLOBBYGETINSTANCEROOMIN/进入房间成功后，会通过（CMATCHVSLOBBYCALLBACKONROOMINBACK）回调给开发者MS_INT32_TLOBBYCALLBACKONROOMINBACKMS_INT32_TI32ROOMID,MATCHVSUSERSTATEPUSERSTATE,MS_INT32_TI32NUMPRINTF“进入房间DN，用户个数D“,I32ROOMID,RETURNMATCHVS_OK监听房间用户变化通过实现回调CMATCHVSLOBBYCALLBACK，开发者可以监听到房间内用户变化的情况。第一个进入房间的用户会自动成为房主，随后进入的每一个用户，都会通过回调通知到其他用户。相同，用户的离开也会同样周知房间内剩余的用户。每个房间都存在一个房主，房主发生变化时，同样能通过回调收到通知/其他玩家加入到这个房间MS_INT32_TLOBBYCALLBACKONUSERROOMINBACKMS_INT32_TI32ROOMID,MATCHVSUSERSTATEUSERSTATEPRINTF“ONUSERROOMINBACKROOMD,USERDN“,I32ROOMID,USERSTATEI32USERIDRETURNMATCHVS_OK/玩家退出房间MS_INT32_TLOBBYCALLBACKONUSERROOMOUTBACKMATCHVSUSERSTATEUSERSTATEPRINTF“ONUSERROOMOUTBACKUSERIDDN“,USERSTATEI32USERIDRETURNMATCHVS_OK/玩家已准备MS_INT32_TLOBBYCALLBACKONUSERGAMEREADYMATCHVSUSERSTATEUSERSTATEPRINTF“ONUSERGAMEREADYUSERIDDN“,USERSTATEI32USERIDRETURNMATCHVS_OK/玩家取消准备MS_INT32_TLOBBYCALLBACKONUSERCANCELREADYMATCHVSUSERSTATEUSERSTATEPRINTF“ONUSERCANCELREADYUSERIDDN“,I32USERIDRETURNMATCHVS_OK/房主变更MS_INT32_TLOBBYCALLBACKONROOMOWNERCHANGEDMS_INT32_TI32USERIDPRINTF“房间主人改为DN“,I32USERID/只有房主才可以触发GAMESTART方法/如果存在“开始”按钮之类的UI，开发者需要在接收到此回调后进行调整RETURNMATCHVS_OK/房间内用户变化时，全体用户信息回调，开发者可以选择使用此回调或之前的详细回调MS_INT32_TLOBBYCALLBACKONROOMCHANGEMATCHVSUSERSTATEPUSERSTATE,MS_INT32_TI32NUMPRINTF“ONROOMCHANGENUMDN“,I32NUMRETURNMATCHVS_OK准备/开始游戏房间内的用户可以自动或主动准备游戏，这取决于开发者的游戏策略，自动或等待用户触发调用游戏准备接口READY，用户准备之后，用户状态同样会通过ONUSERGAMEREADY（他人）或ONGAMEREADY（自己）回调收到通知。当所有用户状态都变为已准备后，需要让房主来调用游戏开始接口START最终通知服务器开始游戏，当然，开发者也可以在代码里判断用户状态后自动由房主客户端调用开始接口。/准备游戏CMATCHVSLOBBYGETINSTANCEREADY/取消准备游戏CMATCHVSLOBBYGETINSTANCECANCELREADY/自己准备后，会通过（CMATCHVSLOBBYCALLBACKONGAMEREADY）回调给开发者/自己取消准备后，会通过（CMATCHVSLOBBYCALLBACKONCANCELREADY）回调给开发者/其他玩家准备后，会通过（CMATCHVSLOBBYCALLBACKONUSERGAMEREADY）回调给开发者/其他玩家取消准备后，会通过（CMATCHVSLOBBYCALLBACKONUSERCANCELREADY）回调给开发者/开始游戏CMATCHVSLOBBYGETINSTANCESTART/服务器在确认游戏可以开始后，会通知所有玩家开始游戏，通过回调通知给开发者/回调参数I32ROUNDID为当局游戏MS_INT32_TLOBBYCALLBACKONGAMESTARTMS_INT64_TI32ROUNDIDPRINTF“游戏开始ROUNDIDLLDTIMESDN“,I32ROUNDIDRETURNMATCHVS_OK获取用户信息有时候，需要在房间显示其他用户的信息，如果做到呢通过调用MATCHVSUSER的相关接口即可达到目的。如何获取其他用户的信息用户信息包含用户的昵称及头像，具体接口GETUSERINFO/获取服务器用户信息CMATCHVSUSERGETINSTANCEGETUSERINFO/登录成功后获取本地缓存用户信息CMATCHVSUSERINFOOBJUSERINFOCMATCHVSUSERGETINSTANCEGETUSERINFO/服务器返回用户信息回调MS_INT32_TONGETUSERINFOBACKMS_INT32_TI32ERROR,CMATCHVSUSERINFOOBJUSERINFOPRINTF“USERIDD”,OBJUSERINFOI32USERIDRETURNMATCHVS_OK如何获取用户战绩用户战绩包含用户在此游戏下的对战数据，具体接口如下/获取用户战绩排行CMATCHVSBATTLEGETINSTANCEGETMYRANK/服务器返回用户排行/当前为JSON数据MS_INT32_TONMYRANKBACKMS_INT32_TI32ERROR,MS_INT32_TI32STATUS,MS_INT32_TI32CODEMS_INT8_TPI8MSG,MS_INT32_TPI8DATAPRINTF“MSGS,RANKDATAS”,PI8MSG,PI8DATARETURNMATCHVS_OK数据传输当收到ONGAMESTART回调监听，就意味着开发者可以开始进行游戏数据传输了。开发者此时可以从一个用户传输任何数据到其他用户。比如，游戏开始前的对时，游戏过程中的状态数据等。目前MATCHVS提供了两种发送数据的方式，方法如下/发送数据UDPCMATCHVSLOBBYGETINSTANCESEND/发送数据可靠传输无丢包CMATCHVSLOBBYGETINSTANCESENDRELIABLE/游戏数据同个以上两个方法将发送到其他玩家/其他玩家将通过回调获取到其他玩家发送过来的数据MS_INT32_TLOBBYCALLBACKONRECVMS_INT32_TI32USERID,MS_STR_TPMSGPRINTF“收到数据LENGTHDN“,PMSGI32SIZERETURNMATCHVS_OKMS_INT32_TLOBBYCALLBACKONRECVRELIABLEMS_INT32_TI32USERID,MS_STR_TPMSGPRINTF“收到数据LENGTHDN“,PMSGI32SIZERETURNMATCHVS_OK提高数据传输质量到此为止，开发者可以自由的在客户端之间交流游戏数据，同时为了保证游戏的流畅体验，开发者可以考虑加入一些游戏同步策略，诸如影子跟随，STEPLOCK等。为了保证服务质量，MATCHVS要求开发者发送数据包的频次不超过每秒钟30次。超过频次的数据包会被错误处理，请开发者注意控制节奏。结果仲裁游戏玩了许久，如果结束一局游戏呢游戏的结果由开发者来判定，当游戏出现结果时，开发者需要通知服务器本局游戏结束（GAMEOVER），同时向服务器上报本次游戏的结果。服务器确认游戏结束（ONGAMEOVER）后，会对本局游戏中所有的结果进行仲裁，最终返回游戏结果到各个客户端。/构造结果MATCHVSSCOREMATCHVSSCORESCORENEWMATCHVSSCORESCOREI32USERID10SCOREI32A1SCOREI32B0SCOREI32C0/通知服务器本机游戏结束，并上报分数CMATCHVSLOBBYGETINSTANCEGAMEOVERSCORE/所有玩家上报结果后，服务器将会对所有用户分数结果进行合法性仲裁，并将最终结果返回到客户端MS_INT32_TLOBBYCALLBACKONGAMEOVERMATCHVSSCOREPSCORE,MS_INT32_TI32NUM/开发者可以根据结果进行UI结果显示RETURNMATCHVS_OKMATCHVSSCORE看完“结果仲裁”前面的文字，那么问题来了，什么是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平，累加胜利方上报SCOREA1,SCOREB0,SCOREC0失败方上报SCOREA0,SCOREB1,SCOREC0玩家历史战绩SCOREA178,SCOREB59,SCOREC30举例B某过关类型游戏配置SCOREA最高分，取大；SCOREB最快耗时，取小SCOREC通关次数，累加结束上报SCOREA78948624,SCOREB660,SCOREC1玩家历史战绩SCOREA88938659,SCOREB659,SCOREC15MATCHVS会根据开发者提交的结果定义进行仲裁，如举例A中的格斗游戏，如果P1和P2都上报了SCOREA1，那么结果一定是出现了问题的。当然，仲裁服务的判断条件会更加复杂，判定规则也可以和开发者一同商定。对于扩展字段（EXTEND），MATCHVS不关心其内容，仅仅是根据设定计算方式进行记录，开发者可以灵活使用。让对战更有趣不同的游戏场仅仅是随机匹配还不过瘾，那么可以试试在MATCHVS定义不同的游戏场（BATTLEFIELD），每个游戏场可以定义各种商品消费，所谓小赌怡情，游戏对战的时候增加一些筹码岂不快哉首先，开发者需要在MATCHVS定义一些商品，在接入MATCHVS的货币加入MATCHVS对战平台大家庭跨设备对战MATCHVS对战引擎整合各种设备，可以在TV，智能盒子，手机等ANDROID设备上相互对战，高性能的