guofei
/
egret-docs-master
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
egret-docs-master/extension/matchvs/demo/duck/README.md

417 lines
15 KiB
Markdown
Raw Permalink Normal View History

fist commit
2024-06-19 13:32:32 +08:00
## Demo简介
为了便于开发者使用和理解，用 Matchvs 的实时联网 SDK 和 白鹭 `Egret` 开发的多人抢足球，提供了简洁的Demo来展示多人实时联网游戏的开发过程和效果，用于演示多人匹配、数据传输、帧同步、创建房间、获取房间列表、消息订阅、断线重连、修改房间属性等功能。
# Egret集成Matchvs
在Egret游戏开发引擎中使用 Matchvs 游戏联网引擎，快速的开发联网对战游戏。
## Egret 环境配置
#### 1、Lanucher 安装。
- [Lanucher 下载](https://www.egret.com/)
#### 2、安装egret引擎版。
打开Lanucher选择对应的egret引擎版本下载安装（egret更新较快建议安装最新的Stableb版本），如下图：
![](http://imgs.matchvs.com/static/Doc-img/new-start/Egretimg/egret_start1.png)
#### 3、安装IDE工具Wing
打开Lanucher 定位到工具页面，下载wing并安装。
## Matchvs 集成
#### 1、创建egret游戏开发项目。
打开Lanucher 定位到项目页面。创建项目。在项目创建页面勾选Matchvs游戏云。并创建。
![](http://imgs.matchvs.com/static/Doc-img/new-start/Egretimg/egret_start2.png)
#### 2、替换matchvs文件夹下面的内容
到 [Matchvs官网下载](http://www.matchvs.com/serviceDownload) TypeScript版本的 MatchvsSDK 解压并取出 matchvs 文件内容到 egret项目的libs目录里面。
> `matchvs`文件下三个文件(matchvs.d.ts、matchvs.js、matchvs.min.js)。
#### 3、使用 wing打开项目
创建好项目后，在打开项目的wing左边导航可以的libs目录下可以看到有 matchvs文件夹，如下图：
![](http://imgs.matchvs.com/static/Doc-img/new-start/Egretimg/egret_start3.png)
#### 4、配置 egretProperties.json 文件
打开 egretProperties.json 文件添加如下配置：
```typescript
{
"name": "matchvs",
"path": "./libs/matchvs"
}
```
如图所示：
![](http://imgs.matchvs.com/static/Doc-img/new-start/Egretimg/egret_start5.png)
以上步骤已经完美集成 Matchvs SDK，接下来就开启你的 联网对战之旅。
## Matchvs 使用
在使用 Matchvs 服务之前请确认您已经在 Matchvs官网注册账号并新建好了一款游戏服务。如果还没有注册Matchvs 游戏服务请参考 [Matchvs 快速入门](../matchvs) 文档。
Matchvs SDK 接口服务分为 **请求服务** 和 **回调服务** ， 使用是以简单的接口调用和接口返回的方式实现相关联网操作。比如随机加入房间只需要调用`joinRandRoom接口`，加入房间结果就以接口 `joinRoomResponse` 返回。在整个使用过程中，开发者只需要关心`MatchvsEngine`(接口请求调用对象)和 `MatchvsResponse`(接口调用返回对象)。接口请求使用 `MatchvsEngine`对象实例，接口返回使用 `MatchvsResponse` 对象实例。后面后介绍这两个对象的使用方法。此文档只是用于引导开发者接入SDK，需要接口详细的参数说明请看 [API手册](../APIDoc/TypeScript)
#### Matchvs 变量定义
定义两个全局唯一的Matchvs 服务变量，一个是 `MatchvsEngine` 接口请求对象变量，另一个是`MatchvsResponse` 接口回调对象。示例代码如下：
```typescript
let engine:MatchvsEngine = new MatchvsEngine();
let response:MatchvsResponse = new MatchvsResponse();
```
在egret 项目中使用示例如下：
```typescript
//这Main是Egret项目中的入口
class Main extends eui.UILayer {
......
private engine:MatchvsEngine = new MatchvsEngine();
private response:MatchvsResponse = new MatchvsResponse();
......
}
```
> 注意：请确保两个对象是全局唯一的，您可以根据自己的喜好进行封装，使用静态变量或者单例类都可以。
#### Matchvs 初始化
获取到对象实例后，需要开发者把 `MatchvsResponse` 实例注册到 `MatchvsEngine` 用于注册、登录、加入房间等接口请求后的异步回调。调用 `init` 接口初始化SDK。
请求示例：
```typescript
engine.init(response, "Matchvs", "alpha", 201016, "appkey","gameSersion");
```
回调示例:
```typescript
response.initResponse = function(status:number){
.......
}
```
参数说明:
| 参数 | 含义 |
| :----- | ----------------- |
| status | 200-成功 其他失败 |
在egret 项目中使用示例如下：
```typescript
class Main extends eui.UILayer {
.....
private runMatchvs(){
this.response.initResponse = this.initResponse.bind(this);
this.engine.init(this.response, "Matchvs", "alpha", 201016, "xxxxappkey", 1);
}
private initResponse(status:number){
if(status === 200){
console.log("初始化成功!");
}
}
}
```
> 注意：this.response.initResponse = this.initResponse; 是指定 engine.init 请求的回调函数，在调用init前需要指定一个回调函数用于处理回调结果，可以在在统一的一个地方处理你将要使用的回调函数。在示例中我们约定在调用`MatchvsEngine` 请求接口前指定回调函数。
#### 注册用户
Matchvs提供的 `userID` 被用于在各个服务中校验连接的有效性，调试前开发者需要先获取到一个合法的`userID`。调用registerUser接口获取，在registerResponse回调返回。
请求示例：
```typescript
engine.registerUser();
```
回调示例：
```typescript
response.registerUserResponse = function(userInfo:MsRegistRsp){
......
}
```
> **注意** : 每次调用 registerUser 接口都会生成新的 `userID` 为了节省资源消耗， `userID`和 `token` 有需要的可以缓存起来，在之后的应用启动中不必重复获取。如果你有自己的用户系统，可以将Matchvs 提供的 userID 和用户系统进行映射。可以参考 [Matchvs 第三方账号绑定](../Advanced/ThirdAccount)，让您的用户唯一对应一个userID，以节省资源。
>
> 为了资源节省，我们在registerUserResponse 回调前把userID信息缓存在本地，数据会暂存在浏览器中。所以使用同一个浏览器调用 registerUser 接口会返回相同的 userID信息。请看 [多开说明](../Advanced/MultipleIdentities)
在egret 项目中使用示例如下：
```typescript
//这是初始化成功的回调，我们初始化成功后调用 registerUser 注册用户
private initResponse(status:number){
if(status === 200){
console.log("初始化成功!");
this.response.registerUserResponse = this.registerUserResponse.bind(this);
this.engine.registerUser();
}
}
//注册用户回调
private registerUserResponse(userInfo:MsRegistRsp){
if(userInfo.status === 0){
console.log("注册成功");
}
}
```
#### 登录Matchvs SDK 联网服务
成功获取 `userID` 后即可连接Matchvs服务。调用 login 接口登录，loginResponse 回调。
请求示例：
```typescript
engine.login(userInfo.userID, "deviceID");
```
回调示例：
```typescript
response.loginResponse = function(rsp:MsLoginRsp){
......
}
```
- 其中，`appKey，secret，gameID`是你在Matchvs官网创建游戏后获取的信息，可以[前往控制台](http://www.matchvs.com/manage/gameContentList)查看。appkey和secret是校验游戏合法性的关键信息，请妥善保管secret信息。
- userID 和 token 是调用 registerUser 接口 **注册成功** 的回调信息。
- deviceID 用于检测是否存在多个设备同时登录同一个用户的情况，如果一个账号在两台设备上登录，则后登录的设备会连接失败。
- Matchvs默认将相同游戏版本的用户匹配到一起。如果开发者对游戏进行了版本升级，不希望两个版本的用户匹配到一起，此时可以在登录的时候通过`gameVersion`区分游戏版本。
在egret 项目中使用示例如下：
```typescript
private registerUserResponse(userInfo:MsRegistRsp){
if(userInfo.status == 0){
console.log("注册成功");
this.response.loginResponse = this.loginResponse.bind(this);
this.engine.login(userInfo.userID, userInfo.token, "deviceID");
}
}
private loginResponse(rsp:MsLoginRsp){
if(rsp.status === 200){
console.log("登录Matchvs联网SDK成功");
}
}
```
#### 随机匹配
登录成功后，可以调用Matchvs加入房间接口，将若干用户匹配至一个房间开始一局游戏（如：《荒野行动》的开始匹配、《球球大作战》的开始比赛等）
Matchvs默认提供了随机加入房间的模式，调用加入房间逻辑后，Matchvs服务器会自动帮助用户寻找当前可用房间，只有在同一个房间里的用户才可以互相通信。
随机加入房间的模式下，Matchvs服务器能够快速找到合适的房间，开发者只需要自定义房间人数上限，Matchvs服务端会根据当前房间人数判断是否可继续加入。 加入房间回调有 `joinRoomResponse` 和 `joinRoomNotify` 两个，前者是**调用joinRoom者**收到是否成功加入房间回调的信息，后者是在**房间其他的玩家**收到的回调信息。
请求示例：
```typescript
engine.joinRandomRoom(3,"hello matchvs");
```
回调示例：
```typescript
this.response.joinRoomNotify = function(roomUserInfo:MsRoomUserInfo){
......
}
this.response.joinRoomResponse = function(status:number, roomUserInfoList: Array <MsRoomUserInfo>, roomInfo:MsRoomInfo){
......
}
```
在 Egret 项目中使用示例如下：
```typescript
private loginResponse(rsp:MsLoginRsp){
if(rsp.status === 200){
console.log("登录Matchvs联网SDK成功");
this.response.joinRoomNotify = this.joinRoomNotify.bind(this);
this.response.joinRoomResponse = this.joinRoomResponse.bind(this);
this.engine.joinRandomRoom(3,"hello matchvs");
}else{
console.log("登录Matchvs联网失败",userInfo.status );
}
}
private joinRoomResponse(status:number, roomUserInfoList:Array<MsRoomUserInfo>, roomInfo:MsRoomInfo){
if(status === 200){
console.log("我自己进入房间成功");
}
}
private joinRoomNotify(roomUserInfo:MsRoomUserInfo){
console.log("有其他人进入房间");
}
```
Matchvs 提供四种加入房间的操作，他们加入房间的操作都是相互平行的，随机匹配只能和随机配的玩家一起，属性匹配只能和属性匹配的玩家一起，但是加入指定房间 与 创建房间是一起的：
- 随机匹配( joinRandRoom ): 由Matchvs 自动匹配用户。
- 属性匹配( joinRoomWithProperties ): 由开发设定属性相同的用户匹配到一起
- 加入指定房间 ( joinRoom )：加入指定房间，这个是与 createRoom配合使用，只能加入到 createRoom 创建的房间。
- 创建房间( createRoom )：开发者自己创建房间。其他玩家要加入必须使用 joinRoom 加入。
### 完整示例代码
```typescript
class Main extends eui.UILayer {
private engine:MatchvsEngine = new MatchvsEngine();
private response:MatchvsResponse = new MatchvsResponse();
protected createChildren(): void {
super.createChildren();
//注入自定义的素材解析器
let assetAdapter = new AssetAdapter();
egret.registerImplementation("eui.IAssetAdapter", assetAdapter);
egret.registerImplementation("eui.IThemeAdapter", new ThemeAdapter());
this.runGame().catch(e => {
console.log(e);
})
}
private async runGame() {
await this.loadResource()
this.createGameScene();
const result = await RES.getResAsync("description_json")
await platform.login();
const userInfo = await platform.getUserInfo();
console.log(userInfo);
}
private async loadResource() {
try {
const loadingView = new LoadingUI();
this.stage.addChild(loadingView);
await RES.loadConfig("resource/default.res.json", "resource/");
await this.loadTheme();
await RES.loadGroup("preload", 0, loadingView);
this.stage.removeChild(loadingView);
}
catch (e) {
console.error(e);
}
}
private loadTheme() {
return new Promise((resolve, reject) => {
// load skin theme configuration file, you can manually modify the file. And replace the default skin.
//加载皮肤主题配置文件,可以手动修改这个文件。替换默认皮肤。
let theme = new eui.Theme("resource/default.thm.json", this.stage);
theme.addEventListener(eui.UIEvent.COMPLETE, () => {
resolve();
}, this);
})
}
private textfield: egret.TextField;
/**
* 创建场景界面
* Create scene interface
*/
protected createGameScene(): void {
let sky = this.createBitmapByName("bg_jpg");
this.addChild(sky);
let stageW = this.stage.stageWidth;
let stageH = this.stage.stageHeight;
sky.width = stageW;
// sky.height = stageH;
this.runMatchvs();
}
/**
* 根据name关键字创建一个Bitmap对象。name属性请参考resources/resource.json配置文件的内容。
* Create a Bitmap object according to name keyword.As for the property of name please refer to the configuration file of resources/resource.json.
*/
private createBitmapByName(name: string): egret.Bitmap {
let result = new egret.Bitmap();
let texture: egret.Texture = RES.getRes(name);
result.texture = texture;
return result;
}
private runMatchvs(){
this.response.initResponse = this.initResponse.bind(this);
this.engine.init(this.response, "Matchvs", "alpha", 201479);
}
private initResponse(status:number){
if(status === 200){
console.log("初始化成功!");
this.response.registerUserResponse = this.registerUserResponse.bind(this);
this.engine.registerUser();
}
}
private registerUserResponse(userInfo:MsRegistRsp){
if(userInfo.status == 0){
console.log("注册成功");
this.response.loginResponse = this.loginResponse.bind(this);
this.engine.login(userInfo.userID, userInfo.token, 201479, 1, "xxxxxxxxxxxxxxxxxxxxx","xxxxxxxxxxxxxxxxxxxx","v",0);
}else{
console.log("注册失败",userInfo.status );
}
}
private loginResponse(rsp:MsLoginRsp){
if(rsp.status == 200){
console.log("登录Matchvs联网SDK成功");
this.response.joinRoomNotify = this.joinRoomNotify.bind(this);
this.response.joinRoomResponse = this.joinRoomResponse.bind(this);
this.engine.joinRandomRoom(3,"hello matchvs");
}
}
private joinRoomResponse(status:number, roomUserInfoList:Array<MsRoomUserInfo>, roomInfo:MsRoomInfo){
if(status === 200){
console.log("我自己进入房间成功");
}
}
private joinRoomNotify(roomUserInfo:MsRoomUserInfo){
console.log("有其他人进入房间");
}
}
```
### 下一步
[更多API文档](../../api/)