== 泡饭工坊介绍 ==
===泡饭工坊是什么？===
泡饭是一套网页虚拟环境下的代码编辑工具，内嵌了多种预设和模板，集成了vscode来编辑代码，自动编译，可以方便的预览和分享给小伙伴体验。
=== 泡饭链接 ===
[链接](https://webdev.popx.com)

=== 泡饭账号注册登录 ===

==== 没账号的需要在泡饭注册账号 ====

点击左上角个人信息

[[File:泡饭未登录.png]]

点击注册

[[File:泡饭点击注册.png]]

注册页面

[[File:新注册账号手机号.png]]

'''请记住您的账号密码，这关系到后续我们管理您的使用权限'''

==== 和我们内部人员沟通，申请后台权限 ====

'''如需开通后台使用权限，将您的账号告知我们内部人员帮操作，等待通知完成后，重新刷新网页即可'''

==== 第一次需要创建一个工程 ====

[[File:新点击模板商店创建模板.png]]

[[File:新模板下载.png]]

[[File:新下载工程.png]]

==== 有了工程后，打开工程 ====

[[File:新打开我的工程.png]]

== 打开泡饭体验项目 ==

参考视频[1.泡饭运行环境演示.mp4]

== 如何用泡饭开发自己的项目 ==

=== 点击跳转后台 ===

===='''就第一次需要创建打开一个工程，才能出现地图编辑器的跳转页面''' ====

[[File:新跳转后台.png]]

=== 后台创建游戏，绑定地图 ===
* 需要泡饭跳转到后台，去新建游戏，生成独属于你的gameid和secret，这在后续的开发和上传时至关重要，请点击下方超链接，去参考其中新建gameid的部分
* [[上传流程|请看该链接中，新建游戏玩法的部分]]

=== 修改package.json进入自己的游戏和地图 ===
- 点击左侧修改配置按钮
[[File:新点击修改配置.png]]
- gameid 开发者后台中指定的游戏玩法
- secretkey 游戏玩法对应的密钥
- defaultMap 游戏玩法中，指定的地图，请在后台至少指定一张，默认填写"地图_0"
- sdkVersion sdk版本号，点击修改可以弹出下拉框，一般选用release标签的稳定版本，修改后，会去修改对应的bridge依赖，并且下载
- resVersion 美术资源版本号，会影响游戏内地图和模型的显示，一般选用最新的版本即可

=== 首次运行需要先发布 ===

当前的gameid是最新的，

目前后台服务器还没有一个初始版本的记录，所以需要在package.json中，修改完gameid之后。

首次运行要发布游戏（后续不需要每次发布，直接保存就可以编译调试）。

[[File:泡饭点击发布游戏.png]]

等待右上脚提示发布完成，即可启动进入游戏

=== 启动项目 ===

一般选用启动游戏（服务器模式）

[[File:新泡饭点击启动游戏.png]]

==== 登录界面 ====
- 运行后，浏览器将显示登陆界面。
[[File:默认地图.png]]
- 账号密码随便输入，会创建新账号
- 输入账号密码后，选择指定地图（可选），即可看到战斗服务器世界中有自己的人物。
- 默认的demo工程中，如果没有修改gameid和secretKey，地图请填写"地图_0"

== 泡饭模板的多人合作 ==

=== 发布模板 ===

[[File:发布工程多人合作.png]]

设置团队成员权限和名称

[[File:设置团队成员权限.png]]

=== 发布后管理项目 ===

发布后可以在商店模板里去修改自己发布的项目。

[[File:发布后编辑模板权限.png]]

=== 其他成员就可以在模板商店拉取模板了 ===

比如上图中的playername1的账号，就可以拉取模板了

=== 打开项目 ===

点击编辑按钮，切换到vscode运行环境。

[[File:点击编辑按钮切换vscode.png]]

=== 团队成员修改提交 ===

我们尝试写第一行代码提交下

[[File:写第一行代码.png]]

[[File:模板内git_commit.png]]

具体在vscode中，怎么使用git来提交和拉取，可以参考如下文档

[vscode使用git插件](https://blog.csdn.net/khhmd/article/details/144131405)

=== 多人合作冲突的解决(遇到冲突再看，可以先跳过) ===
==== 选择远端的master分支来merge ====

[[File:git冲突merge.png]]

[[File:gitmerge选择远端.png]]

==== 根据需求去修改冲突文件 ====

[[File:git冲突文件解决.png]]

==== 冲突文件修改完成，resolve ====
[[File:git冲突保存.png]]
[[File:解决冲突完成.png]]

==== 同步到远端 ====

[[File:gitmerge同步到远端.png]]

== 前端基础逻辑 ==

根据以下步骤，一步步进入泡泡的游戏世界，即使你是新手也无需担心。

=== 前端游戏入口 ===
- '''/src/client/index.ts''' 文件中的 `XPopManager.onGameStart` 是前端的主要入口点。

=== 创建第一个人物 ===
在 `simpleGame` 类中，我们将创建并初始化第一个游戏人物。

<pre>
export class simpleGame {
private firstModel: XModelHero;

constructor() {
// 创建第一个人物
this.firstModel = new XModelHero();
let path = 'role/model_avatar_body_default';

// 加载人物模型并播放动画
this.firstModel.loadModel(path, null, this, (success) => {
// 播放跑步动画
let actName = "act_avatar_base_run";
this.firstModel.playAniUp(`${actName}_up`);
this.firstModel.playAniDown(`${actName}_down`);

// 摄像机跟随
let camera = XPopManager.instance.xScene.camera;
camera.focus = this.firstModel;

// 定时更新人物位置
XTimer.loop(100, this, this.updateModelPos.bind(this));
});
}

updateModelPos(delta: number, frame?: string) {
// 更新人物位置
this.firstModel.position.x += 0.1;
}
}

// 设置游戏启动时执行
XPopManager.onGameStart = () => {
new simpleGame();
}
</pre>

*注意：请将原代码中的 '''new Main()''' 替换为 '''new simpleGame()''';
上述的代码我们以最简单的方式，去掉一切服务器交互，添加一个基础模型到游戏中跑动

再提醒一次，每次有代码修改后，运行前需调用命令进行编译
[[#编译]]

=== 播放人物的动作 ===
我们的人物有上下半身，在知道动画名字的情况下，需要分上下半身来播放动画

以'act_avatar_plant_collect'为例

<pre>
let animbaseStr = 'act_avatar_plant_collect';
role.model.playAniUp(`${animbaseStr}_up`);
role.model.playAniDown(`${animbaseStr}_down`);
</pre>

那么如何快速查看已有哪些动画呢？

[动作查看器](https://webdev.popx.com/v1/game/client_host.html?author=qc_jump&project=resourceviewer_0926&diyserver=1&gameid=0bkyyeesxnzsrd9s&editorFormal=true)

=== 添加按键控制 ===
看demo中的代码，提供了一个MoveComponent类
摇杆的显示资源放在'''res-extra'''目录中

[[File:摇杆资源.png]]

以下是示例中添加摇杆控制的代码
<pre>
//摇杆背景
let rocker = new XImage('res-extra/imgs/stick_bg.png');
rocker.width = rocker.height = 164;
rocker.pivotX = rocker.pivotY = 82;
rocker.pos(178, -198);
leftbottom.addChild(rocker);
//摇杆方向
let imgdir = new XImage('res-extra/imgs/stick_dir.png');
imgdir.centerX = imgdir.centerY = 0;
imgdir.anchorX = imgdir.anchorY = 0.5;
imgdir.name = "dir";
rocker.addChild(imgdir);
//摇杆中心点
let node = new XImage('res-extra/imgs/stick_rocker.png');
node.centerX = node.centerY = 0;
node.anchorX = node.anchorY = 0.5;
node.name = "node";
rocker.addChild(node);
//移动
let hero = this.heros.get(this.roleIndex);
if (hero) {
let movecomponent = rocker.addComponent(MoveComponent) as MoveComponent;
movecomponent.init(hero, ctrlayer, rocker);
}
</pre>

示例中，添加了一个触摸区域挂载在根节点的左下角，触摸反馈会根据'''XEvent'''来传递给节点
代码中根据摇杆方向变化来控制人物移动
其中涉及了部分修改玩家状态的服务器代码，可以先忽略

=== 摄像机的跟随 ===
代码中，摄像机跟随人物移动，只需要简单的一行
<pre>
let hero = new Xmodel();
//这是全局的摄像机
XPopManager.instance.xScene.camera.focus = hero;
</pre>

摄像机的旋转视角，demo中也提供了一个类'''CameraComponent'''
和摇杆的节点类似，通过'''XEvent'''来传递点击事件，
根据点击事件的拖动，来修改摄像机的旋转视角 '''xcamera.rotate'''
<pre>
private onCtrlMouseMove(e: XEvent): void {
if(this._touchId != e.touchId) return;
let xcamera = XPopManager.instance.xScene.camera as XCamera;
if(!xcamera)return;
if(this._mouseX == 0) this._mouseX = e.stageX;
if(this._mouseY == 0) this._mouseY = e.stageY;
let offx = e.stageX-this._mouseX;
let offy = e.stageY-this._mouseY;
this._mouseX = e.stageX;
this._mouseY = e.stageY;
xcamera.rotate(offx, offy);
}
</pre>
=== 砖块说明 ===
[[File:砖块说明.png]]

如图所示，我们的世界地图由若干个方形大'''地块'''组成，

每个地块里，可以划分成32*32的平面坐标，一层层叠高，可以有64层高，

转化为三维坐标系就是32*64*32，对应xyz轴，

地块上，可以添加以坐标为单位的'''砖块'''。

其中，cubeId表示砖块的类型，比如草地就是id为1的砖块，该砖块具有可以踩踏行走的特性。

某些其他的砖块具有别的特性，都通过cubeid来区分，当开发者接触地图编辑器时，就会有所了解。

我们以Demo中，'''MoveComponent'''中的一段代码来参考
<pre>
// 游戏世界地图
let scene = XPopManager.instance.xScene;
// 判断水平方向是否有砖块
// 根据坐标位置，找到世界中，其坐标对应的砖块id
let cubeid = scene.getCube(dir.x ,position.y, dir.z)
if(cubeid){
// 根据砖块id，找到砖块的类型，判断其是否和人物碰撞阻挡
scene.getCubeInfo(cubeid, this.cubeInfo);
if(this.cubeInfo.collisionPlayer){
dir.x = position.x;
dir.z = position.z;
}
}
//如果没有砖块或者有无阻挡砖块，给一个向下的位移
cubeid = scene.getCube(dir.x ,position.y-0.1, dir.z)
if(cubeid){
scene.getCubeInfo(cubeid, this.cubeInfo);
if(!this.cubeInfo.collisionPlayer){
dir.y = position.y-0.1;
}
}else{
dir.y = position.y-0.1;
}
</pre>

*再以图中为例，v3的坐标代表了地图上的位置，(24,3,26)
*如果需要设置模型在地图上的位置，用如下代码
<pre>
let pos = new XVector3(x,y,z);
xModel.position = pos;
</pre>

== 资源加载说明 ==

=== 演示加载图片 ===
<pre>
// 测试加载图片
// 创建一个全屏的挂载UI层
let mainui = new XImage();
mainui.left = mainui.right = mainui.top = mainui.bottom = 0;
XPopManager.rootNode.addChild(mainui);

// 图片路径，如果是本地的额外资源，就加上"res-extra/"前缀，否则就是远端资源
let path = 'avatarstart/ball_btn2.png';
// 创建图片
let img = new XImage(path);
// 添加到父节点显示
mainui.addChild(img);
// 设置位置
img.left = img.top = 100;
</pre>

编译，运行后，可以看到，添加了指定的图片

[[File:资源加载一.png]]

=== 公共资源 ===
PGT为开发者提供了很多基础的图片，模型，音频等等的资源。

====怎么查看有哪些公共资源呢？====

*打开项目目录下的package.json文件

[[File:资源加载二.png]]

===== 有sdkVersion =====
*调用查看当前的远端sdk版本，即资源版本，比如"sdkVersion": "1.0.15",
*具体有哪些资源版本可用，可以调用'''npm run sdklist '''来查看
*把下面链接里的v1.0.16替换成和你目前版本一致的数字，就可以查看远端资源列表

[[File:sdkVersion.png]]

[远端文件列表json](https://h5ppreview.jumpw.com/popion/sdk/v1.0.16/version.json)

===== sdkVersion>1.2.60的版本 =====

同样是查看pacakge.json，但是字段换成了"resVersion": "1.0.5"

resVersion

如下是1.0.5版本的资源列表，可以修改数字查找不同版本

[远端文件列表json](https://h5ppreview.jumpw.com/popion/popx-res/version-1.0.5.json)

也可以用命令来查找显示不同的资源版本

'''查看资源版本列表'''：npm run reslist (只包含正式发布的版本)

'''查看所有资源版本列表'''：npm run reslistall

===== 查看json文件 =====

*json文件左侧是游戏内加载的路径，右侧是实际的打过md5值的网络路径

[[File:资源加载四.png]]

这就是我们刚刚演示的加载图片

''avatarstart/ball_btn2.png": "avatarstart/ball_btn2-2c717f83a3.png''

*游戏内我们通过加载接口去加载左侧路径
*游戏外，直接在刚刚的cdnUrl后拼接带md5值的完整路径即可查看

[查看网络资源](https://h5ppreview.jumpw.com/popion/sdk/v1.0.17/avatarstart/ball_btn2-2c717f83a3.png)

[[File:资源加载五.png]]

*音频文件同理，模型文件直接游戏内调用接口显示

=== 额外资源 ===
最基础的demo中，会看到用于演示的摇杆资源是放在'''res-extra'''目录下的。

一般来说，开发者的一些特制UI，图形，可以放在这里。

加载时在路径前加上"res-extra/"即可。

*注意，我们目前不支持第三方模型文件，模型必须提交审核，不放在res-extra中

=== 模型查看器 ===
*除了图片资源外，为了方便开发者使用，我们额外做了一个模型查看器

[公共模型查看器](https://webdev.popx.com/client_host.html?author=qc_jump&project=resourceviewer_0926&diyserver=1&gameid=09kyye6gcmmda79s&editorFormal=true)

== UI界面开发 ==

=== git拉取ui工程到本地 ===

==== 泡饭的项目发布后获取到了git地址 ====
[[File:发布模板后获得git地址.png]]

==== 查看git密钥 ====

[[File:查看git密钥.png]]

==== 使用accesstoken来拉取项目到本地 ====

===== 常见的git工具中=====

git clone 地址

输入泡饭账号和accesstoken即可拉取，注意不是泡饭的密码，是token

===== 没有工具时用命令拉取说明=====

[[File:如何使用accesstoken拉取.png]]

=== 安装本地ui的编辑环境 ===

==== laya 版本 v2.13.1 ====
- [laya官方ide](https://ldc2.layabox.com/layadownload/?type=layaairide-LayaAir%20IDE%202.13.1)

==== 安装项目自定义封装的cmd命令库 ====
- 推荐安装方式：
<pre>
npm i popxcmd -g --registry https://registry.popx.com
</pre>

==== node 版本 v10.24.1 ====
- 必须使用指定的nodejs版本 ，推荐安装nvm以自由转换node版本。
- [nvm下载及安装方式](https://blog.csdn.net/ppz8823/article/details/130862191)

*记得nvm需要换源，否则后续安装可能会出错，按照下述操作

[[File:nvm换源.png]]

*最下面两行修改node和npm的镜像地址
<pre>
node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/
</pre>

*安装nvm后，命令行运行如下命令切换到node版本v10.24.1，一步步来:
<pre>
// 安装
nvm install 10.24.1
// 等待安装完成后，切换
nvm use 10.24.1
</pre>

*nodejs也需要用下面的命令来换源，修改镜像地址
<pre>
npm config set registry https://registry.popx.com/
</pre>

==== 修改host文件 ====
- 找到host文件，一般在`C:\WINDOWS\system32\drivers\etc`目录下。
- 在文件末尾添加：
<pre>
199.232.68.133 raw.githubusercontent.com
</pre>

=== 在编辑器中创建UI ===

如果开发者有额外的ui交互需求，希望在IDE中自己拼接UI

可以在指定目录下，去添加资源，一般来说，拼接scene即可，scene用到的资源要放在如下的指定目录中

* '''ui_laya/laya/''' - 开发者可以自由扩展的ui资源目录
* '''ui_laya/laya/pages''' - 开发者创建的.scene文件目录
* '''ui_laya/laya/assets/uiextra''' - secne文件中引用到的各种美术资源，包括音频和动画

==== 打开Laya工程 ====
使用指定版本的Laya编辑器打开 `demo/ui_laya/ui_laya.laya` 项目。

==== 添加.scene界面 ====
在编辑器中，可以添加一个新的scene界面，并在其上放置UI元素。

[[File:新界面.png]]

==== 界面添加UI组件 ====
例如，添加一个名为 `btnFirst` 的按钮，并确保其 `var` 属性有值，以便后续导出。

[[File:UI按钮有值.png]]

添加后，记得保存，'''ctrl+S'''

=== 额外资源的添加 ===

注意，所有上述scene中用到的美术资源，必须放在Assets/uiextra/ 目录下

否则导出ui时会失败

=== 运行生成UI命令 ===
在命令行中运行以下命令来生成UI代码：

<pre>
npm run ui
</pre>

-运行后，会在client目录代码中，生成对应的XUIComponent类，

-运行后，会更新'''res-extra'''文件夹下的fileconfig.json，该文件会把额外的资源列表记录下来

运行成功后，生成的UI类将位于 `src/ui/popxMaxUI.ts` 文件中。

[[File:UI生成代码.png]]

其中，添加了一个和scene名相同的UI类，
并且，var有值的组件也一起生成了对应属性。

每次在调用命令，npm run ui时，会更新上述的'''fileconfig.json'''文件。

*注意，UI资源使用前，要调用如下固定代码开启合图资源的配置，建议参考demo，在游戏入口就初始化调用一次
<pre>
XResManager.instance.enableAtlas("res-extra/fileconfig.json",()=>{
// 可以调用额外资源了
});
</pre>

=== 修改后的资源，git上传到远端 ===

注意：提交的文件里，最终要检查下如下内容，才能保证正常泡饭中正常使用。

1.修改后的ui内容，比如修改了mainUI.scene,对应的，在res-extra/ui文件夹下，mainUI.json就会有修改

2.res-extra目录里，有刚刚通过npm run ui 命令，拷贝过来的laya工程中的文件。

3.fileconfig.json里，有那些新增和改动的文件的配置。

上传后，泡饭即可使用

先git commit提交
注意推送时要用如下命令

git push --force

如果弹出输入框，账号输入泡饭账号名，密码输入accesstoken

[[File:新泡饭推送到远端.png]]

=== 代码控制XUIComponent ===
==== 注册UI类的控制文件 ====
使用 `PopxBridge.regUIClass()` 方法在相应的类中注册UI类，并处理UI相关的按键逻辑。
<pre>
//注册自定义的ui类
PopxBridge.regUIClass(DemoUI.getClassName(), DemoUI);
</pre>

以下是我们新加UI的最基础代码，在界面显示的时候，注册点击事件，点击后打印日志
<pre>
export class DemoUI extends uiextra.demoUIUI{

constructor(){
super();
}

onAwake(): void {

}

onEnable(): void {
// 设置在顶层可以被点击
this.zOrder = 1;
this.first_btn.on(XEvent.CLICK, this, this.onClickFirstBtn);
}

private onClickFirstBtn(e:XEvent){
console.log("click first btn");
}
}
</pre>

==== 代码调用显示UI ====
通过 `xUiManager.instance.openUI()` 方法来调用并显示UI界面。
<pre>
// 加载对应的json文件路径，并挂载在指定父节点上
XUiManager.instance.openUI('res-extra/ui/demoUI', XPopManager.rootNode);
</pre>

-编译，运行

[[File:UI点击按钮.png]]

==== 代码调用加载组件 ====
*某些界面上的元素，比如卡牌，也可以类似做成一个scene，运行npm run ui 自动生成类
*比如类名为CardView
*注册和UI注册类似
<pre>
PopxBridge.regUIClass(CardView.getClassName(), CardView);
</pre>
*创建时，调用`XUiManager.instance.createView`
<pre>
XUiManager.instance.createView(path,parent,this.onLoadCardView,showData);

onLoadCardView(view:XUIComponent)
{
}
</pre>

== 前后端数据交互 ==

该篇会讲述服务器和前端的数据同步，如果想要先了解项目目录和工作流，建议先参考如下篇幅
[[#主要工程目录]]

=== 进入房间（游戏世界） ===
如下是最基本的开发登录流程说明
{| class="wikitable"
|-
! 步骤
! 描述
! 流向
|-
| 开始
| 流程的开始
| -> 登录页面
|-
| 登录页面
| 账号密码，选定地图，输入房间号（可不填）
| -> 远端服务器（官方）
|-
| 远端服务器（官方）
| 获取玩家账户信息，分配到房间,房间就是我们的host代码
| -> Client 和 -> Host
|-
| Client
| 监听XPopManager.onGameStart
| -> 前端逻辑开始
|-
| Host
| 监听XPopManager.onHostStart
| -> 房间战斗逻辑开始

|}

远端服务器(官方)会处理最基本的登录，分配房间，创建游戏世界的逻辑，并且同步该世界中的游戏数据。

通过'''XpopManager'''管理类，来向Client和Host抛出事件，开发者可以监听这些事件做处理。

开发者需要关心的逻辑，就是Clint和Server（上图中Host）目录下的代码。

=== 前后端协议交互 ===
项目采用proto来做相互通信

=== 前后端共用配置 ===
前端'''src/client'''目录和后端'''src/server'''目录中，都可以调用如下代码来加载所有的表格配置
<pre>
CsvManager.ins.loadCsvs(this, () => {
// Do some thing after load
});
</pre>

表格的加载逻辑和解析逻辑，可以参考CsvManager中的代码
'''src/shared/csv/CsvManager.ts'''

''如何新增配置?''
以demo中的'''item.csv'''为例.
*1.配置csv文件资源的根目录为'''res-extra/csv/''' ,在里面添加'''item.csv'''
*2.'''CsvManager.ts'''文件中，添加读取表格和解析表格的逻辑
<pre>
// loadCsvs代码中，添加你需要解析的csv名称
public loadCsvs(caller: any = null, listener: Function = null) {
let assets = [
this._prefix + "item.csv",
];
// XResManager加载本地资源
XResManager.instance.loadText(assets, () => {
// 在加载完成的回调中，处理表格数据结构，生成CItemData，不再赘述
this.onCompleted(caller, listener);
});
}
</pre>
*3.解析表格得到的'''CItemData'''结构，定义在'''src/shared/dataMgr/'''中，可以被前后端一起调用
*4.如果是加载json文件，用'''XResManager.instance.loadText'''

=== 玩家战斗数据快照 ===
游戏战斗服务器中，每个玩家的实时信息，通过快照来更新
==== XVF_SnapData ====
以demo中的'''Snap_UserData.ts'''为例
*该玩家数据中类中，包含的各种public变量，都是''XVF_SnapData''接口类型
<pre>
export class Snap_UserData {
//坐标旋转
public position: XVF_SnapData<SyncPos>;
//状态
public state: XVF_SnapData<SyncState>;
//hp
public hp: XVF_SnapData<number>;
}
</pre>
快照类型数据，前端负责注册和监听，服务器负责修改
*每次该接口类型的数据发生变化时，会调用OnSet方法，这类数据的修改逻辑是：服务器修改，前端监听变化
** 前端登录成功后，服务器注册对应玩家数据
** 前端对数据中的某个XVF_SnapData做监听，注册OnSet方法
** 服务器战斗逻辑修改了该数据时，前端根据OnSet的逻辑做表现处理

服务器先注册全局的快照
<pre>
let userData = new Snap_UserData();
XPopManager.instance.xHost.RegisterSnapshot(`UserData${i}`, userData);
</pre>

前端绑定同一个地址的快照
<pre>
this._userData = new Snap_UserData();
XPopManager.instance.xRemote.RegisterSnapshot(`UserData${index}`, this._userData);
</pre>

*XVF_SnapData数据，如果是复杂类型，需要调用UpdateData()方法，前端才能触发OnSet
如下的SyncState就是复杂类型
<pre>
public state: XVF_SnapData<SyncState>;
public setState(key:string, obj:string):void{
this.state.value.key = key;
this.state.value.obj = obj;
this.state.UpdateData();
}
</pre>
*XVF_SnapData如果是基础类型，不需要调用UpdateData()
<pre>
public hp: XVF_SnapData<number>;
public setHP(hp:number):void {
this.hp.value = hp;
}
</pre>

=== 代码如何调试 ===
==== 前端调试 ====
直接在网页上调试

f12打开控制台，

点击源代码，

可以根据代码目录结构找到想要断点的文件，

也可以快捷键"ctrl + p"输入文件名查找（mac上是cmd + p）,

找到后，点击具体左侧代码行数标签即可。

可以很方便的观察堆栈和变量信息

[[File:网页断点调试.png]]

==== 服务器调试 ====
*启动运行时，会弹出一个host弹窗服务器在调用命令'''npm run server'''后，会启动一个Host网页

[[File:服务器host.png]]

*只要是网页，那就能调试js代码
*打开网页的开发者工具（一般浏览器是f12）,找到'''index.js'''文件

*该文件是由服务器代码入口index.ts编译生成的js文件，注意，不止是index.ts，里面相关的引用代码都会编进去

*虽然代码经过编译，但是没有混淆，可以通过函数名，找到js代码中的行号，打断点

[[File:服务器断点.png]]

==== 调试注意事项 ====
*每次'''npm run build'''后，如果修改了服务器代码，可以在本地host的浏览器里，立刻刷新，F5或者shift+f5
*如果修改了编译脚本来调试服务器，记得最后打包上传前，把rollup的代码改回来

== 地图的制作和选取 ==
=== 地图制作导出 ===

[[File:地图编辑视频.png]]

教学视频已经上传到网页链接

[新建地图](https://formalhead.popx.com/popxVedio/mapeditor/新建地图.mp4)

[地块操作](https://formalhead.popx.com/popxVedio/mapeditor/地块操作.mp4)

[地块（水）](https://formalhead.popx.com/popxVedio/mapeditor/地块（水）.mp4)

[地形设置（增加）](https://formalhead.popx.com/popxVedio/mapeditor/地形设置（增加）.mp4)

[新地编添加预制件和编辑](https://formalhead.popx.com/popxVedio/mapeditor/新地编添加预制件和编辑.mp4)

[预制件操作](https://formalhead.popx.com/popxVedio/mapeditor/预制件操作.mp4)

[授权给他人使用](https://formalhead.popx.com/popxVedio/mapeditor/授权.mp4)

[如何游戏内绑定后台玩法和地图](https://formalhead.popx.com/popxVedio/mapeditor/如何游戏内绑定后台玩法和地图.mp4)

=== 开发环境选择地图 ===
我们在登录界面，可以通过填写你gameid中的地图名字，来进入指定地图。

所以必须要先创建gameid，并且选择至少一张地图，该地图才能在调试时进入。

举例：

*上传地图到某个游戏gameid时，会从你自己的'''可用地图'''中选择。

- 可用地图指的是你自己制作上传了地图。或者其他人共享给了你地图。

*比如你的可用地图名字是"推箱子"。

*右边会有可填写的自定义地图名字，比如"第一关"

那么登录的时候就是填写 "第一关"

*'''也就是说，地图做完后，必须要在审核平台上，添加到玩法里，生成自定义的名字，才可以在测试时填写进去生效 '''

== 打包与上传 ==

[[File:泡饭点击发布游戏.png]]

点击发布后，会把构建生成的压缩包上传到远端，就可以去试玩了。

=== 玩法测试 ===

[[File:泡饭点击打开审核后台.png]]

* [[上传流程|查看文档中试玩/审核/发布的部分]]

== 项目目录 ==

=== 主要工程目录 ===
对于开发者，需要关心和操作的目录如下：

* '''node_modules/''' - 通过npm安装的PGC库文件，对外暴露的方法，可以通过bridge.d.ts来外部引用
* '''res-extra/''' - 开发者除了PGC的远程资源外，需要额外使用到的资源目录，比如UI，图片，音频，表格，最后会打包上传到PGC远端资源服务器
* '''ui/''' - 开发者自己在laya编辑器中，拼接的界面json文件，运行命令后，会转化为PGT指定的XUIComponent存放于此
* '''src/''' - 开发者所有的战斗逻辑代码修改都在此进行
* '''src/client/''' - 前端代码，入口文件index.ts，监听XPopManager.onGameStart，前端游戏逻辑
* '''src/server/''' - 后端代码，入口文件index.ts，监听XPopManager.onHostStart，后端游戏逻辑
* '''src/shared/''' - 前后端共用的数据结构，包括表格，协议，玩家数据
* '''dist/''' - 编译后，生成的运行文件，包含前后端代码
* '''dist/client/''' - 编译后生成的混淆的前端代码
* '''dist/host/''' - 编译后服务端的代码文件，里面也包括表格数据的缓存

=== 前后端协议通信生成 ===

[[File:泡饭点击生成协议.png]]

==== 协议通信 ====
该命令会用到tsrpc的proto协议，
把'''src/shared/protocols'''下的指定格式文件，
转换到'''src/shared/protocols/generated/serviceProto'''文件中，

* 文件名为：Ptl{接口名}.ts '''（Ptl 是 Protocol 的缩写，l是小写的L）'''
* 请求类型名为： Req{接口名}，通过 interface 或 type 定义，需 export
* 响应类型名为：Res{接口名}，通过 interface 或 type 定义，需 export

例如，添加'''PtlPosition.ts'''文件
文件代码如下
<pre>
// 该接口用于向服务器同步自身的坐标
export interface ReqPosition {
i: number;
x: number;
y: number;
z: number;
ry: number;
}
export interface ResPosition {
ret: string;
diy: string;
}
</pre>

'''serviceProto.ts'''中会增加可外部调用的api类型
<pre>
export interface ServiceType {
api: {
"Position": {
req: ReqPosition,
res: ResPosition
},
},
msg: {

}
}
</pre>

'''前端代码调用请求'''
<pre>
// 前端可以用promise语法来调用同步位置的Request，异步处理服务器的返回值
let remote = XPopManager.instance.xRemote;
let ret = await remote.Request('Position', {i: 1, x:2, y:3, z:4, ry:5});
if(ret && ret.isSucc){
console.log(ret.res.diy)
}
</pre>

'''后端代码监听请求处理返回'''
<pre>
// 服务器收到前端请求的处理返回RegisterRpc
let host = XPopManager.instance.xHost;
//当收到坐标变化请求
host.RegisterRpc("Position", async (call: ApiCall<ReqPosition, ResPosition>) => {
let index = call.req.i;
let userData = this.usersData.get(index);
userData.setPosition(call.req.x, call.req.y, call.req.z, call.req.ry);
return call.succ({
ret: "Success",
diy: "自定义参数"
});
});
</pre>
如果想更多了解proto的结构和数据类型说明，可以参考官方链接
[tsrpc-proto格式说明](https://tsrpc.cn/docs/server/service-proto.html)

== 核心类目说明 ==
=== XPopManager ===
Bridge.d.ts中的核心类

对游戏逻辑进行了结构化的拆封和管理，

可以理解为，

库文件内处理了各种玩家的逻辑，比如登录，加载地图，分配房间，快照数据同步等等,然后关键的几个节点，暴露给外部去执行游戏逻辑。

开发者只需要去编写独立游戏模块的代码，其中，'''Xremote'''暴露给前端处理，'''Xhost'''暴露给后端处理

下面是最重要的几个生命周期函数
;onGameStart:玩家已经完成了登录步骤，已经分配好了房间，通知前端游戏开始
;onHostStart:玩家已经完成了登录步骤，已经分配好了房间，通知后端游戏开始
;onGameOver:游戏结束（一般是玩家都离开了战斗房间）
;onUpdate:每一帧会调用更新

我们在demo中，index.ts里，可以给这几个方法监听绑定函数，输出日志就可以查看

<pre>
XPopManager.onGameStart = ()=>{
new Main();
console.log("qc,XPopManager.onGameStart");
}

XPopManager.onGameOver = () => {
console.log("qc,XPopManager.onGameOver");
}

XPopManager.onHostStart = () => {
console.log("qc,XPopManager.onHostStart");
}

XPopManager.onUpdate = () => {
console.log("XPopManager.onUpdate");
}
</pre>

[[File:XPopManager生命周期.png]]

=== XRemote(前端) ===
*以下是最关键的生命周期和方法调用，调用逻辑可以自定义设计，后端代码同理
;UserID:玩家进入游戏的唯一id
;onUserEnter:每当房间内玩家进入时会调用，前端可以在此根据返回的userId来同步XHost玩家的快照数据，创建角色等等
;onUserLeave:每当房间内玩家离开时会调用，前端根据userId来处理模型的销毁
;RegisterSnapshot:用于注册绑定快照，快照类型开发者自定义，需要和XHost代码中绑定的地址一致，才可以收到OnSet回调
;Request:发送RPC请求，请求和回调的代码由protocol生成

=== XHost(后端) ===
;onUserEnter:每当房间内玩家进入时会调用，初始化玩家身上的快照数据，可以根据人数来判断游戏阶段，比如准备阶段
;onUserLeave:每当房间内玩家离开时会调用，清理玩家数据，可以根据玩家人数来判断是否进入结算或者游戏结束
;RegisterSnapshot:用于注册绑定快照，快照类型开发者自定义，需要和XRemote代码中绑定的地址一致
;RegisterRpc:注册RPC回调

=== XUIComponent(UI组件) ===
UI组件通过XUiManager.instance.OpenUI或者XUiManager.instance.CreateView加载显示
;showUI:调用后会设置active为true，当调用创建的方法，加载成功显示时也会调用一次，可以在创建时传参，每次主动调用也可以传参。
;hideUI:把该组件的active设置成false
;closeUI:把该组件从父节点移除，可以传参处理移除成功时的回调
=== XEventDispatcher(事件)===
我们可以根据已有的XEventDispatcher来封装一个单例，这样就能外部夸文件调用事件了。
如下为演示封装的单例
<pre>
export class EventManager extends XEventDispatcher{

constructor () {
super();
}

private static _instance: EventManager
public static get instance(): EventManager {
if (!this._instance) { this._instance = new EventManager(); }
return this._instance;
}

}
</pre>

事件的派发
<pre>
EventManager.instance.dispatch("new_event_name", ...args);
</pre>

事件的监听
<pre>
EventManager.instance.add("new_event_name", this, this.ParseNewEvent);

private ParseNewEvent(...args)
{
console.log("parse new event")
}
</pre>

== 泡饭实用工具 ==

[[File:泡饭工具.png]]

=== 模型查看器 ===
=== AI对话 ===
=== AI语音生成 ===
=== AI图转3d模型 ===

== 常见工作流问题 ==
=== 如何把本地的项目上传到泡饭 ===
==== 建议先上传项目到自己的git仓库 ====
==== 从git拉取 ====

点击图中创建模板按钮，从git创建工程

[[File:点击从git创建工程.png]]

[[File:git项目地址.png]]

== 官方论坛 ==
*[论坛地址](https://bbs.popx.com/)
*可以由我们内部人员给出的邀请链接申请加入论坛。
*申请后，等待审核人员核实，批准后，即可浏览论坛内容，发表疑问贴。
*强烈建议多去论坛搜索关键字，发帖会有对应的专业人员回答问题，大家一起维护论坛生态。
*常见问题faq帖子会持续维护

[论坛FAQ](https://bbs.popx.com/t/topic/53)

大厅功能

2025-02-19T10:03:31Z

Liuweichen：/* 项目demo地址 */

== 老项目升级环境配置 ==
=== 项目demo地址 ===
泡饭中，hall_test模板，有完整代码

* [[File:泡饭大厅工程.png]]

下载模板

我的工程打开hall_test模板

编译&启动(大厅)

=== demo体验地址 ===

[试玩链接]( https://subgame.popx.com/popion/master.html)

* 如果是新号，在PC端ctrl +6，打开特殊窗口，输入 “isover 1”,点击按钮，可直接跳过新手流程!
* [[File:跳过引导.png]]

* 在游戏界面游玩中，找到demox，点击进入即可
* [[File:Demo地址.png]]
=== 添加src/hall/index.ts的大厅服务器入口文件 ===

* [[File:添加hall入口.png]]

=== 修改打包配置rollup ===

* rollup.config.js新增打包大厅index.js的配置

* [[File:rollup配置.png]]

* rollup.config.js加一下服务类的白名单

* [[File:rollup白名单.png]]

=== 修改html启动文件 ===

* 拷贝覆盖index.html到你的项目中，拷贝hall.html本地大厅文件到同一文件夹下

* [[File:html入口.png]]

=== 审核后台勾选大厅 ===

* [[File:勾选大厅.png]]

'''只有勾选了大厅后，登录流程才会走大厅的逻辑，否则是走的老的流程，直接进战斗房间'''

== 大厅游戏工作流说明 ==
大厅工程相对于原来的client，server目录结构，多了一个hall目录，而且server实际上指的是host，

每个目录的代码文件入口都在各自的'''index.ts'''里

[[File:大厅文件结构.png]]

为了方便大家理解，我们用颜色来标记各个核心文件夹的工作流

'''client'''用橙色，代表前端显示，前端逻辑

'''hall'''用绿色，代表大厅，大厅服务器逻辑

'''host'''用蓝色，注意，为了不和开房间混淆，host代表的是战斗服务器逻辑，而不是和以前一样叫做房间

'''client的入口代码最早执行，在里面做各种监听，也就是说，大厅期间，各种前端界面UI就已经能自己处理了，可以调用大厅的数据'''

'''以下的流程，如果审核后台勾选了大厅，按照顺序执行，否则直接跳过大厅，到了《进入战斗》'''

=== 游戏开始时 ===

==== 进大厅前预加载资源 ====

'''client:'''XPopManager.onHallWait

--在进入大厅前，会有一个promise的异步接口供开发者使用去预加载资源，比如表格，比如读取文件配置等等。

'''必须在加载完成的回调中resolve'''

<pre>
//预加载资源
XPopManager.onHallWait = new Promise((resolve)=>{
GameManager.instance.onPreLoadRes(()=>{
resolve("Resource loaded successfully hall");
});
});
</pre>

==== 进入大厅 ====

'''client:'''XPopManager.onHallStart

--在大厅资源预加载完成后，会直接启动大厅服务器实例

'''hall:'''XPopManager.onHostHallStart

--src/hall/index.ts 中监听的代码入口

=== 大厅期间操作 ===

==== 监听大厅内数据变化 ====
大厅期间，hall的实例会监听各种玩家的事件，并且抛出回调，开发者可以在回调中处理hall的快照数据

hall的实例是指XPopManager.instance.xHostHall

'''hall:'''hall.onUserEnter

--大厅内有玩家进入

'''hall:'''hall.onUserLeave

--大厅内有玩家离开

'''hall:'''hall.onUserMatchChange

--大厅内匹配信息发生变化，主要是指倒计时的变化

'''hall:'''hall.onDbItemChange

--大厅内存盘的数据变化，在进入时就会调用一次，获取到账号DB数据，'''存盘'''后面再说

==== 开始匹配 ====

匹配内容后面单独讲

==== 匹配成功 ====
后面匹配内容会单独讲，
匹配成功后，分配到了某个房间的实例（host）,并且会把匹配时的透传参数通知给host实例

=== 进入战斗 ===
'''host:'''XPopManager.onHostStart
--src/server/index.ts 中监听的代码入口，去处理host实例的各种回调

=== 战斗期间操作 ===
==== 监听host战斗服内数据变化 ====
host的实例是指XPopManager.instance.xHost
'''host:'''host.onUserEnter

--当战斗服务器内有玩家进入

'''host:'''host.onUserLeave

--当战斗服务器内有玩家离开

'''host:'''host.onUserMatchExtraDataReceived

--当战斗服务器收到玩家透传信息(匹配时传入的ExtraData)

'''host:'''host.onDbItemChange

--当战斗服务器收到存盘的数据变化，在进入时就会调用一次，获取到账号DB数据，'''存盘'''后面再说

=== 战斗返回大厅 ===

'''client:'''XPopManager.onGameLeave

--返回到大厅，大厅的数据还在快照中，可以做一些结算的处理

想要回到大厅，需要手动调用'''XPopManager.instance.xRemote.LeaveGame '''
，demo里有示例
<pre>
XPopManager.instance.xRemote.LeaveGame(this, (code: number, ret: string) => {
console.log('LeaveGame', code, ret);
});
</pre>

=== 离开整个游戏 ===
'''client:'''XPopManager.onExit

--在试玩的时候，点击官方左上角的退出，会进入此回调函数

--平时本地调试开发时，不需要去处理这个回调

--但是试玩时需要在此销毁场内资源，否则，退出后再次进入，会发现上一回的模型还在

<pre>
XPopManager.onExit = () => {
model.destroy();
}
</pre>

== 前后端数据交互 ==
'''交互只能client和hall,client和host之间互通信息，不能hall和host直接交互'''
=== client和hall的交互 ===
所有的和大厅的数据交互，依赖于

client内部代码：this._remoteHall = XPopManager.instance.xRemote.hall

hall内部代码：this.hall = XPopManager.instance.xHostHall

具体代码位置在各自文件夹内

*1.client向hall注册快照，并且监听快照变化
*2.hall注册rcp请求的回调方法
*3.client向hall发起rpc请求
*4.hall处理rpc请求，hall修改快照
*5.client监听快照变化的回调，处理显示逻辑

具体可以查看MessageManager中的代码

==== client注册快照 ====

代码里有私有和共有快照，实际上本质上都是最基本的注册快照，只是在hall里面处理数据的方式不一样，具体可以看代码，不再赘述
<pre>
this._remoteHall.RegisterSnapshot(`${Snap_HallData.tag}`, this._hallData);
</pre>

==== client监听快照变化 ====
<pre>
this._hallData.notice.OnSet = (bReset) => {
XTipManager.Instance.showTip(this._hallData.notice.value);
}
</pre>

==== hall注册rpc回调 ====
<pre>
this.hall.RegisterRpc('AddDbItem', this.onReceiveAddDbItem.bind(this));
</pre>

==== client发起rpc请求 ====
<pre>
public async Hall_Request_AddItem(type:DBItemType, itemID:ItemNormalID, itemNum:number, callback?: Function): Promise<void> {
let ret = await this._remoteHall.Request("AddDbItem", { type: type, actorID: this._userID, itemID: itemID, itemNum: itemNum });
console.log('requestAddDbItem', ret);
callback && callback(ret);
}
</pre>

==== hall处理rpc请求，修改快照 ====
<pre>
private async onReceiveAddDbItem(call: ApiCall<ReqAddDbItem, ResAddDbItem>): Promise<void> {
console.log('>>>>>>onReceiveAddDbItem');
// 修改某个快照，前端已经注册过处理函数
}
</pre>

=== client和host的交互 ===
所有的和战斗服的数据交互，依赖于

client内部代码：this._remoteBattle = XPopManager.instance.xRemote.game;

host内部代码（server文件夹）：this.host = XPopManager.instance.xHost;

所有的流程和hall一样处理

== 数据存盘 ==
数据存盘对应的是玩家登录时的账号id，调用存盘后，就有账号的长期数据可以记录和读取了

=== 存储 ===
'''存储只能由hall或者host发起，两个服务器都有同名的存储接口'''

'''该功能没有必要接入大厅，直接调用host中的代码接口也可以存储和读取'''

'''调用该功能前，请务必根据自身gameid向我们内部申请一个对应的数字id来存盘使用'''

demo中，写在了hall里面，host里也可以写一份一样的，这样战斗和大厅的数据就都能存储了.

如下示例代码的发起方是client通过rpc去通知hall发起的，实际上可以在服务器计算过程中自己发起

说几个关键的参数：

*dbID

-- 需要开发者在我们的审核后台，获取了游戏id之后，把游戏id的字符串给我们的内部人员，
-- 然后我们帮开发者映射生成一个数字的id，专门来存储该游戏的数据，
-- 以后存盘读盘时就走的这个数字id

*type

-- 存盘的时候还有个type，支持填写0到9，可以用于开发者处理不同类型的数据分类。
-- 比如0代表货币类型，1代表背包道具，2代表头像。。等等
-- 当然，全存在一个type里也没影响，因为可以根据唯一的itemID去读自己的表格

*itemID

-- 开发者存储时的自定义id，用于自己游戏内的道具表格映射，请保持id的唯一性，不要有同id的道具

<pre>
private async onReceiveAddDbItem(call: ApiCall<ReqAddDbItem, ResAddDbItem>): Promise<void> {
console.log('>>>>>>onReceiveAddDbItem');
let userdata = this._usersMap.get(call.req.actorID);
if (!userdata) {
return;
}
if(call.req.type == DBItemType.Normal && call.req.itemID == ItemNormalID.Gold){
let ret;
if(userdata.goldCount.value == -1){
let item = new XDbItem();
item.nID = call.req.itemID;
item.nCount = call.req.itemNum;
ret = await this.hall.AddDbItem(this.dbID, call.req.actorID, call.req.type, call.req.itemID, item, this);
}else{
ret = await this.hall.SetDbItemCount(this.dbID, call.req.actorID, call.req.type, call.req.itemID, call.req.itemNum+userdata.goldCount.value, this);
}
return call.succ({
ret: ret.ret
});
}else{
return call.succ({
ret: '未实现'
});
}
}
</pre>

=== 读取 ===

在hall和host中，都有一个监听函数
<pre>
XPopManager.instance.xHostHall.onDbItemChange;
XPopManager.instance.xHost.onDbItemChange;

</pre>

每次当存盘的数据发生变化，都会进入该回调函数。
'''hall和host连接成功后，也会先进入一次，所以进游戏就能获得存盘数据'''

我们以hall里的代码举例

<pre>
private onDbItemChange(type: number, key: number, value: XDbItem | null, iUserID: number, bReset: boolean):void{
if(type == DBItemType.Normal && key == ItemNormalID.Gold){
let userdata = this._usersMap.get(iUserID);
if (!userdata) {
return;
}
userdata.goldCount.value = value.nCount;
}
}
</pre>
*type
-对应传入的type
*key
—对应存储的itemId
*value: XDbItem

其中，XDbItem的结构是我们DB中固定的格式，外部只需要关心nID和nCount即可

nID对应存储时传入的唯一itemId
nCount对应DB中该物品的数量

* [[File:db存储结构.png]]

=== KeyValue数据存盘 ===
简单的物品类型并不足以支持复杂的游戏数据结构，我们也提供了和物品存储类似的数据结构存储

同样是在hall和host中都可以调用

监听的函数用'''onDbDataChange'''
<pre>
XPopManager.instance.xHostHall.onDbDataChange;
XPopManager.instance.xHost.onDbDataChange;
</pre>

存储的函数用SetDbDatas

<pre>

// 存储设置自定义key-value
ret = await this.hall.SetDbData()
// 存储整个map的keyvalue合集
ret = await this.hall.SetDbDatas()
</pre>

* [[File:存盘复杂数据.png]]

如函数参数中所示，存储的value是string类型，

那么可以通过JSON.stringify(obj)和JSON.parse(str)来相互转换，从而存储复杂数据

* 注意:如上是hall的存储读取示例，如果想用host，接口类似，在如下的论坛帖子里有演示。

[host存储数据](https://bbs.popx.com/t/keyvalue-ondbdatachange/207/14?u=qc_jump)

== 匹配逻辑 ==

匹配逻辑在hall中处理

=== 创建匹配规则 ===

匹配前，一定要创建至少一个匹配规则的名称，否则无法匹配

参考demo中，在hall代码的初始阶段就要设置

如下是添加了更加详细的注释代码，其中段位相关的规则可以先不添加

<pre>
/**
* 初始化匹配规则
*/
private initMatchRule(): void {
let rules = new XMatchRule();
// 需求人数必填
rules.nRoleNum = Config.MatchNumMax;
// 地图列表 - 匹配成功后，会从中随机创建一个地图必填,如果填一张就是唯一一张图
rules.addMapName(this.matchMapName);

// 选填更复杂的段位规则,根据段位来设置规则，如果不添加，就会无规则随意匹配
{
for(let i =0;i<9;i++)
{
let duanLevel = i+1;
this.addRulesDuan(rules,duanLevel)
}
}
// 调用添加matchRuleName为key的匹配规则，可以调用添加多个，
// 添加后，才可以通过this.hall.UserBeginMatch，根据matchRuleName进行匹配
this.hall.AddGameMatchRules(this.matchRuleName, rules, this);
}
</pre>

*通过this.hall.AddGameMatchRules(this.matchRuleName, rules, this);来添加至少一条匹配规则，

*其中matchRuleName为key，可以多次添加不同的key和rules

*必须添加至少一条规则后，才可以通过this.hall.UserBeginMatch，'''根据matchRuleName来映射到具体规则和地图列表，进行匹配'''
==== 详细段位规则 ====
上面的基础规则代码中，有一部分在添加段位规则，并且一个XMatchRule对应了多个段位规则

<pre>
private addRulesDuan(rules: XMatchRule,duanLevel:number = 1):void
{
let danRule = new XDanRule();
// 匹配分数区间,匹配时，根据传入的分数，来找到符合区间的duanRule，找不到那就没有规则
danRule.nMinScore = (duanLevel - 1) * 1000;
danRule.nMaxScore = duanLevel * 1000;

// 比如初始分数区间为1000-2000，
// 玩家是1500分，玩家就匹配到了这个段的规则

// 每个匹配规则里，可以分成多个段位，比如青铜，王者，通过id来区分各个段位的匹配规则
danRule.nDanID = duanLevel;

// 1阶段匹配时间
danRule.nMatchTime1 = 15;

// 1阶段时，可以根据震荡区间来扩大搜索范围.比如本身是匹配1000-2000，添加后变成了900-2100
danRule.AddScore = 100;

// 1阶段的时间结束，房间人还没满，会进入2阶段

// 2阶段匹配时间
danRule.nMatchTime2 = 15;
// 2阶段时，可以根据震荡区间来扩大搜索范围.比如本身是匹配1000-2000，添加后变成了1800-2200
danRule.AddScoreMax = 200;

// 匹配2阶段后，是否塞人机数量
// 已经实现了把人机的数据塞进战斗房间
// 比如XMatchRule里的nRoleNum = 8，nAINum = 2，那么当房间人数为6时，就会进入游戏（2阶段后）
danRule.nAINum = Config.MatchNumMax - Config.MatchNumMin > 0 ? Config.MatchNumMax - Config.MatchNumMin : 0;
rules.addDanRule(danRule);
}
</pre>

<pre>
// 可以通过接口来获取具体的玩家信息，玩家信息中有字段来标记是否为机器人
// host接口
XPopManager.instance.xHost.GetUserInfo(userid).isRobot
// 前端接口
XPopManager.instance.xRemote.GetUserInfo(userid).isRobot
</pre>

=== 通过匹配规则匹配 ===
*'''matchRuleName'''必须要先添加
*rankScore对应匹配规则中的分数，根据实际开发的业务数据来，分数会对应到详细的段位规则里
*'''ExtraData'''是透传参数，可以在匹配成功进入战斗服中获取到

<pre>
private async onReceiveStartMatch(call: ApiCall<ReqStartMatch, ResStartMatch>): Promise<void> {
console.log('>>>>>>onReceiveAddDbItem');
let match = new XMatchRole(call.req.actorID);
match.ruleName = this.matchRuleName;
match.rankScore = 0;
//匹配透传数据
match.ExtraData = JSON.stringify({heroID:101});
let ret = await this.hall.UserBeginMatch(call.req.actorID, match, this);
return call.succ({
ret: ret.ret
});
}

</pre>

=== 取消匹配 ===
<pre>
private async onReceiveCancelMatch(call: ApiCall<ReqCancelMatch, ResCancelMatch>): Promise<void> {
let ret = await this.hall.UserCancelMatch(call.req.actorID, this)
return call.succ({
ret: ret.ret
});
}
</pre>

=== 匹配状态变化 ===
开始匹配和取消匹配都会通过回调来通知给hall，

可以根据开始时间，来处理倒计时等显示的逻辑
<pre>
// 绑定
this.hall.onUserMatchChange = this.onUserMatchChange.bind(this);
</pre>

<pre>
private onUserMatchChange(iUserID: number, ruleName: string, matchTime: number): void {
let userdata = this._usersMap.get(iUserID);
if (!userdata) {
return;
}
userdata.matchTime.value = matchTime;
console.log('onUserMatchChange', iUserID, ruleName, matchTime);
}
</pre>

=== 匹配成功 ===
匹配成功后会进入战斗服务器，host，上面的完整流程已经提过

并且会收到匹配时传入的透传参数'''ExtraData'''

<pre>
this.host.onUserMatchExtraDataReceived = this.onUserMatchExtraDataReceived.bind(this);
</pre>

== 开房间 ==

开房间功能建议在试玩链接里体验，目前房间列表只在试玩里开放

=== 接入开房间组件 ===
参考demo中HallUI的代码，一行即可,在点击创建房间按钮后触发

<pre>
XPopManager.instance.advancedComponentMgr.addComponent("CreateRoomComponent");
</pre>

房主在大厅内点击创建房间
* [[File:创建房间.png]]
创建房间可以选择地图，具体能选择的地图需要在审核后台配置

其他人加入房间
* [[File:创建房间2.png]]
* [[File:创建房间3.png]]

=== 房间内显示逻辑 ===

*'''强调一个概念，开房间组件，相当于是在大厅里，忽略了匹配过程，直接把玩家拉到了host里面'''

*'''在房主创建房间进入时，以及其他人在大厅找到房间进入时，都会触发host的onUserEnter'''

* 匹配时，我们一直在强调匹配规则的key，在进入host时，我们可以根据是否存在匹配规则的key，来判断是匹配进入，还是房间组件进入
<pre>
let ruleName: string = this.host.GetMatchRuleName();
</pre>

* [[File:判断战斗快照.png]]

*此时，界面内的显示需要根据host是否是房间状态来处理
-- 房间状态就显示各种座位的人员信息
-- 战斗状态就进入战斗逻辑（其实都是战斗服务器里的逻辑）
-- 具体的状态管理可以参考demo代码，由开发者自己写状态机

== 启动本地大厅 ==
本地调试时，登录界面，勾选本地大厅即可
* [[File:勾选本地大厅.png]]

只要勾选一个本地大厅就可以了，另一个账号登录时也会进入此大厅

2025-02-19T05:53:43Z

Liuweichen：

文件:服务器host.png

2025-02-19T05:53:33Z

Liuweichen：

泡饭工坊项目流程

2025-02-19T05:53:19Z

Liuweichen：/* 本地服务器调试 */

== 泡饭工坊介绍 ==
===泡饭工坊是什么？===
泡饭是一套网页虚拟环境下的代码编辑工具，内嵌了多种预设和模板，集成了vscode来编辑代码，自动编译，可以方便的预览和分享给小伙伴体验。
=== 泡饭链接 ===
[链接](https://webdev.popx.com)

=== 泡饭账号注册登录 ===

==== 没账号的需要在泡饭注册账号 ====

[[File:新注册账号手机号.png]]

'''请记住您的账号密码，这关系到后续我们管理您的使用权限'''

==== 和我们内部人员沟通，申请后台权限 ====

'''如需开通后台使用权限，将您的账号告知我们内部人员帮操作，等待通知完成后，重新刷新网页即可'''

==== 第一次需要创建一个工程 ====

[[File:新点击模板商店创建模板.png]]

[[File:新模板下载.png]]

[[File:新下载工程.png]]

==== 有了工程后，打开工程 ====

[[File:新打开我的工程.png]]

== 打开泡饭体验项目 ==

参考视频[1.泡饭运行环境演示.mp4]

== 如何用泡饭开发自己的项目 ==

=== 点击跳转后台 ===

===='''就第一次需要创建打开一个工程，才能出现地图编辑器的跳转页面''' ====

[[File:新跳转后台.png]]

=== 后台创建游戏，绑定地图 ===
* 需要泡饭跳转到后台，去新建游戏，生成独属于你的gameid和secret，这在后续的开发和上传时至关重要，请点击下方超链接，去参考其中新建gameid的部分
* [[上传流程|请看该链接中，新建游戏玩法的部分]]

=== 修改package.json进入自己的游戏和地图 ===
- 点击左侧修改配置按钮
[[File:新点击修改配置.png]]
- gameid 开发者后台中指定的游戏玩法
- secretkey 游戏玩法对应的密钥
- defaultMap 游戏玩法中，指定的地图，请在后台至少指定一张，默认填写"地图_0"
- sdkVersion sdk版本号，点击修改可以弹出下拉框，一般选用release标签的稳定版本，修改后，会去修改对应的bridge依赖，并且下载
- resVersion 美术资源版本号，会影响游戏内地图和模型的显示，一般选用最新的版本即可

=== 首次运行需要先发布 ===

当前的gameid是最新的，

目前后台服务器还没有一个初始版本的记录，所以需要在package.json中，修改完gameid之后。

首次运行要发布游戏（后续不需要每次发布，直接保存就可以编译调试）。

[[File:泡饭点击发布游戏.png]]

等待右上脚提示发布完成，即可启动进入游戏

=== 启动项目 ===

一般选用启动游戏（服务器模式）

[[File:新泡饭点击启动游戏.png]]

==== 登录界面 ====
- 运行后，浏览器将显示登陆界面。
[[File:默认地图.png]]
- 账号密码随便输入，会创建新账号
- 输入账号密码后，选择指定地图（可选），即可看到战斗服务器世界中有自己的人物。
- 默认的demo工程中，如果没有修改gameid和secretKey，地图请填写"地图_0"

== 泡饭模板的多人合作 ==

=== 发布模板 ===

[[File:发布工程多人合作.png]]

设置团队成员权限和名称

[[File:设置团队成员权限.png]]

=== 发布后管理项目 ===

发布后可以在商店模板里去修改自己发布的项目。

[[File:发布后编辑模板权限.png]]

=== 其他成员就可以在模板商店拉取模板了 ===

比如上图中的playername1的账号，就可以拉取模板了

=== 打开项目 ===

点击编辑按钮，切换到vscode运行环境。

[[File:点击编辑按钮切换vscode.png]]

=== 团队成员修改提交 ===

我们尝试写第一行代码提交下

[[File:写第一行代码.png]]

[[File:模板内git_commit.png]]

具体在vscode中，怎么使用git来提交和拉取，可以参考如下文档

[vscode使用git插件](https://blog.csdn.net/khhmd/article/details/144131405)

=== 多人合作冲突的解决(遇到冲突再看，可以先跳过) ===
==== 选择远端的master分支来merge ====

[[File:git冲突merge.png]]

[[File:gitmerge选择远端.png]]

==== 根据需求去修改冲突文件 ====

[[File:git冲突文件解决.png]]

==== 冲突文件修改完成，resolve ====
[[File:git冲突保存.png]]
[[File:解决冲突完成.png]]

==== 同步到远端 ====

[[File:gitmerge同步到远端.png]]

== 前端基础逻辑 ==

根据以下步骤，一步步进入泡泡的游戏世界，即使你是新手也无需担心。

=== 前端游戏入口 ===
- '''/src/client/index.ts''' 文件中的 `XPopManager.onGameStart` 是前端的主要入口点。

=== 创建第一个人物 ===
在 `simpleGame` 类中，我们将创建并初始化第一个游戏人物。

<pre>
export class simpleGame {
private firstModel: XModelHero;

constructor() {
// 创建第一个人物
this.firstModel = new XModelHero();
let path = 'role/model_avatar_body_default';

// 加载人物模型并播放动画
this.firstModel.loadModel(path, null, this, (success) => {
// 播放跑步动画
let actName = "act_avatar_base_run";
this.firstModel.playAniUp(`${actName}_up`);
this.firstModel.playAniDown(`${actName}_down`);

// 摄像机跟随
let camera = XPopManager.instance.xScene.camera;
camera.focus = this.firstModel;

// 定时更新人物位置
XTimer.loop(100, this, this.updateModelPos.bind(this));
});
}

updateModelPos(delta: number, frame?: string) {
// 更新人物位置
this.firstModel.position.x += 0.1;
}
}

// 设置游戏启动时执行
XPopManager.onGameStart = () => {
new simpleGame();
}
</pre>

*注意：请将原代码中的 '''new Main()''' 替换为 '''new simpleGame()''';
上述的代码我们以最简单的方式，去掉一切服务器交互，添加一个基础模型到游戏中跑动

再提醒一次，每次有代码修改后，运行前需调用命令进行编译
[[#编译]]

=== 播放人物的动作 ===
我们的人物有上下半身，在知道动画名字的情况下，需要分上下半身来播放动画

以'act_avatar_plant_collect'为例

<pre>
let animbaseStr = 'act_avatar_plant_collect';
role.model.playAniUp(`${animbaseStr}_up`);
role.model.playAniDown(`${animbaseStr}_down`);
</pre>

那么如何快速查看已有哪些动画呢？

[动作查看器](https://webdev.popx.com/v1/game/client_host.html?author=qc_jump&project=resourceviewer_0926&diyserver=1&gameid=0bkyyeesxnzsrd9s&editorFormal=true)

=== 添加按键控制 ===
看demo中的代码，提供了一个MoveComponent类
摇杆的显示资源放在'''res-extra'''目录中

[[File:摇杆资源.png]]

以下是示例中添加摇杆控制的代码
<pre>
//摇杆背景
let rocker = new XImage('res-extra/imgs/stick_bg.png');
rocker.width = rocker.height = 164;
rocker.pivotX = rocker.pivotY = 82;
rocker.pos(178, -198);
leftbottom.addChild(rocker);
//摇杆方向
let imgdir = new XImage('res-extra/imgs/stick_dir.png');
imgdir.centerX = imgdir.centerY = 0;
imgdir.anchorX = imgdir.anchorY = 0.5;
imgdir.name = "dir";
rocker.addChild(imgdir);
//摇杆中心点
let node = new XImage('res-extra/imgs/stick_rocker.png');
node.centerX = node.centerY = 0;
node.anchorX = node.anchorY = 0.5;
node.name = "node";
rocker.addChild(node);
//移动
let hero = this.heros.get(this.roleIndex);
if (hero) {
let movecomponent = rocker.addComponent(MoveComponent) as MoveComponent;
movecomponent.init(hero, ctrlayer, rocker);
}
</pre>

示例中，添加了一个触摸区域挂载在根节点的左下角，触摸反馈会根据'''XEvent'''来传递给节点
代码中根据摇杆方向变化来控制人物移动
其中涉及了部分修改玩家状态的服务器代码，可以先忽略

=== 摄像机的跟随 ===
代码中，摄像机跟随人物移动，只需要简单的一行
<pre>
let hero = new Xmodel();
//这是全局的摄像机
XPopManager.instance.xScene.camera.focus = hero;
</pre>

摄像机的旋转视角，demo中也提供了一个类'''CameraComponent'''
和摇杆的节点类似，通过'''XEvent'''来传递点击事件，
根据点击事件的拖动，来修改摄像机的旋转视角 '''xcamera.rotate'''
<pre>
private onCtrlMouseMove(e: XEvent): void {
if(this._touchId != e.touchId) return;
let xcamera = XPopManager.instance.xScene.camera as XCamera;
if(!xcamera)return;
if(this._mouseX == 0) this._mouseX = e.stageX;
if(this._mouseY == 0) this._mouseY = e.stageY;
let offx = e.stageX-this._mouseX;
let offy = e.stageY-this._mouseY;
this._mouseX = e.stageX;
this._mouseY = e.stageY;
xcamera.rotate(offx, offy);
}
</pre>
=== 砖块说明 ===
[[File:砖块说明.png]]

如图所示，我们的世界地图由若干个方形大'''地块'''组成，

每个地块里，可以划分成32*32的平面坐标，一层层叠高，可以有64层高，

转化为三维坐标系就是32*64*32，对应xyz轴，

地块上，可以添加以坐标为单位的'''砖块'''。

其中，cubeId表示砖块的类型，比如草地就是id为1的砖块，该砖块具有可以踩踏行走的特性。

某些其他的砖块具有别的特性，都通过cubeid来区分，当开发者接触地图编辑器时，就会有所了解。

我们以Demo中，'''MoveComponent'''中的一段代码来参考
<pre>
// 游戏世界地图
let scene = XPopManager.instance.xScene;
// 判断水平方向是否有砖块
// 根据坐标位置，找到世界中，其坐标对应的砖块id
let cubeid = scene.getCube(dir.x ,position.y, dir.z)
if(cubeid){
// 根据砖块id，找到砖块的类型，判断其是否和人物碰撞阻挡
scene.getCubeInfo(cubeid, this.cubeInfo);
if(this.cubeInfo.collisionPlayer){
dir.x = position.x;
dir.z = position.z;
}
}
//如果没有砖块或者有无阻挡砖块，给一个向下的位移
cubeid = scene.getCube(dir.x ,position.y-0.1, dir.z)
if(cubeid){
scene.getCubeInfo(cubeid, this.cubeInfo);
if(!this.cubeInfo.collisionPlayer){
dir.y = position.y-0.1;
}
}else{
dir.y = position.y-0.1;
}
</pre>

*再以图中为例，v3的坐标代表了地图上的位置，(24,3,26)
*如果需要设置模型在地图上的位置，用如下代码
<pre>
let pos = new XVector3(x,y,z);
xModel.position = pos;
</pre>

== 资源加载说明 ==

=== 演示加载图片 ===
<pre>
// 测试加载图片
// 创建一个全屏的挂载UI层
let mainui = new XImage();
mainui.left = mainui.right = mainui.top = mainui.bottom = 0;
XPopManager.rootNode.addChild(mainui);

// 图片路径，如果是本地的额外资源，就加上"res-extra/"前缀，否则就是远端资源
let path = 'avatarstart/ball_btn2.png';
// 创建图片
let img = new XImage(path);
// 添加到父节点显示
mainui.addChild(img);
// 设置位置
img.left = img.top = 100;
</pre>

编译，运行后，可以看到，添加了指定的图片

[[File:资源加载一.png]]

=== 公共资源 ===
PGT为开发者提供了很多基础的图片，模型，音频等等的资源。

====怎么查看有哪些公共资源呢？====

*打开项目目录下的package.json文件

[[File:资源加载二.png]]

===== 有sdkVersion =====
*调用查看当前的远端sdk版本，即资源版本，比如"sdkVersion": "1.0.15",
*具体有哪些资源版本可用，可以调用'''npm run sdklist '''来查看
*把下面链接里的v1.0.16替换成和你目前版本一致的数字，就可以查看远端资源列表

[[File:sdkVersion.png]]

[远端文件列表json](https://h5ppreview.jumpw.com/popion/sdk/v1.0.16/version.json)

===== sdkVersion>1.2.60的版本 =====

同样是查看pacakge.json，但是字段换成了"resVersion": "1.0.5"

resVersion

如下是1.0.5版本的资源列表，可以修改数字查找不同版本

[远端文件列表json](https://h5ppreview.jumpw.com/popion/popx-res/version-1.0.5.json)

也可以用命令来查找显示不同的资源版本

'''查看资源版本列表'''：npm run reslist (只包含正式发布的版本)

'''查看所有资源版本列表'''：npm run reslistall

===== 查看json文件 =====

*json文件左侧是游戏内加载的路径，右侧是实际的打过md5值的网络路径

[[File:资源加载四.png]]

这就是我们刚刚演示的加载图片

''avatarstart/ball_btn2.png": "avatarstart/ball_btn2-2c717f83a3.png''

*游戏内我们通过加载接口去加载左侧路径
*游戏外，直接在刚刚的cdnUrl后拼接带md5值的完整路径即可查看

[查看网络资源](https://h5ppreview.jumpw.com/popion/sdk/v1.0.17/avatarstart/ball_btn2-2c717f83a3.png)

[[File:资源加载五.png]]

*音频文件同理，模型文件直接游戏内调用接口显示

=== 额外资源 ===
最基础的demo中，会看到用于演示的摇杆资源是放在'''res-extra'''目录下的。

一般来说，开发者的一些特制UI，图形，可以放在这里。

加载时在路径前加上"res-extra/"即可。

*注意，额外资源调用前，要调用如下固定代码开启合图资源的配置，建议参考demo，在游戏入口就初始化调用一次
<pre>
XResManager.instance.enableAtlas("res-extra/fileconfig.json",()=>{
// 可以调用额外资源了
});
</pre>

每次在调用命令，npm run ui时，会更新上述的'''fileconfig.json'''文件。

[[#npm run ui ( 生成ui类 )]]

==== npm run ui ( 生成ui类 ) ====
如果开发者有额外的ui交互需求，希望在IDE中自己拼接UI
可以在指定目录下，
* '''ui_laya/laya/''' - 开发者可以自由扩展的ui资源目录
* '''ui_laya/laya/pages''' - 开发者创建的.scene文件目录
* '''ui_laya/laya/assets/uiextra''' - secne文件中引用到的各种美术资源，包括音频和动画

-运行后，会在client目录代码中，生成对应的XUIComponent类，[[#XUIComponent]]

-运行后，会更新'''res-extra'''文件夹下的fileconfig.json

*注意，我们目前不支持第三方模型文件，模型必须提交审核，不放在res-extra中

=== 模型查看器 ===
*除了图片资源外，为了方便开发者使用，我们额外做了一个模型查看器

[公共模型查看器](https://webdev.popx.com/client_host.html?author=qc_jump&project=resourceviewer_0926&diyserver=1&gameid=09kyye6gcmmda79s&editorFormal=true)

== UI界面开发 ==

=== git拉取ui工程到本地 ===

==== 泡饭的项目发布后获取到了git地址 ====
[[File:发布模板后获得git地址.png]]

==== 查看git密钥 ====

[[File:查看git密钥.png]]

==== 使用accesstoken来拉取项目到本地 ====

===== 常见的git工具中=====

git clone 地址

输入泡饭账号和accesstoken即可拉取，注意不是泡饭的密码，是token

===== 没有工具时用命令拉取说明=====

[[File:如何使用accesstoken拉取.png]]

=== 安装本地ui的编辑环境 ===

==== laya 版本 v2.13.1 ====
- [laya官方ide](https://ldc2.layabox.com/layadownload/?type=layaairide-LayaAir%20IDE%202.13.1)

==== 安装项目自定义封装的cmd命令库 ====
- 推荐安装方式：
<pre>
npm i popxcmd -g --registry https://registry.popx.com
</pre>

==== node 版本 v10.24.1 ====
- 必须使用指定的nodejs版本 ，推荐安装nvm以自由转换node版本。
- [nvm下载及安装方式](https://blog.csdn.net/ppz8823/article/details/130862191)

*记得nvm需要换源，否则后续安装可能会出错，按照下述操作

[[File:nvm换源.png]]

*最下面两行修改node和npm的镜像地址
<pre>
node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/
</pre>

*安装nvm后，命令行运行如下命令切换到node版本v10.24.1，一步步来:
<pre>
// 安装
nvm install 10.24.1
// 等待安装完成后，切换
nvm use 10.24.1
</pre>

*nodejs也需要用下面的命令来换源，修改镜像地址
<pre>
npm config set registry https://registry.popx.com/
</pre>

==== 修改host文件 ====
- 找到host文件，一般在`C:\WINDOWS\system32\drivers\etc`目录下。
- 在文件末尾添加：
<pre>
199.232.68.133 raw.githubusercontent.com
</pre>

=== 在编辑器中创建UI ===
==== 打开Laya工程 ====
使用指定版本的Laya编辑器打开 `demo/ui_laya/ui_laya.laya` 项目。

==== 添加.scene界面 ====
在编辑器中，可以添加一个新的scene界面，并在其上放置UI元素。

[[File:新界面.png]]

==== 界面添加UI组件 ====
例如，添加一个名为 `btnFirst` 的按钮，并确保其 `var` 属性有值，以便后续导出。

[[File:UI按钮有值.png]]

添加后，记得保存，'''ctrl+S'''

=== 额外资源的添加 ===

注意，所有上述scene中用到的美术资源，必须放在Assets/uiextra/ 目录下

否则导出ui时会失败

=== 运行生成UI命令 ===
在命令行中运行以下命令来生成UI代码：

<pre>
npm run ui
</pre>

运行成功后，生成的UI类将位于 `src/ui/popxMaxUI.ts` 文件中。

[[File:UI生成代码.png]]

其中，添加了一个和scene名相同的UI类，
并且，var有值的组件也一起生成了对应属性。

=== 修改后的资源，git上传到远端 ===

上传后，泡饭即可使用

先git commit提交
注意推送时要用如下命令

git push --force

如果弹出输入框，账号输入泡饭账号名，密码输入accesstoken

[[File:新泡饭推送到远端.png]]

=== 代码控制XUIComponent ===
==== 注册UI类的控制文件 ====
使用 `PopxBridge.regUIClass()` 方法在相应的类中注册UI类，并处理UI相关的按键逻辑。
<pre>
//注册自定义的ui类
PopxBridge.regUIClass(DemoUI.getClassName(), DemoUI);
</pre>

以下是我们新加UI的最基础代码，在界面显示的时候，注册点击事件，点击后打印日志
<pre>
export class DemoUI extends uiextra.demoUIUI{

constructor(){
super();
}

onAwake(): void {

}

onEnable(): void {
// 设置在顶层可以被点击
this.zOrder = 1;
this.first_btn.on(XEvent.CLICK, this, this.onClickFirstBtn);
}

private onClickFirstBtn(e:XEvent){
console.log("click first btn");
}
}
</pre>

==== 代码调用显示UI ====
通过 `xUiManager.instance.openUI()` 方法来调用并显示UI界面。
<pre>
// 加载对应的json文件路径，并挂载在指定父节点上
XUiManager.instance.openUI('res-extra/ui/demoUI', XPopManager.rootNode);
</pre>

-编译，运行

[[File:UI点击按钮.png]]

==== 代码调用加载组件 ====
*某些界面上的元素，比如卡牌，也可以类似做成一个scene，运行npm run ui 自动生成类
*比如类名为CardView
*注册和UI注册类似
<pre>
PopxBridge.regUIClass(CardView.getClassName(), CardView);
</pre>
*创建时，调用`XUiManager.instance.createView`
<pre>
XUiManager.instance.createView(path,parent,this.onLoadCardView,showData);

onLoadCardView(view:XUIComponent)
{
}
</pre>

== 前后端数据交互 ==

该篇会讲述服务器和前端的数据同步，如果想要先了解项目目录和工作流，建议先参考如下篇幅
[[#主要工程目录]]

=== 进入房间（游戏世界） ===
如下是最基本的开发登录流程说明
{| class="wikitable"
|-
! 步骤
! 描述
! 流向
|-
| 开始
| 流程的开始
| -> 登录页面
|-
| 登录页面
| 账号密码，选定地图，输入房间号（可不填）
| -> 远端服务器（官方）
|-
| 远端服务器（官方）
| 获取玩家账户信息，分配到房间,房间就是我们的host代码
| -> Client 和 -> Host
|-
| Client
| 监听XPopManager.onGameStart
| -> 前端逻辑开始
|-
| Host
| 监听XPopManager.onHostStart
| -> 房间战斗逻辑开始

|}

远端服务器(官方)会处理最基本的登录，分配房间，创建游戏世界的逻辑，并且同步该世界中的游戏数据。

通过'''XpopManager'''管理类，来向Client和Host抛出事件，开发者可以监听这些事件做处理。

开发者需要关心的逻辑，就是Clint和Server（上图中Host）目录下的代码。

=== 前后端协议交互 ===
项目采用proto来做相互通信

=== 前后端共用配置 ===
前端'''src/client'''目录和后端'''src/server'''目录中，都可以调用如下代码来加载所有的表格配置
<pre>
CsvManager.ins.loadCsvs(this, () => {
// Do some thing after load
});
</pre>

表格的加载逻辑和解析逻辑，可以参考CsvManager中的代码
'''src/shared/csv/CsvManager.ts'''

''如何新增配置?''
以demo中的'''item.csv'''为例.
*1.配置csv文件资源的根目录为'''res-extra/csv/''' ,在里面添加'''item.csv'''
*2.'''CsvManager.ts'''文件中，添加读取表格和解析表格的逻辑
<pre>
// loadCsvs代码中，添加你需要解析的csv名称
public loadCsvs(caller: any = null, listener: Function = null) {
let assets = [
this._prefix + "item.csv",
];
// XResManager加载本地资源
XResManager.instance.loadText(assets, () => {
// 在加载完成的回调中，处理表格数据结构，生成CItemData，不再赘述
this.onCompleted(caller, listener);
});
}
</pre>
*3.解析表格得到的'''CItemData'''结构，定义在'''src/shared/dataMgr/'''中，可以被前后端一起调用
*4.如果是加载json文件，用'''XResManager.instance.loadText'''

=== 玩家战斗数据快照 ===
游戏战斗服务器中，每个玩家的实时信息，通过快照来更新
==== XVF_SnapData ====
以demo中的'''Snap_UserData.ts'''为例
*该玩家数据中类中，包含的各种public变量，都是''XVF_SnapData''接口类型
<pre>
export class Snap_UserData {
//坐标旋转
public position: XVF_SnapData<SyncPos>;
//状态
public state: XVF_SnapData<SyncState>;
//hp
public hp: XVF_SnapData<number>;
}
</pre>
快照类型数据，前端负责注册和监听，服务器负责修改
*每次该接口类型的数据发生变化时，会调用OnSet方法，这类数据的修改逻辑是：服务器修改，前端监听变化
** 前端登录成功后，服务器注册对应玩家数据
** 前端对数据中的某个XVF_SnapData做监听，注册OnSet方法
** 服务器战斗逻辑修改了该数据时，前端根据OnSet的逻辑做表现处理

服务器先注册全局的快照
<pre>
let userData = new Snap_UserData();
XPopManager.instance.xHost.RegisterSnapshot(`UserData${i}`, userData);
</pre>

前端绑定同一个地址的快照
<pre>
this._userData = new Snap_UserData();
XPopManager.instance.xRemote.RegisterSnapshot(`UserData${index}`, this._userData);
</pre>

*XVF_SnapData数据，如果是复杂类型，需要调用UpdateData()方法，前端才能触发OnSet
如下的SyncState就是复杂类型
<pre>
public state: XVF_SnapData<SyncState>;
public setState(key:string, obj:string):void{
this.state.value.key = key;
this.state.value.obj = obj;
this.state.UpdateData();
}
</pre>
*XVF_SnapData如果是基础类型，不需要调用UpdateData()
<pre>
public hp: XVF_SnapData<number>;
public setHP(hp:number):void {
this.hp.value = hp;
}
</pre>

=== 代码如何调试 ===
==== 前端调试 ====
直接在网页上调试

f12打开控制台，

点击源代码，

可以根据代码目录结构找到想要断点的文件，

也可以快捷键"ctrl + p"输入文件名查找（mac上是cmd + p）,

找到后，点击具体左侧代码行数标签即可。

可以很方便的观察堆栈和变量信息

[[File:网页断点调试.png]]

==== 服务器调试 ====
*启动运行时，会弹出一个host弹窗服务器在调用命令'''npm run server'''后，会启动一个Host网页

[[File:服务器host.png]]

*只要是网页，那就能调试js代码
*打开网页的开发者工具（一般浏览器是f12）,找到'''index.js'''文件

*该文件是由服务器代码入口index.ts编译生成的js文件，注意，不止是index.ts，里面相关的引用代码都会编进去

*虽然代码经过编译，但是没有混淆，可以通过函数名，找到js代码中的行号，打断点

[[File:服务器断点.png]]

==== 调试注意事项 ====
*每次'''npm run build'''后，如果修改了服务器代码，可以在本地host的浏览器里，立刻刷新，F5或者shift+f5
*如果修改了编译脚本来调试服务器，记得最后打包上传前，把rollup的代码改回来

== 地图的制作和选取 ==
=== 地图制作导出 ===

[[File:地图编辑视频.png]]

教学视频已经上传到网页链接

[新建地图](https://formalhead.popx.com/popxVedio/mapeditor/新建地图.mp4)

[地块操作](https://formalhead.popx.com/popxVedio/mapeditor/地块操作.mp4)

[地块（水）](https://formalhead.popx.com/popxVedio/mapeditor/地块（水）.mp4)

[地形设置（增加）](https://formalhead.popx.com/popxVedio/mapeditor/地形设置（增加）.mp4)

[新地编添加预制件和编辑](https://formalhead.popx.com/popxVedio/mapeditor/新地编添加预制件和编辑.mp4)

[预制件操作](https://formalhead.popx.com/popxVedio/mapeditor/预制件操作.mp4)

[授权给他人使用](https://formalhead.popx.com/popxVedio/mapeditor/授权.mp4)

[如何游戏内绑定后台玩法和地图](https://formalhead.popx.com/popxVedio/mapeditor/如何游戏内绑定后台玩法和地图.mp4)

=== 开发环境选择地图 ===
我们在登录界面，可以通过填写你gameid中的地图名字，来进入指定地图。

所以必须要先创建gameid，并且选择至少一张地图，该地图才能在调试时进入。

举例：

*上传地图到某个游戏gameid时，会从你自己的'''可用地图'''中选择。

- 可用地图指的是你自己制作上传了地图。或者其他人共享给了你地图。

*比如你的可用地图名字是"推箱子"。

*右边会有可填写的自定义地图名字，比如"第一关"

那么登录的时候就是填写 "第一关"

*'''也就是说，地图做完后，必须要在审核平台上，添加到玩法里，生成自定义的名字，才可以在测试时填写进去生效 '''

== 打包与上传 ==

[[File:泡饭点击发布游戏.png]]

点击发布后，会把构建生成的压缩包上传到远端，就可以去试玩了。

=== 玩法测试 ===

[[File:泡饭点击打开审核后台.png]]

* [[上传流程|查看文档中试玩/审核/发布的部分]]

== 项目目录 ==

=== 主要工程目录 ===
对于开发者，需要关心和操作的目录如下：

* '''node_modules/''' - 通过npm安装的PGC库文件，对外暴露的方法，可以通过bridge.d.ts来外部引用
* '''res-extra/''' - 开发者除了PGC的远程资源外，需要额外使用到的资源目录，比如UI，图片，音频，表格，最后会打包上传到PGC远端资源服务器
* '''ui/''' - 开发者自己在laya编辑器中，拼接的界面json文件，运行命令后，会转化为PGT指定的XUIComponent存放于此
* '''src/''' - 开发者所有的战斗逻辑代码修改都在此进行
* '''src/client/''' - 前端代码，入口文件index.ts，监听XPopManager.onGameStart，前端游戏逻辑
* '''src/server/''' - 后端代码，入口文件index.ts，监听XPopManager.onHostStart，后端游戏逻辑
* '''src/shared/''' - 前后端共用的数据结构，包括表格，协议，玩家数据
* '''dist/''' - 编译后，生成的运行文件，包含前后端代码
* '''dist/client/''' - 编译后生成的混淆的前端代码
* '''dist/host/''' - 编译后服务端的代码文件，里面也包括表格数据的缓存

=== 前后端协议通信生成 ===

[[File:泡饭点击生成协议.png]]

==== 协议通信 ====
该命令会用到tsrpc的proto协议，
把'''src/shared/protocols'''下的指定格式文件，
转换到'''src/shared/protocols/generated/serviceProto'''文件中，

* 文件名为：Ptl{接口名}.ts '''（Ptl 是 Protocol 的缩写，l是小写的L）'''
* 请求类型名为： Req{接口名}，通过 interface 或 type 定义，需 export
* 响应类型名为：Res{接口名}，通过 interface 或 type 定义，需 export

例如，添加'''PtlPosition.ts'''文件
文件代码如下
<pre>
// 该接口用于向服务器同步自身的坐标
export interface ReqPosition {
i: number;
x: number;
y: number;
z: number;
ry: number;
}
export interface ResPosition {
ret: string;
diy: string;
}
</pre>

'''serviceProto.ts'''中会增加可外部调用的api类型
<pre>
export interface ServiceType {
api: {
"Position": {
req: ReqPosition,
res: ResPosition
},
},
msg: {

}
}
</pre>

'''前端代码调用请求'''
<pre>
// 前端可以用promise语法来调用同步位置的Request，异步处理服务器的返回值
let remote = XPopManager.instance.xRemote;
let ret = await remote.Request('Position', {i: 1, x:2, y:3, z:4, ry:5});
if(ret && ret.isSucc){
console.log(ret.res.diy)
}
</pre>

'''后端代码监听请求处理返回'''
<pre>
// 服务器收到前端请求的处理返回RegisterRpc
let host = XPopManager.instance.xHost;
//当收到坐标变化请求
host.RegisterRpc("Position", async (call: ApiCall<ReqPosition, ResPosition>) => {
let index = call.req.i;
let userData = this.usersData.get(index);
userData.setPosition(call.req.x, call.req.y, call.req.z, call.req.ry);
return call.succ({
ret: "Success",
diy: "自定义参数"
});
});
</pre>
如果想更多了解proto的结构和数据类型说明，可以参考官方链接
[tsrpc-proto格式说明](https://tsrpc.cn/docs/server/service-proto.html)

== 核心类目说明 ==
=== XPopManager ===
Bridge.d.ts中的核心类

对游戏逻辑进行了结构化的拆封和管理，

可以理解为，

库文件内处理了各种玩家的逻辑，比如登录，加载地图，分配房间，快照数据同步等等,然后关键的几个节点，暴露给外部去执行游戏逻辑。

开发者只需要去编写独立游戏模块的代码，其中，'''Xremote'''暴露给前端处理，'''Xhost'''暴露给后端处理

下面是最重要的几个生命周期函数
;onGameStart:玩家已经完成了登录步骤，已经分配好了房间，通知前端游戏开始
;onHostStart:玩家已经完成了登录步骤，已经分配好了房间，通知后端游戏开始
;onGameOver:游戏结束（一般是玩家都离开了战斗房间）
;onUpdate:每一帧会调用更新

我们在demo中，index.ts里，可以给这几个方法监听绑定函数，输出日志就可以查看

<pre>
XPopManager.onGameStart = ()=>{
new Main();
console.log("qc,XPopManager.onGameStart");
}

XPopManager.onGameOver = () => {
console.log("qc,XPopManager.onGameOver");
}

XPopManager.onHostStart = () => {
console.log("qc,XPopManager.onHostStart");
}

XPopManager.onUpdate = () => {
console.log("XPopManager.onUpdate");
}
</pre>

[[File:XPopManager生命周期.png]]

=== XRemote(前端) ===
*以下是最关键的生命周期和方法调用，调用逻辑可以自定义设计，后端代码同理
;UserID:玩家进入游戏的唯一id
;onUserEnter:每当房间内玩家进入时会调用，前端可以在此根据返回的userId来同步XHost玩家的快照数据，创建角色等等
;onUserLeave:每当房间内玩家离开时会调用，前端根据userId来处理模型的销毁
;RegisterSnapshot:用于注册绑定快照，快照类型开发者自定义，需要和XHost代码中绑定的地址一致，才可以收到OnSet回调
;Request:发送RPC请求，请求和回调的代码由protocol生成

=== XHost(后端) ===
;onUserEnter:每当房间内玩家进入时会调用，初始化玩家身上的快照数据，可以根据人数来判断游戏阶段，比如准备阶段
;onUserLeave:每当房间内玩家离开时会调用，清理玩家数据，可以根据玩家人数来判断是否进入结算或者游戏结束
;RegisterSnapshot:用于注册绑定快照，快照类型开发者自定义，需要和XRemote代码中绑定的地址一致
;RegisterRpc:注册RPC回调

=== XUIComponent(UI组件) ===
UI组件通过XUiManager.instance.OpenUI或者XUiManager.instance.CreateView加载显示
;showUI:调用后会设置active为true，当调用创建的方法，加载成功显示时也会调用一次，可以在创建时传参，每次主动调用也可以传参。
;hideUI:把该组件的active设置成false
;closeUI:把该组件从父节点移除，可以传参处理移除成功时的回调
=== XEventDispatcher(事件)===
我们可以根据已有的XEventDispatcher来封装一个单例，这样就能外部夸文件调用事件了。
如下为演示封装的单例
<pre>
export class EventManager extends XEventDispatcher{

constructor () {
super();
}

private static _instance: EventManager
public static get instance(): EventManager {
if (!this._instance) { this._instance = new EventManager(); }
return this._instance;
}

}
</pre>

事件的派发
<pre>
EventManager.instance.dispatch("new_event_name", ...args);
</pre>

事件的监听
<pre>
EventManager.instance.add("new_event_name", this, this.ParseNewEvent);

private ParseNewEvent(...args)
{
console.log("parse new event")
}
</pre>

== 常见工作流问题 ==
=== 如何把本地的项目上传到泡饭 ===
==== 建议先上传项目到自己的git仓库 ====
==== 从git拉取 ====

点击图中创建模板按钮，从git创建工程

[[File:点击从git创建工程.png]]

[[File:git项目地址.png]]

== 官方论坛 ==
*[论坛地址](https://bbs.popx.com/)
*可以由我们内部人员给出的邀请链接申请加入论坛。
*申请后，等待审核人员核实，批准后，即可浏览论坛内容，发表疑问贴。
*强烈建议多去论坛搜索关键字，发帖会有对应的专业人员回答问题，大家一起维护论坛生态。
*常见问题faq帖子会持续维护

[论坛FAQ](https://bbs.popx.com/t/topic/53)

泡饭工坊项目流程

2025-02-19T05:42:06Z

Liuweichen：/* 代码如何调试 */

== 泡饭工坊介绍 ==
===泡饭工坊是什么？===
泡饭是一套网页虚拟环境下的代码编辑工具，内嵌了多种预设和模板，集成了vscode来编辑代码，自动编译，可以方便的预览和分享给小伙伴体验。
=== 泡饭链接 ===
[链接](https://webdev.popx.com)

=== 泡饭账号注册登录 ===

==== 没账号的需要在泡饭注册账号 ====

[[File:新注册账号手机号.png]]

'''请记住您的账号密码，这关系到后续我们管理您的使用权限'''

==== 和我们内部人员沟通，申请后台权限 ====

'''如需开通后台使用权限，将您的账号告知我们内部人员帮操作，等待通知完成后，重新刷新网页即可'''

==== 第一次需要创建一个工程 ====

[[File:新点击模板商店创建模板.png]]

[[File:新模板下载.png]]

[[File:新下载工程.png]]

==== 有了工程后，打开工程 ====

[[File:新打开我的工程.png]]

== 打开泡饭体验项目 ==

参考视频[1.泡饭运行环境演示.mp4]

== 如何用泡饭开发自己的项目 ==

=== 点击跳转后台 ===

===='''就第一次需要创建打开一个工程，才能出现地图编辑器的跳转页面''' ====

[[File:新跳转后台.png]]

=== 后台创建游戏，绑定地图 ===
* 需要泡饭跳转到后台，去新建游戏，生成独属于你的gameid和secret，这在后续的开发和上传时至关重要，请点击下方超链接，去参考其中新建gameid的部分
* [[上传流程|请看该链接中，新建游戏玩法的部分]]

=== 修改package.json进入自己的游戏和地图 ===
- 点击左侧修改配置按钮
[[File:新点击修改配置.png]]
- gameid 开发者后台中指定的游戏玩法
- secretkey 游戏玩法对应的密钥
- defaultMap 游戏玩法中，指定的地图，请在后台至少指定一张，默认填写"地图_0"
- sdkVersion sdk版本号，点击修改可以弹出下拉框，一般选用release标签的稳定版本，修改后，会去修改对应的bridge依赖，并且下载
- resVersion 美术资源版本号，会影响游戏内地图和模型的显示，一般选用最新的版本即可

=== 首次运行需要先发布 ===

当前的gameid是最新的，

目前后台服务器还没有一个初始版本的记录，所以需要在package.json中，修改完gameid之后。

首次运行要发布游戏（后续不需要每次发布，直接保存就可以编译调试）。

[[File:泡饭点击发布游戏.png]]

等待右上脚提示发布完成，即可启动进入游戏

=== 启动项目 ===

一般选用启动游戏（服务器模式）

[[File:新泡饭点击启动游戏.png]]

==== 登录界面 ====
- 运行后，浏览器将显示登陆界面。
[[File:默认地图.png]]
- 账号密码随便输入，会创建新账号
- 输入账号密码后，选择指定地图（可选），即可看到战斗服务器世界中有自己的人物。
- 默认的demo工程中，如果没有修改gameid和secretKey，地图请填写"地图_0"

== 泡饭模板的多人合作 ==

=== 发布模板 ===

[[File:发布工程多人合作.png]]

设置团队成员权限和名称

[[File:设置团队成员权限.png]]

=== 发布后管理项目 ===

发布后可以在商店模板里去修改自己发布的项目。

[[File:发布后编辑模板权限.png]]

=== 其他成员就可以在模板商店拉取模板了 ===

比如上图中的playername1的账号，就可以拉取模板了

=== 打开项目 ===

点击编辑按钮，切换到vscode运行环境。

[[File:点击编辑按钮切换vscode.png]]

=== 团队成员修改提交 ===

我们尝试写第一行代码提交下

[[File:写第一行代码.png]]

[[File:模板内git_commit.png]]

具体在vscode中，怎么使用git来提交和拉取，可以参考如下文档

[vscode使用git插件](https://blog.csdn.net/khhmd/article/details/144131405)

=== 多人合作冲突的解决(遇到冲突再看，可以先跳过) ===
==== 选择远端的master分支来merge ====

[[File:git冲突merge.png]]

[[File:gitmerge选择远端.png]]

==== 根据需求去修改冲突文件 ====

[[File:git冲突文件解决.png]]

==== 冲突文件修改完成，resolve ====
[[File:git冲突保存.png]]
[[File:解决冲突完成.png]]

==== 同步到远端 ====

[[File:gitmerge同步到远端.png]]

== 前端基础逻辑 ==

根据以下步骤，一步步进入泡泡的游戏世界，即使你是新手也无需担心。

=== 前端游戏入口 ===
- '''/src/client/index.ts''' 文件中的 `XPopManager.onGameStart` 是前端的主要入口点。

=== 创建第一个人物 ===
在 `simpleGame` 类中，我们将创建并初始化第一个游戏人物。

<pre>
export class simpleGame {
private firstModel: XModelHero;

constructor() {
// 创建第一个人物
this.firstModel = new XModelHero();
let path = 'role/model_avatar_body_default';

// 加载人物模型并播放动画
this.firstModel.loadModel(path, null, this, (success) => {
// 播放跑步动画
let actName = "act_avatar_base_run";
this.firstModel.playAniUp(`${actName}_up`);
this.firstModel.playAniDown(`${actName}_down`);

// 摄像机跟随
let camera = XPopManager.instance.xScene.camera;
camera.focus = this.firstModel;

// 定时更新人物位置
XTimer.loop(100, this, this.updateModelPos.bind(this));
});
}

updateModelPos(delta: number, frame?: string) {
// 更新人物位置
this.firstModel.position.x += 0.1;
}
}

// 设置游戏启动时执行
XPopManager.onGameStart = () => {
new simpleGame();
}
</pre>

*注意：请将原代码中的 '''new Main()''' 替换为 '''new simpleGame()''';
上述的代码我们以最简单的方式，去掉一切服务器交互，添加一个基础模型到游戏中跑动

再提醒一次，每次有代码修改后，运行前需调用命令进行编译
[[#编译]]

=== 播放人物的动作 ===
我们的人物有上下半身，在知道动画名字的情况下，需要分上下半身来播放动画

以'act_avatar_plant_collect'为例

<pre>
let animbaseStr = 'act_avatar_plant_collect';
role.model.playAniUp(`${animbaseStr}_up`);
role.model.playAniDown(`${animbaseStr}_down`);
</pre>

那么如何快速查看已有哪些动画呢？

[动作查看器](https://webdev.popx.com/v1/game/client_host.html?author=qc_jump&project=resourceviewer_0926&diyserver=1&gameid=0bkyyeesxnzsrd9s&editorFormal=true)

=== 添加按键控制 ===
看demo中的代码，提供了一个MoveComponent类
摇杆的显示资源放在'''res-extra'''目录中

[[File:摇杆资源.png]]

以下是示例中添加摇杆控制的代码
<pre>
//摇杆背景
let rocker = new XImage('res-extra/imgs/stick_bg.png');
rocker.width = rocker.height = 164;
rocker.pivotX = rocker.pivotY = 82;
rocker.pos(178, -198);
leftbottom.addChild(rocker);
//摇杆方向
let imgdir = new XImage('res-extra/imgs/stick_dir.png');
imgdir.centerX = imgdir.centerY = 0;
imgdir.anchorX = imgdir.anchorY = 0.5;
imgdir.name = "dir";
rocker.addChild(imgdir);
//摇杆中心点
let node = new XImage('res-extra/imgs/stick_rocker.png');
node.centerX = node.centerY = 0;
node.anchorX = node.anchorY = 0.5;
node.name = "node";
rocker.addChild(node);
//移动
let hero = this.heros.get(this.roleIndex);
if (hero) {
let movecomponent = rocker.addComponent(MoveComponent) as MoveComponent;
movecomponent.init(hero, ctrlayer, rocker);
}
</pre>

示例中，添加了一个触摸区域挂载在根节点的左下角，触摸反馈会根据'''XEvent'''来传递给节点
代码中根据摇杆方向变化来控制人物移动
其中涉及了部分修改玩家状态的服务器代码，可以先忽略

=== 摄像机的跟随 ===
代码中，摄像机跟随人物移动，只需要简单的一行
<pre>
let hero = new Xmodel();
//这是全局的摄像机
XPopManager.instance.xScene.camera.focus = hero;
</pre>

摄像机的旋转视角，demo中也提供了一个类'''CameraComponent'''
和摇杆的节点类似，通过'''XEvent'''来传递点击事件，
根据点击事件的拖动，来修改摄像机的旋转视角 '''xcamera.rotate'''
<pre>
private onCtrlMouseMove(e: XEvent): void {
if(this._touchId != e.touchId) return;
let xcamera = XPopManager.instance.xScene.camera as XCamera;
if(!xcamera)return;
if(this._mouseX == 0) this._mouseX = e.stageX;
if(this._mouseY == 0) this._mouseY = e.stageY;
let offx = e.stageX-this._mouseX;
let offy = e.stageY-this._mouseY;
this._mouseX = e.stageX;
this._mouseY = e.stageY;
xcamera.rotate(offx, offy);
}
</pre>
=== 砖块说明 ===
[[File:砖块说明.png]]

如图所示，我们的世界地图由若干个方形大'''地块'''组成，

每个地块里，可以划分成32*32的平面坐标，一层层叠高，可以有64层高，

转化为三维坐标系就是32*64*32，对应xyz轴，

地块上，可以添加以坐标为单位的'''砖块'''。

其中，cubeId表示砖块的类型，比如草地就是id为1的砖块，该砖块具有可以踩踏行走的特性。

某些其他的砖块具有别的特性，都通过cubeid来区分，当开发者接触地图编辑器时，就会有所了解。

我们以Demo中，'''MoveComponent'''中的一段代码来参考
<pre>
// 游戏世界地图
let scene = XPopManager.instance.xScene;
// 判断水平方向是否有砖块
// 根据坐标位置，找到世界中，其坐标对应的砖块id
let cubeid = scene.getCube(dir.x ,position.y, dir.z)
if(cubeid){
// 根据砖块id，找到砖块的类型，判断其是否和人物碰撞阻挡
scene.getCubeInfo(cubeid, this.cubeInfo);
if(this.cubeInfo.collisionPlayer){
dir.x = position.x;
dir.z = position.z;
}
}
//如果没有砖块或者有无阻挡砖块，给一个向下的位移
cubeid = scene.getCube(dir.x ,position.y-0.1, dir.z)
if(cubeid){
scene.getCubeInfo(cubeid, this.cubeInfo);
if(!this.cubeInfo.collisionPlayer){
dir.y = position.y-0.1;
}
}else{
dir.y = position.y-0.1;
}
</pre>

*再以图中为例，v3的坐标代表了地图上的位置，(24,3,26)
*如果需要设置模型在地图上的位置，用如下代码
<pre>
let pos = new XVector3(x,y,z);
xModel.position = pos;
</pre>

== 资源加载说明 ==

=== 演示加载图片 ===
<pre>
// 测试加载图片
// 创建一个全屏的挂载UI层
let mainui = new XImage();
mainui.left = mainui.right = mainui.top = mainui.bottom = 0;
XPopManager.rootNode.addChild(mainui);

// 图片路径，如果是本地的额外资源，就加上"res-extra/"前缀，否则就是远端资源
let path = 'avatarstart/ball_btn2.png';
// 创建图片
let img = new XImage(path);
// 添加到父节点显示
mainui.addChild(img);
// 设置位置
img.left = img.top = 100;
</pre>

编译，运行后，可以看到，添加了指定的图片

[[File:资源加载一.png]]

=== 公共资源 ===
PGT为开发者提供了很多基础的图片，模型，音频等等的资源。

====怎么查看有哪些公共资源呢？====

*打开项目目录下的package.json文件

[[File:资源加载二.png]]

===== 有sdkVersion =====
*调用查看当前的远端sdk版本，即资源版本，比如"sdkVersion": "1.0.15",
*具体有哪些资源版本可用，可以调用'''npm run sdklist '''来查看
*把下面链接里的v1.0.16替换成和你目前版本一致的数字，就可以查看远端资源列表

[[File:sdkVersion.png]]

[远端文件列表json](https://h5ppreview.jumpw.com/popion/sdk/v1.0.16/version.json)

===== sdkVersion>1.2.60的版本 =====

同样是查看pacakge.json，但是字段换成了"resVersion": "1.0.5"

resVersion

如下是1.0.5版本的资源列表，可以修改数字查找不同版本

[远端文件列表json](https://h5ppreview.jumpw.com/popion/popx-res/version-1.0.5.json)

也可以用命令来查找显示不同的资源版本

'''查看资源版本列表'''：npm run reslist (只包含正式发布的版本)

'''查看所有资源版本列表'''：npm run reslistall

===== 查看json文件 =====

*json文件左侧是游戏内加载的路径，右侧是实际的打过md5值的网络路径

[[File:资源加载四.png]]

这就是我们刚刚演示的加载图片

''avatarstart/ball_btn2.png": "avatarstart/ball_btn2-2c717f83a3.png''

*游戏内我们通过加载接口去加载左侧路径
*游戏外，直接在刚刚的cdnUrl后拼接带md5值的完整路径即可查看

[查看网络资源](https://h5ppreview.jumpw.com/popion/sdk/v1.0.17/avatarstart/ball_btn2-2c717f83a3.png)

[[File:资源加载五.png]]

*音频文件同理，模型文件直接游戏内调用接口显示

=== 额外资源 ===
最基础的demo中，会看到用于演示的摇杆资源是放在'''res-extra'''目录下的。

一般来说，开发者的一些特制UI，图形，可以放在这里。

加载时在路径前加上"res-extra/"即可。

*注意，额外资源调用前，要调用如下固定代码开启合图资源的配置，建议参考demo，在游戏入口就初始化调用一次
<pre>
XResManager.instance.enableAtlas("res-extra/fileconfig.json",()=>{
// 可以调用额外资源了
});
</pre>

每次在调用命令，npm run ui时，会更新上述的'''fileconfig.json'''文件。

[[#npm run ui ( 生成ui类 )]]

==== npm run ui ( 生成ui类 ) ====
如果开发者有额外的ui交互需求，希望在IDE中自己拼接UI
可以在指定目录下，
* '''ui_laya/laya/''' - 开发者可以自由扩展的ui资源目录
* '''ui_laya/laya/pages''' - 开发者创建的.scene文件目录
* '''ui_laya/laya/assets/uiextra''' - secne文件中引用到的各种美术资源，包括音频和动画

-运行后，会在client目录代码中，生成对应的XUIComponent类，[[#XUIComponent]]

-运行后，会更新'''res-extra'''文件夹下的fileconfig.json

*注意，我们目前不支持第三方模型文件，模型必须提交审核，不放在res-extra中

=== 模型查看器 ===
*除了图片资源外，为了方便开发者使用，我们额外做了一个模型查看器

[公共模型查看器](https://webdev.popx.com/client_host.html?author=qc_jump&project=resourceviewer_0926&diyserver=1&gameid=09kyye6gcmmda79s&editorFormal=true)

== UI界面开发 ==

=== git拉取ui工程到本地 ===

==== 泡饭的项目发布后获取到了git地址 ====
[[File:发布模板后获得git地址.png]]

==== 查看git密钥 ====

[[File:查看git密钥.png]]

==== 使用accesstoken来拉取项目到本地 ====

===== 常见的git工具中=====

git clone 地址

输入泡饭账号和accesstoken即可拉取，注意不是泡饭的密码，是token

===== 没有工具时用命令拉取说明=====

[[File:如何使用accesstoken拉取.png]]

=== 安装本地ui的编辑环境 ===

==== laya 版本 v2.13.1 ====
- [laya官方ide](https://ldc2.layabox.com/layadownload/?type=layaairide-LayaAir%20IDE%202.13.1)

==== 安装项目自定义封装的cmd命令库 ====
- 推荐安装方式：
<pre>
npm i popxcmd -g --registry https://registry.popx.com
</pre>

==== node 版本 v10.24.1 ====
- 必须使用指定的nodejs版本 ，推荐安装nvm以自由转换node版本。
- [nvm下载及安装方式](https://blog.csdn.net/ppz8823/article/details/130862191)

*记得nvm需要换源，否则后续安装可能会出错，按照下述操作

[[File:nvm换源.png]]

*最下面两行修改node和npm的镜像地址
<pre>
node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/
</pre>

*安装nvm后，命令行运行如下命令切换到node版本v10.24.1，一步步来:
<pre>
// 安装
nvm install 10.24.1
// 等待安装完成后，切换
nvm use 10.24.1
</pre>

*nodejs也需要用下面的命令来换源，修改镜像地址
<pre>
npm config set registry https://registry.popx.com/
</pre>

==== 修改host文件 ====
- 找到host文件，一般在`C:\WINDOWS\system32\drivers\etc`目录下。
- 在文件末尾添加：
<pre>
199.232.68.133 raw.githubusercontent.com
</pre>

=== 在编辑器中创建UI ===
==== 打开Laya工程 ====
使用指定版本的Laya编辑器打开 `demo/ui_laya/ui_laya.laya` 项目。

==== 添加.scene界面 ====
在编辑器中，可以添加一个新的scene界面，并在其上放置UI元素。

[[File:新界面.png]]

==== 界面添加UI组件 ====
例如，添加一个名为 `btnFirst` 的按钮，并确保其 `var` 属性有值，以便后续导出。

[[File:UI按钮有值.png]]

添加后，记得保存，'''ctrl+S'''

=== 额外资源的添加 ===

注意，所有上述scene中用到的美术资源，必须放在Assets/uiextra/ 目录下

否则导出ui时会失败

=== 运行生成UI命令 ===
在命令行中运行以下命令来生成UI代码：

<pre>
npm run ui
</pre>

运行成功后，生成的UI类将位于 `src/ui/popxMaxUI.ts` 文件中。

[[File:UI生成代码.png]]

其中，添加了一个和scene名相同的UI类，
并且，var有值的组件也一起生成了对应属性。

=== 修改后的资源，git上传到远端 ===

上传后，泡饭即可使用

先git commit提交
注意推送时要用如下命令

git push --force

如果弹出输入框，账号输入泡饭账号名，密码输入accesstoken

[[File:新泡饭推送到远端.png]]

=== 代码控制XUIComponent ===
==== 注册UI类的控制文件 ====
使用 `PopxBridge.regUIClass()` 方法在相应的类中注册UI类，并处理UI相关的按键逻辑。
<pre>
//注册自定义的ui类
PopxBridge.regUIClass(DemoUI.getClassName(), DemoUI);
</pre>

以下是我们新加UI的最基础代码，在界面显示的时候，注册点击事件，点击后打印日志
<pre>
export class DemoUI extends uiextra.demoUIUI{

constructor(){
super();
}

onAwake(): void {

}

onEnable(): void {
// 设置在顶层可以被点击
this.zOrder = 1;
this.first_btn.on(XEvent.CLICK, this, this.onClickFirstBtn);
}

private onClickFirstBtn(e:XEvent){
console.log("click first btn");
}
}
</pre>

==== 代码调用显示UI ====
通过 `xUiManager.instance.openUI()` 方法来调用并显示UI界面。
<pre>
// 加载对应的json文件路径，并挂载在指定父节点上
XUiManager.instance.openUI('res-extra/ui/demoUI', XPopManager.rootNode);
</pre>

-编译，运行

[[File:UI点击按钮.png]]

==== 代码调用加载组件 ====
*某些界面上的元素，比如卡牌，也可以类似做成一个scene，运行npm run ui 自动生成类
*比如类名为CardView
*注册和UI注册类似
<pre>
PopxBridge.regUIClass(CardView.getClassName(), CardView);
</pre>
*创建时，调用`XUiManager.instance.createView`
<pre>
XUiManager.instance.createView(path,parent,this.onLoadCardView,showData);

onLoadCardView(view:XUIComponent)
{
}
</pre>

== 前后端数据交互 ==

该篇会讲述服务器和前端的数据同步，如果想要先了解项目目录和工作流，建议先参考如下篇幅
[[#主要工程目录]]

=== 进入房间（游戏世界） ===
如下是最基本的开发登录流程说明
{| class="wikitable"
|-
! 步骤
! 描述
! 流向
|-
| 开始
| 流程的开始
| -> 登录页面
|-
| 登录页面
| 账号密码，选定地图，输入房间号（可不填）
| -> 远端服务器（官方）
|-
| 远端服务器（官方）
| 获取玩家账户信息，分配到房间,房间就是我们的host代码
| -> Client 和 -> Host
|-
| Client
| 监听XPopManager.onGameStart
| -> 前端逻辑开始
|-
| Host
| 监听XPopManager.onHostStart
| -> 房间战斗逻辑开始

|}

远端服务器(官方)会处理最基本的登录，分配房间，创建游戏世界的逻辑，并且同步该世界中的游戏数据。

通过'''XpopManager'''管理类，来向Client和Host抛出事件，开发者可以监听这些事件做处理。

开发者需要关心的逻辑，就是Clint和Server（上图中Host）目录下的代码。

=== 前后端协议交互 ===
项目采用proto来做相互通信

=== 前后端共用配置 ===
前端'''src/client'''目录和后端'''src/server'''目录中，都可以调用如下代码来加载所有的表格配置
<pre>
CsvManager.ins.loadCsvs(this, () => {
// Do some thing after load
});
</pre>

表格的加载逻辑和解析逻辑，可以参考CsvManager中的代码
'''src/shared/csv/CsvManager.ts'''

''如何新增配置?''
以demo中的'''item.csv'''为例.
*1.配置csv文件资源的根目录为'''res-extra/csv/''' ,在里面添加'''item.csv'''
*2.'''CsvManager.ts'''文件中，添加读取表格和解析表格的逻辑
<pre>
// loadCsvs代码中，添加你需要解析的csv名称
public loadCsvs(caller: any = null, listener: Function = null) {
let assets = [
this._prefix + "item.csv",
];
// XResManager加载本地资源
XResManager.instance.loadText(assets, () => {
// 在加载完成的回调中，处理表格数据结构，生成CItemData，不再赘述
this.onCompleted(caller, listener);
});
}
</pre>
*3.解析表格得到的'''CItemData'''结构，定义在'''src/shared/dataMgr/'''中，可以被前后端一起调用
*4.如果是加载json文件，用'''XResManager.instance.loadText'''

=== 玩家战斗数据快照 ===
游戏战斗服务器中，每个玩家的实时信息，通过快照来更新
==== XVF_SnapData ====
以demo中的'''Snap_UserData.ts'''为例
*该玩家数据中类中，包含的各种public变量，都是''XVF_SnapData''接口类型
<pre>
export class Snap_UserData {
//坐标旋转
public position: XVF_SnapData<SyncPos>;
//状态
public state: XVF_SnapData<SyncState>;
//hp
public hp: XVF_SnapData<number>;
}
</pre>
快照类型数据，前端负责注册和监听，服务器负责修改
*每次该接口类型的数据发生变化时，会调用OnSet方法，这类数据的修改逻辑是：服务器修改，前端监听变化
** 前端登录成功后，服务器注册对应玩家数据
** 前端对数据中的某个XVF_SnapData做监听，注册OnSet方法
** 服务器战斗逻辑修改了该数据时，前端根据OnSet的逻辑做表现处理

服务器先注册全局的快照
<pre>
let userData = new Snap_UserData();
XPopManager.instance.xHost.RegisterSnapshot(`UserData${i}`, userData);
</pre>

前端绑定同一个地址的快照
<pre>
this._userData = new Snap_UserData();
XPopManager.instance.xRemote.RegisterSnapshot(`UserData${index}`, this._userData);
</pre>

*XVF_SnapData数据，如果是复杂类型，需要调用UpdateData()方法，前端才能触发OnSet
如下的SyncState就是复杂类型
<pre>
public state: XVF_SnapData<SyncState>;
public setState(key:string, obj:string):void{
this.state.value.key = key;
this.state.value.obj = obj;
this.state.UpdateData();
}
</pre>
*XVF_SnapData如果是基础类型，不需要调用UpdateData()
<pre>
public hp: XVF_SnapData<number>;
public setHP(hp:number):void {
this.hp.value = hp;
}
</pre>

=== 代码如何调试 ===
==== 前端调试 ====
直接在网页上调试

f12打开控制台，

点击源代码，

可以根据代码目录结构找到想要断点的文件，

也可以快捷键"ctrl + p"输入文件名查找（mac上是cmd + p）,

找到后，点击具体左侧代码行数标签即可。

可以很方便的观察堆栈和变量信息

[[File:网页断点调试.png]]

==== 本地服务器调试 ====
*本地服务器在调用命令'''npm run server'''后，会启动一个Host网页
*只要是网页，那就能调试js代码
*打开网页的开发者工具（一般浏览器是f12）,找到'''index.js'''文件
*这时有个问题，发现打不了断点，原因是代码编译过程被混淆了

[[File:服务器调试一.png]]

*我们需要关闭混淆的配置，在'''rollup.config.js'''中修改

[[File:服务器调试二.png]]

*修改plugins中，关闭sourcemap，不使用terser()压缩

[[File:服务器调试三.png]]

*修改完后，每次编译后运行的服务器Host代码就都可以断点了

编译，启动服务器，运行
<pre>
npm run build
npm run server
</pre>

*这次会发现，Host的网页代码有了行号，可以断点调试了

[[File:服务器调试四.png]]
==== 调试注意事项 ====
*每次'''npm run build'''后，如果修改了服务器代码，可以在本地host的浏览器里，立刻刷新，F5或者shift+f5
*如果修改了编译脚本来调试服务器，记得最后打包上传前，把rollup的代码改回来

== 地图的制作和选取 ==
=== 地图制作导出 ===

[[File:地图编辑视频.png]]

教学视频已经上传到网页链接

[新建地图](https://formalhead.popx.com/popxVedio/mapeditor/新建地图.mp4)

[地块操作](https://formalhead.popx.com/popxVedio/mapeditor/地块操作.mp4)

[地块（水）](https://formalhead.popx.com/popxVedio/mapeditor/地块（水）.mp4)

[地形设置（增加）](https://formalhead.popx.com/popxVedio/mapeditor/地形设置（增加）.mp4)

[新地编添加预制件和编辑](https://formalhead.popx.com/popxVedio/mapeditor/新地编添加预制件和编辑.mp4)

[预制件操作](https://formalhead.popx.com/popxVedio/mapeditor/预制件操作.mp4)

[授权给他人使用](https://formalhead.popx.com/popxVedio/mapeditor/授权.mp4)

[如何游戏内绑定后台玩法和地图](https://formalhead.popx.com/popxVedio/mapeditor/如何游戏内绑定后台玩法和地图.mp4)

=== 开发环境选择地图 ===
我们在登录界面，可以通过填写你gameid中的地图名字，来进入指定地图。

所以必须要先创建gameid，并且选择至少一张地图，该地图才能在调试时进入。

举例：

*上传地图到某个游戏gameid时，会从你自己的'''可用地图'''中选择。

- 可用地图指的是你自己制作上传了地图。或者其他人共享给了你地图。

*比如你的可用地图名字是"推箱子"。

*右边会有可填写的自定义地图名字，比如"第一关"

那么登录的时候就是填写 "第一关"

*'''也就是说，地图做完后，必须要在审核平台上，添加到玩法里，生成自定义的名字，才可以在测试时填写进去生效 '''

== 打包与上传 ==

[[File:泡饭点击发布游戏.png]]

点击发布后，会把构建生成的压缩包上传到远端，就可以去试玩了。

=== 玩法测试 ===

[[File:泡饭点击打开审核后台.png]]

* [[上传流程|查看文档中试玩/审核/发布的部分]]

== 项目目录 ==

=== 主要工程目录 ===
对于开发者，需要关心和操作的目录如下：

* '''node_modules/''' - 通过npm安装的PGC库文件，对外暴露的方法，可以通过bridge.d.ts来外部引用
* '''res-extra/''' - 开发者除了PGC的远程资源外，需要额外使用到的资源目录，比如UI，图片，音频，表格，最后会打包上传到PGC远端资源服务器
* '''ui/''' - 开发者自己在laya编辑器中，拼接的界面json文件，运行命令后，会转化为PGT指定的XUIComponent存放于此
* '''src/''' - 开发者所有的战斗逻辑代码修改都在此进行
* '''src/client/''' - 前端代码，入口文件index.ts，监听XPopManager.onGameStart，前端游戏逻辑
* '''src/server/''' - 后端代码，入口文件index.ts，监听XPopManager.onHostStart，后端游戏逻辑
* '''src/shared/''' - 前后端共用的数据结构，包括表格，协议，玩家数据
* '''dist/''' - 编译后，生成的运行文件，包含前后端代码
* '''dist/client/''' - 编译后生成的混淆的前端代码
* '''dist/host/''' - 编译后服务端的代码文件，里面也包括表格数据的缓存

=== 前后端协议通信生成 ===

[[File:泡饭点击生成协议.png]]

==== 协议通信 ====
该命令会用到tsrpc的proto协议，
把'''src/shared/protocols'''下的指定格式文件，
转换到'''src/shared/protocols/generated/serviceProto'''文件中，

* 文件名为：Ptl{接口名}.ts '''（Ptl 是 Protocol 的缩写，l是小写的L）'''
* 请求类型名为： Req{接口名}，通过 interface 或 type 定义，需 export
* 响应类型名为：Res{接口名}，通过 interface 或 type 定义，需 export

例如，添加'''PtlPosition.ts'''文件
文件代码如下
<pre>
// 该接口用于向服务器同步自身的坐标
export interface ReqPosition {
i: number;
x: number;
y: number;
z: number;
ry: number;
}
export interface ResPosition {
ret: string;
diy: string;
}
</pre>

'''serviceProto.ts'''中会增加可外部调用的api类型
<pre>
export interface ServiceType {
api: {
"Position": {
req: ReqPosition,
res: ResPosition
},
},
msg: {

}
}
</pre>

'''前端代码调用请求'''
<pre>
// 前端可以用promise语法来调用同步位置的Request，异步处理服务器的返回值
let remote = XPopManager.instance.xRemote;
let ret = await remote.Request('Position', {i: 1, x:2, y:3, z:4, ry:5});
if(ret && ret.isSucc){
console.log(ret.res.diy)
}
</pre>

'''后端代码监听请求处理返回'''
<pre>
// 服务器收到前端请求的处理返回RegisterRpc
let host = XPopManager.instance.xHost;
//当收到坐标变化请求
host.RegisterRpc("Position", async (call: ApiCall<ReqPosition, ResPosition>) => {
let index = call.req.i;
let userData = this.usersData.get(index);
userData.setPosition(call.req.x, call.req.y, call.req.z, call.req.ry);
return call.succ({
ret: "Success",
diy: "自定义参数"
});
});
</pre>
如果想更多了解proto的结构和数据类型说明，可以参考官方链接
[tsrpc-proto格式说明](https://tsrpc.cn/docs/server/service-proto.html)

== 核心类目说明 ==
=== XPopManager ===
Bridge.d.ts中的核心类

对游戏逻辑进行了结构化的拆封和管理，

可以理解为，

库文件内处理了各种玩家的逻辑，比如登录，加载地图，分配房间，快照数据同步等等,然后关键的几个节点，暴露给外部去执行游戏逻辑。

开发者只需要去编写独立游戏模块的代码，其中，'''Xremote'''暴露给前端处理，'''Xhost'''暴露给后端处理

下面是最重要的几个生命周期函数
;onGameStart:玩家已经完成了登录步骤，已经分配好了房间，通知前端游戏开始
;onHostStart:玩家已经完成了登录步骤，已经分配好了房间，通知后端游戏开始
;onGameOver:游戏结束（一般是玩家都离开了战斗房间）
;onUpdate:每一帧会调用更新

我们在demo中，index.ts里，可以给这几个方法监听绑定函数，输出日志就可以查看

<pre>
XPopManager.onGameStart = ()=>{
new Main();
console.log("qc,XPopManager.onGameStart");
}

XPopManager.onGameOver = () => {
console.log("qc,XPopManager.onGameOver");
}

XPopManager.onHostStart = () => {
console.log("qc,XPopManager.onHostStart");
}

XPopManager.onUpdate = () => {
console.log("XPopManager.onUpdate");
}
</pre>

[[File:XPopManager生命周期.png]]

=== XRemote(前端) ===
*以下是最关键的生命周期和方法调用，调用逻辑可以自定义设计，后端代码同理
;UserID:玩家进入游戏的唯一id
;onUserEnter:每当房间内玩家进入时会调用，前端可以在此根据返回的userId来同步XHost玩家的快照数据，创建角色等等
;onUserLeave:每当房间内玩家离开时会调用，前端根据userId来处理模型的销毁
;RegisterSnapshot:用于注册绑定快照，快照类型开发者自定义，需要和XHost代码中绑定的地址一致，才可以收到OnSet回调
;Request:发送RPC请求，请求和回调的代码由protocol生成

=== XHost(后端) ===
;onUserEnter:每当房间内玩家进入时会调用，初始化玩家身上的快照数据，可以根据人数来判断游戏阶段，比如准备阶段
;onUserLeave:每当房间内玩家离开时会调用，清理玩家数据，可以根据玩家人数来判断是否进入结算或者游戏结束
;RegisterSnapshot:用于注册绑定快照，快照类型开发者自定义，需要和XRemote代码中绑定的地址一致
;RegisterRpc:注册RPC回调

=== XUIComponent(UI组件) ===
UI组件通过XUiManager.instance.OpenUI或者XUiManager.instance.CreateView加载显示
;showUI:调用后会设置active为true，当调用创建的方法，加载成功显示时也会调用一次，可以在创建时传参，每次主动调用也可以传参。
;hideUI:把该组件的active设置成false
;closeUI:把该组件从父节点移除，可以传参处理移除成功时的回调
=== XEventDispatcher(事件)===
我们可以根据已有的XEventDispatcher来封装一个单例，这样就能外部夸文件调用事件了。
如下为演示封装的单例
<pre>
export class EventManager extends XEventDispatcher{

constructor () {
super();
}

private static _instance: EventManager
public static get instance(): EventManager {
if (!this._instance) { this._instance = new EventManager(); }
return this._instance;
}

}
</pre>

事件的派发
<pre>
EventManager.instance.dispatch("new_event_name", ...args);
</pre>

事件的监听
<pre>
EventManager.instance.add("new_event_name", this, this.ParseNewEvent);

private ParseNewEvent(...args)
{
console.log("parse new event")
}
</pre>

== 常见工作流问题 ==
=== 如何把本地的项目上传到泡饭 ===
==== 建议先上传项目到自己的git仓库 ====
==== 从git拉取 ====

点击图中创建模板按钮，从git创建工程

[[File:点击从git创建工程.png]]

[[File:git项目地址.png]]

== 官方论坛 ==
*[论坛地址](https://bbs.popx.com/)
*可以由我们内部人员给出的邀请链接申请加入论坛。
*申请后，等待审核人员核实，批准后，即可浏览论坛内容，发表疑问贴。
*强烈建议多去论坛搜索关键字，发帖会有对应的专业人员回答问题，大家一起维护论坛生态。
*常见问题faq帖子会持续维护

[论坛FAQ](https://bbs.popx.com/t/topic/53)

2025-02-10T08:58:55Z

Liuweichen：/* 官方论坛 */

== 泡饭工坊介绍 ==
===泡饭工坊是什么？===
泡饭是一套网页虚拟环境下的代码编辑工具，内嵌了多种预设和模板，集成了vscode来编辑代码，自动编译，可以方便的预览和分享给小伙伴体验。
=== 泡饭链接 ===
[链接](https://webdev.popx.com)

=== 泡饭账号注册登录 ===

==== 没账号的需要在泡饭注册账号 ====

[[File:新注册账号手机号.png]]

'''请记住您的账号密码，这关系到后续我们管理您的使用权限'''

==== 和我们内部人员沟通，申请后台权限 ====

'''如需开通后台使用权限，将您的账号告知我们内部人员帮操作，等待通知完成后，重新刷新网页即可'''

==== 第一次需要创建一个工程 ====

[[File:新点击模板商店创建模板.png]]

[[File:新模板下载.png]]

[[File:新下载工程.png]]

==== 有了工程后，打开工程 ====

[[File:新打开我的工程.png]]

== 打开泡饭体验项目 ==

参考视频[1.泡饭运行环境演示.mp4]

== 如何用泡饭开发自己的项目 ==

=== 点击跳转后台 ===

===='''就第一次需要创建打开一个工程，才能出现地图编辑器的跳转页面''' ====

[[File:新跳转后台.png]]

=== 后台创建游戏，绑定地图 ===
* 需要泡饭跳转到后台，去新建游戏，生成独属于你的gameid和secret，这在后续的开发和上传时至关重要，请点击下方超链接，去参考其中新建gameid的部分
* [[上传流程|请看该链接中，新建游戏玩法的部分]]

=== 修改package.json进入自己的游戏和地图 ===
- 点击左侧修改配置按钮
[[File:新点击修改配置.png]]
- gameid 开发者后台中指定的游戏玩法
- secretkey 游戏玩法对应的密钥
- defaultMap 游戏玩法中，指定的地图，请在后台至少指定一张，默认填写"地图_0"
- sdkVersion sdk版本号，点击修改可以弹出下拉框，一般选用release标签的稳定版本，修改后，会去修改对应的bridge依赖，并且下载
- resVersion 美术资源版本号，会影响游戏内地图和模型的显示，一般选用最新的版本即可

=== 首次运行需要先发布 ===

当前的gameid是最新的，

目前后台服务器还没有一个初始版本的记录，所以需要在package.json中，修改完gameid之后。

首次运行要发布游戏（后续不需要每次发布，直接保存就可以编译调试）。

[[File:泡饭点击发布游戏.png]]

等待右上脚提示发布完成，即可启动进入游戏

=== 启动项目 ===

一般选用启动游戏（服务器模式）

[[File:新泡饭点击启动游戏.png]]

==== 登录界面 ====
- 运行后，浏览器将显示登陆界面。
[[File:默认地图.png]]
- 账号密码随便输入，会创建新账号
- 输入账号密码后，选择指定地图（可选），即可看到战斗服务器世界中有自己的人物。
- 默认的demo工程中，如果没有修改gameid和secretKey，地图请填写"地图_0"

== 泡饭模板的多人合作 ==

=== 发布模板 ===

[[File:发布工程多人合作.png]]

设置团队成员权限和名称

[[File:设置团队成员权限.png]]

=== 发布后管理项目 ===

发布后可以在商店模板里去修改自己发布的项目。

[[File:发布后编辑模板权限.png]]

=== 其他成员就可以在模板商店拉取模板了 ===

比如上图中的playername1的账号，就可以拉取模板了

=== 打开项目 ===

点击编辑按钮，切换到vscode运行环境。

[[File:点击编辑按钮切换vscode.png]]

=== 团队成员修改提交 ===

我们尝试写第一行代码提交下

[[File:写第一行代码.png]]

[[File:模板内git_commit.png]]

具体在vscode中，怎么使用git来提交和拉取，可以参考如下文档

[vscode使用git插件](https://blog.csdn.net/khhmd/article/details/144131405)

=== 多人合作冲突的解决(遇到冲突再看，可以先跳过) ===
==== 选择远端的master分支来merge ====

[[File:git冲突merge.png]]

[[File:gitmerge选择远端.png]]

==== 根据需求去修改冲突文件 ====

[[File:git冲突文件解决.png]]

==== 冲突文件修改完成，resolve ====
[[File:git冲突保存.png]]
[[File:解决冲突完成.png]]

==== 同步到远端 ====

[[File:gitmerge同步到远端.png]]

== 前端基础逻辑 ==

根据以下步骤，一步步进入泡泡的游戏世界，即使你是新手也无需担心。

=== 前端游戏入口 ===
- '''/src/client/index.ts''' 文件中的 `XPopManager.onGameStart` 是前端的主要入口点。

=== 创建第一个人物 ===
在 `simpleGame` 类中，我们将创建并初始化第一个游戏人物。

<pre>
export class simpleGame {
private firstModel: XModelHero;

constructor() {
// 创建第一个人物
this.firstModel = new XModelHero();
let path = 'role/model_avatar_body_default';

// 加载人物模型并播放动画
this.firstModel.loadModel(path, null, this, (success) => {
// 播放跑步动画
let actName = "act_avatar_base_run";
this.firstModel.playAniUp(`${actName}_up`);
this.firstModel.playAniDown(`${actName}_down`);

// 摄像机跟随
let camera = XPopManager.instance.xScene.camera;
camera.focus = this.firstModel;

// 定时更新人物位置
XTimer.loop(100, this, this.updateModelPos.bind(this));
});
}

updateModelPos(delta: number, frame?: string) {
// 更新人物位置
this.firstModel.position.x += 0.1;
}
}

// 设置游戏启动时执行
XPopManager.onGameStart = () => {
new simpleGame();
}
</pre>

*注意：请将原代码中的 '''new Main()''' 替换为 '''new simpleGame()''';
上述的代码我们以最简单的方式，去掉一切服务器交互，添加一个基础模型到游戏中跑动

再提醒一次，每次有代码修改后，运行前需调用命令进行编译
[[#编译]]

=== 播放人物的动作 ===
我们的人物有上下半身，在知道动画名字的情况下，需要分上下半身来播放动画

以'act_avatar_plant_collect'为例

<pre>
let animbaseStr = 'act_avatar_plant_collect';
role.model.playAniUp(`${animbaseStr}_up`);
role.model.playAniDown(`${animbaseStr}_down`);
</pre>

那么如何快速查看已有哪些动画呢？

[动作查看器](https://webdev.popx.com/v1/game/client_host.html?author=qc_jump&project=resourceviewer_0926&diyserver=1&gameid=0bkyyeesxnzsrd9s&editorFormal=true)

=== 添加按键控制 ===
看demo中的代码，提供了一个MoveComponent类
摇杆的显示资源放在'''res-extra'''目录中

[[File:摇杆资源.png]]

以下是示例中添加摇杆控制的代码
<pre>
//摇杆背景
let rocker = new XImage('res-extra/imgs/stick_bg.png');
rocker.width = rocker.height = 164;
rocker.pivotX = rocker.pivotY = 82;
rocker.pos(178, -198);
leftbottom.addChild(rocker);
//摇杆方向
let imgdir = new XImage('res-extra/imgs/stick_dir.png');
imgdir.centerX = imgdir.centerY = 0;
imgdir.anchorX = imgdir.anchorY = 0.5;
imgdir.name = "dir";
rocker.addChild(imgdir);
//摇杆中心点
let node = new XImage('res-extra/imgs/stick_rocker.png');
node.centerX = node.centerY = 0;
node.anchorX = node.anchorY = 0.5;
node.name = "node";
rocker.addChild(node);
//移动
let hero = this.heros.get(this.roleIndex);
if (hero) {
let movecomponent = rocker.addComponent(MoveComponent) as MoveComponent;
movecomponent.init(hero, ctrlayer, rocker);
}
</pre>

示例中，添加了一个触摸区域挂载在根节点的左下角，触摸反馈会根据'''XEvent'''来传递给节点
代码中根据摇杆方向变化来控制人物移动
其中涉及了部分修改玩家状态的服务器代码，可以先忽略

=== 摄像机的跟随 ===
代码中，摄像机跟随人物移动，只需要简单的一行
<pre>
let hero = new Xmodel();
//这是全局的摄像机
XPopManager.instance.xScene.camera.focus = hero;
</pre>

摄像机的旋转视角，demo中也提供了一个类'''CameraComponent'''
和摇杆的节点类似，通过'''XEvent'''来传递点击事件，
根据点击事件的拖动，来修改摄像机的旋转视角 '''xcamera.rotate'''
<pre>
private onCtrlMouseMove(e: XEvent): void {
if(this._touchId != e.touchId) return;
let xcamera = XPopManager.instance.xScene.camera as XCamera;
if(!xcamera)return;
if(this._mouseX == 0) this._mouseX = e.stageX;
if(this._mouseY == 0) this._mouseY = e.stageY;
let offx = e.stageX-this._mouseX;
let offy = e.stageY-this._mouseY;
this._mouseX = e.stageX;
this._mouseY = e.stageY;
xcamera.rotate(offx, offy);
}
</pre>
=== 砖块说明 ===
[[File:砖块说明.png]]

如图所示，我们的世界地图由若干个方形大'''地块'''组成，

每个地块里，可以划分成32*32的平面坐标，一层层叠高，可以有64层高，

转化为三维坐标系就是32*64*32，对应xyz轴，

地块上，可以添加以坐标为单位的'''砖块'''。

其中，cubeId表示砖块的类型，比如草地就是id为1的砖块，该砖块具有可以踩踏行走的特性。

某些其他的砖块具有别的特性，都通过cubeid来区分，当开发者接触地图编辑器时，就会有所了解。

我们以Demo中，'''MoveComponent'''中的一段代码来参考
<pre>
// 游戏世界地图
let scene = XPopManager.instance.xScene;
// 判断水平方向是否有砖块
// 根据坐标位置，找到世界中，其坐标对应的砖块id
let cubeid = scene.getCube(dir.x ,position.y, dir.z)
if(cubeid){
// 根据砖块id，找到砖块的类型，判断其是否和人物碰撞阻挡
scene.getCubeInfo(cubeid, this.cubeInfo);
if(this.cubeInfo.collisionPlayer){
dir.x = position.x;
dir.z = position.z;
}
}
//如果没有砖块或者有无阻挡砖块，给一个向下的位移
cubeid = scene.getCube(dir.x ,position.y-0.1, dir.z)
if(cubeid){
scene.getCubeInfo(cubeid, this.cubeInfo);
if(!this.cubeInfo.collisionPlayer){
dir.y = position.y-0.1;
}
}else{
dir.y = position.y-0.1;
}
</pre>

*再以图中为例，v3的坐标代表了地图上的位置，(24,3,26)
*如果需要设置模型在地图上的位置，用如下代码
<pre>
let pos = new XVector3(x,y,z);
xModel.position = pos;
</pre>

== 资源加载说明 ==

=== 演示加载图片 ===
<pre>
// 测试加载图片
// 创建一个全屏的挂载UI层
let mainui = new XImage();
mainui.left = mainui.right = mainui.top = mainui.bottom = 0;
XPopManager.rootNode.addChild(mainui);

// 图片路径，如果是本地的额外资源，就加上"res-extra/"前缀，否则就是远端资源
let path = 'avatarstart/ball_btn2.png';
// 创建图片
let img = new XImage(path);
// 添加到父节点显示
mainui.addChild(img);
// 设置位置
img.left = img.top = 100;
</pre>

编译，运行后，可以看到，添加了指定的图片

[[File:资源加载一.png]]

=== 公共资源 ===
PGT为开发者提供了很多基础的图片，模型，音频等等的资源。

====怎么查看有哪些公共资源呢？====

*打开项目目录下的package.json文件

[[File:资源加载二.png]]

===== 有sdkVersion =====
*调用查看当前的远端sdk版本，即资源版本，比如"sdkVersion": "1.0.15",
*具体有哪些资源版本可用，可以调用'''npm run sdklist '''来查看
*把下面链接里的v1.0.16替换成和你目前版本一致的数字，就可以查看远端资源列表

[[File:sdkVersion.png]]

[远端文件列表json](https://h5ppreview.jumpw.com/popion/sdk/v1.0.16/version.json)

===== sdkVersion>1.2.60的版本 =====

同样是查看pacakge.json，但是字段换成了"resVersion": "1.0.5"

resVersion

如下是1.0.5版本的资源列表，可以修改数字查找不同版本

[远端文件列表json](https://h5ppreview.jumpw.com/popion/popx-res/version-1.0.5.json)

也可以用命令来查找显示不同的资源版本

'''查看资源版本列表'''：npm run reslist (只包含正式发布的版本)

'''查看所有资源版本列表'''：npm run reslistall

===== 查看json文件 =====

*json文件左侧是游戏内加载的路径，右侧是实际的打过md5值的网络路径

[[File:资源加载四.png]]

这就是我们刚刚演示的加载图片

''avatarstart/ball_btn2.png": "avatarstart/ball_btn2-2c717f83a3.png''

*游戏内我们通过加载接口去加载左侧路径
*游戏外，直接在刚刚的cdnUrl后拼接带md5值的完整路径即可查看

[查看网络资源](https://h5ppreview.jumpw.com/popion/sdk/v1.0.17/avatarstart/ball_btn2-2c717f83a3.png)

[[File:资源加载五.png]]

*音频文件同理，模型文件直接游戏内调用接口显示

=== 额外资源 ===
最基础的demo中，会看到用于演示的摇杆资源是放在'''res-extra'''目录下的。

一般来说，开发者的一些特制UI，图形，可以放在这里。

加载时在路径前加上"res-extra/"即可。

*注意，额外资源调用前，要调用如下固定代码开启合图资源的配置，建议参考demo，在游戏入口就初始化调用一次
<pre>
XResManager.instance.enableAtlas("res-extra/fileconfig.json",()=>{
// 可以调用额外资源了
});
</pre>

每次在调用命令，npm run ui时，会更新上述的'''fileconfig.json'''文件。

[[#npm run ui ( 生成ui类 )]]

==== npm run ui ( 生成ui类 ) ====
如果开发者有额外的ui交互需求，希望在IDE中自己拼接UI
可以在指定目录下，
* '''ui_laya/laya/''' - 开发者可以自由扩展的ui资源目录
* '''ui_laya/laya/pages''' - 开发者创建的.scene文件目录
* '''ui_laya/laya/assets/uiextra''' - secne文件中引用到的各种美术资源，包括音频和动画

-运行后，会在client目录代码中，生成对应的XUIComponent类，[[#XUIComponent]]

-运行后，会更新'''res-extra'''文件夹下的fileconfig.json

*注意，我们目前不支持第三方模型文件，模型必须提交审核，不放在res-extra中

=== 模型查看器 ===
*除了图片资源外，为了方便开发者使用，我们额外做了一个模型查看器

[公共模型查看器](https://webdev.popx.com/client_host.html?author=qc_jump&project=resourceviewer_0926&diyserver=1&gameid=09kyye6gcmmda79s&editorFormal=true)

== UI界面开发 ==

=== git拉取ui工程到本地 ===

==== 泡饭的项目发布后获取到了git地址 ====
[[File:发布模板后获得git地址.png]]

==== 查看git密钥 ====

[[File:查看git密钥.png]]

==== 使用accesstoken来拉取项目到本地 ====

===== 常见的git工具中=====

git clone 地址

输入泡饭账号和accesstoken即可拉取，注意不是泡饭的密码，是token

===== 没有工具时用命令拉取说明=====

[[File:如何使用accesstoken拉取.png]]

=== 安装本地ui的编辑环境 ===

==== laya 版本 v2.13.1 ====
- [laya官方ide](https://ldc2.layabox.com/layadownload/?type=layaairide-LayaAir%20IDE%202.13.1)

==== 安装项目自定义封装的cmd命令库 ====
- 推荐安装方式：
<pre>
npm i popxcmd -g --registry https://registry.popx.com
</pre>

==== node 版本 v10.24.1 ====
- 必须使用指定的nodejs版本 ，推荐安装nvm以自由转换node版本。
- [nvm下载及安装方式](https://blog.csdn.net/ppz8823/article/details/130862191)

*记得nvm需要换源，否则后续安装可能会出错，按照下述操作

[[File:nvm换源.png]]

*最下面两行修改node和npm的镜像地址
<pre>
node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/
</pre>

*安装nvm后，命令行运行如下命令切换到node版本v10.24.1，一步步来:
<pre>
// 安装
nvm install 10.24.1
// 等待安装完成后，切换
nvm use 10.24.1
</pre>

*nodejs也需要用下面的命令来换源，修改镜像地址
<pre>
npm config set registry https://registry.popx.com/
</pre>

==== 修改host文件 ====
- 找到host文件，一般在`C:\WINDOWS\system32\drivers\etc`目录下。
- 在文件末尾添加：
<pre>
199.232.68.133 raw.githubusercontent.com
</pre>

=== 在编辑器中创建UI ===
==== 打开Laya工程 ====
使用指定版本的Laya编辑器打开 `demo/ui_laya/ui_laya.laya` 项目。

==== 添加.scene界面 ====
在编辑器中，可以添加一个新的scene界面，并在其上放置UI元素。

[[File:新界面.png]]

==== 界面添加UI组件 ====
例如，添加一个名为 `btnFirst` 的按钮，并确保其 `var` 属性有值，以便后续导出。

[[File:UI按钮有值.png]]

添加后，记得保存，'''ctrl+S'''

=== 额外资源的添加 ===

注意，所有上述scene中用到的美术资源，必须放在Assets/uiextra/ 目录下

否则导出ui时会失败

=== 运行生成UI命令 ===
在命令行中运行以下命令来生成UI代码：

<pre>
npm run ui
</pre>

运行成功后，生成的UI类将位于 `src/ui/popxMaxUI.ts` 文件中。

[[File:UI生成代码.png]]

其中，添加了一个和scene名相同的UI类，
并且，var有值的组件也一起生成了对应属性。

=== 修改后的资源，git上传到远端 ===

上传后，泡饭即可使用

先git commit提交
注意推送时要用如下命令

git push --force

如果弹出输入框，账号输入泡饭账号名，密码输入accesstoken

[[File:新泡饭推送到远端.png]]

=== 代码控制XUIComponent ===
==== 注册UI类的控制文件 ====
使用 `PopxBridge.regUIClass()` 方法在相应的类中注册UI类，并处理UI相关的按键逻辑。
<pre>
//注册自定义的ui类
PopxBridge.regUIClass(DemoUI.getClassName(), DemoUI);
</pre>

以下是我们新加UI的最基础代码，在界面显示的时候，注册点击事件，点击后打印日志
<pre>
export class DemoUI extends uiextra.demoUIUI{

constructor(){
super();
}

onAwake(): void {

}

onEnable(): void {
// 设置在顶层可以被点击
this.zOrder = 1;
this.first_btn.on(XEvent.CLICK, this, this.onClickFirstBtn);
}

private onClickFirstBtn(e:XEvent){
console.log("click first btn");
}
}
</pre>

==== 代码调用显示UI ====
通过 `xUiManager.instance.openUI()` 方法来调用并显示UI界面。
<pre>
// 加载对应的json文件路径，并挂载在指定父节点上
XUiManager.instance.openUI('res-extra/ui/demoUI', XPopManager.rootNode);
</pre>

-编译，运行

[[File:UI点击按钮.png]]

==== 代码调用加载组件 ====
*某些界面上的元素，比如卡牌，也可以类似做成一个scene，运行npm run ui 自动生成类
*比如类名为CardView
*注册和UI注册类似
<pre>
PopxBridge.regUIClass(CardView.getClassName(), CardView);
</pre>
*创建时，调用`XUiManager.instance.createView`
<pre>
XUiManager.instance.createView(path,parent,this.onLoadCardView,showData);

onLoadCardView(view:XUIComponent)
{
}
</pre>

== 前后端数据交互 ==

该篇会讲述服务器和前端的数据同步，如果想要先了解项目目录和工作流，建议先参考如下篇幅
[[#主要工程目录]]

=== 进入房间（游戏世界） ===
如下是最基本的开发登录流程说明
{| class="wikitable"
|-
! 步骤
! 描述
! 流向
|-
| 开始
| 流程的开始
| -> 登录页面
|-
| 登录页面
| 账号密码，选定地图，输入房间号（可不填）
| -> 远端服务器（官方）
|-
| 远端服务器（官方）
| 获取玩家账户信息，分配到房间,房间就是我们的host代码
| -> Client 和 -> Host
|-
| Client
| 监听XPopManager.onGameStart
| -> 前端逻辑开始
|-
| Host
| 监听XPopManager.onHostStart
| -> 房间战斗逻辑开始

|}

远端服务器(官方)会处理最基本的登录，分配房间，创建游戏世界的逻辑，并且同步该世界中的游戏数据。

通过'''XpopManager'''管理类，来向Client和Host抛出事件，开发者可以监听这些事件做处理。

开发者需要关心的逻辑，就是Clint和Server（上图中Host）目录下的代码。

=== 前后端协议交互 ===
项目采用proto来做相互通信，建议参考如下篇幅 [[#npm run proto（协议通信）]]

=== 前后端共用配置 ===
前端'''src/client'''目录和后端'''src/server'''目录中，都可以调用如下代码来加载所有的表格配置
<pre>
CsvManager.ins.loadCsvs(this, () => {
// Do some thing after load
});
</pre>

表格的加载逻辑和解析逻辑，可以参考CsvManager中的代码
'''src/shared/csv/CsvManager.ts'''

''如何新增配置?''
以demo中的'''item.csv'''为例.
*1.配置csv文件资源的根目录为'''res-extra/csv/''' ,在里面添加'''item.csv'''
*2.'''CsvManager.ts'''文件中，添加读取表格和解析表格的逻辑
<pre>
// loadCsvs代码中，添加你需要解析的csv名称
public loadCsvs(caller: any = null, listener: Function = null) {
let assets = [
this._prefix + "item.csv",
];
// XResManager加载本地资源
XResManager.instance.loadText(assets, () => {
// 在加载完成的回调中，处理表格数据结构，生成CItemData，不再赘述
this.onCompleted(caller, listener);
});
}
</pre>
*3.解析表格得到的'''CItemData'''结构，定义在'''src/shared/dataMgr/'''中，可以被前后端一起调用
*4.如果是加载json文件，用'''XResManager.instance.loadText'''

=== 玩家战斗数据快照 ===
游戏战斗服务器中，每个玩家的实时信息，通过快照来更新
==== XVF_SnapData ====
以demo中的'''Snap_UserData.ts'''为例
*该玩家数据中类中，包含的各种public变量，都是''XVF_SnapData''接口类型
<pre>
export class Snap_UserData {
//坐标旋转
public position: XVF_SnapData<SyncPos>;
//状态
public state: XVF_SnapData<SyncState>;
//hp
public hp: XVF_SnapData<number>;
}
</pre>
快照类型数据，前端负责注册和监听，服务器负责修改
*每次该接口类型的数据发生变化时，会调用OnSet方法，这类数据的修改逻辑是：服务器修改，前端监听变化
** 前端登录成功后，服务器注册对应玩家数据
** 前端对数据中的某个XVF_SnapData做监听，注册OnSet方法
** 服务器战斗逻辑修改了该数据时，前端根据OnSet的逻辑做表现处理

服务器先注册全局的快照
<pre>
let userData = new Snap_UserData();
XPopManager.instance.xHost.RegisterSnapshot(`UserData${i}`, userData);
</pre>

前端绑定同一个地址的快照
<pre>
this._userData = new Snap_UserData();
XPopManager.instance.xRemote.RegisterSnapshot(`UserData${index}`, this._userData);
</pre>

*XVF_SnapData数据，如果是复杂类型，需要调用UpdateData()方法，前端才能触发OnSet
如下的SyncState就是复杂类型
<pre>
public state: XVF_SnapData<SyncState>;
public setState(key:string, obj:string):void{
this.state.value.key = key;
this.state.value.obj = obj;
this.state.UpdateData();
}
</pre>
*XVF_SnapData如果是基础类型，不需要调用UpdateData()
<pre>
public hp: XVF_SnapData<number>;
public setHP(hp:number):void {
this.hp.value = hp;
}
</pre>

=== 代码如何调试 ===
==== 前端调试 ====
直接在vscode中打断点即可，
可以很方便的观察堆栈和变量信息

[[File:前端调试.png]]

==== 本地服务器调试 ====
*本地服务器在调用命令'''npm run server'''后，会启动一个Host网页
*只要是网页，那就能调试js代码
*打开网页的开发者工具（一般浏览器是f12）,找到'''index.js'''文件
*这时有个问题，发现打不了断点，原因是代码编译过程被混淆了

[[File:服务器调试一.png]]

*我们需要关闭混淆的配置，在'''rollup.config.js'''中修改

[[File:服务器调试二.png]]

*修改plugins中，关闭sourcemap，不使用terser()压缩

[[File:服务器调试三.png]]

*修改完后，每次编译后运行的服务器Host代码就都可以断点了

编译，启动服务器，运行
<pre>
npm run build
npm run server
</pre>

*这次会发现，Host的网页代码有了行号，可以断点调试了

[[File:服务器调试四.png]]
==== 调试注意事项 ====
*每次'''npm run build'''后，如果修改了服务器代码，可以在本地host的浏览器里，立刻刷新，F5或者shift+f5
*如果修改了编译脚本来调试服务器，记得最后打包上传前，把rollup的代码改回来

== 地图的制作和选取 ==
=== 地图官网地址 ===
*[[上传流程|地图编辑器页签可以操作]]

=== 地图制作导出 ===
在项目目录'''/地图编辑器操作说明'''中，有视频教程

[[File:地图编辑视频.png]]

=== 开发环境选择地图 ===
我们在登录界面，可以通过填写你gameid中的地图名字，来进入指定地图。

所以必须要先创建gameid，并且选择至少一张地图，该地图才能在调试时进入。

举例：

*上传地图到某个游戏gameid时，会从你自己的'''可用地图'''中选择。

- 可用地图指的是你自己制作上传了地图。或者其他人共享给了你地图。

*比如你的可用地图名字是"推箱子"。

*右边会有可填写的自定义地图名字，比如"第一关"

那么登录的时候就是填写 "第一关"

*'''也就是说，地图做完后，必须要在审核平台上，添加到玩法里，生成自定义的名字，才可以在测试时填写进去生效 '''

== 打包与上传 ==

[[File:泡饭点击发布游戏.png]]

点击发布后，会把构建生成的压缩包上传到远端，就可以去试玩了。

=== 玩法测试 ===

[[File:泡饭点击打开审核后台.png]]

* [[上传流程|查看文档中试玩/审核/发布的部分]]

== 项目目录 ==

=== 主要工程目录 ===
对于开发者，需要关心和操作的目录如下：

* '''node_modules/''' - 通过npm安装的PGC库文件，对外暴露的方法，可以通过bridge.d.ts来外部引用
* '''res-extra/''' - 开发者除了PGC的远程资源外，需要额外使用到的资源目录，比如UI，图片，音频，表格，最后会打包上传到PGC远端资源服务器
* '''ui/''' - 开发者自己在laya编辑器中，拼接的界面json文件，运行命令后，会转化为PGT指定的XUIComponent存放于此
* '''src/''' - 开发者所有的战斗逻辑代码修改都在此进行
* '''src/client/''' - 前端代码，入口文件index.ts，监听XPopManager.onGameStart，前端游戏逻辑
* '''src/server/''' - 后端代码，入口文件index.ts，监听XPopManager.onHostStart，后端游戏逻辑
* '''src/shared/''' - 前后端共用的数据结构，包括表格，协议，玩家数据
* '''dist/''' - 编译后，生成的运行文件，包含前后端代码
* '''dist/client/''' - 编译后生成的混淆的前端代码
* '''dist/host/''' - 编译后服务端的代码文件，里面也包括表格数据的缓存

=== 前后端协议通信生成 ===

[[File:泡饭点击生成协议.png]]

==== 协议通信 ====
该命令会用到tsrpc的proto协议，
把'''src/shared/protocols'''下的指定格式文件，
转换到'''src/shared/protocols/generated/serviceProto'''文件中，

* 文件名为：Ptl{接口名}.ts '''（Ptl 是 Protocol 的缩写，l是小写的L）'''
* 请求类型名为： Req{接口名}，通过 interface 或 type 定义，需 export
* 响应类型名为：Res{接口名}，通过 interface 或 type 定义，需 export

例如，添加'''PtlPosition.ts'''文件
文件代码如下
<pre>
// 该接口用于向服务器同步自身的坐标
export interface ReqPosition {
i: number;
x: number;
y: number;
z: number;
ry: number;
}
export interface ResPosition {
ret: string;
diy: string;
}
</pre>

'''serviceProto.ts'''中会增加可外部调用的api类型
<pre>
export interface ServiceType {
api: {
"Position": {
req: ReqPosition,
res: ResPosition
},
},
msg: {

}
}
</pre>

'''前端代码调用请求'''
<pre>
// 前端可以用promise语法来调用同步位置的Request，异步处理服务器的返回值
let remote = XPopManager.instance.xRemote;
let ret = await remote.Request('Position', {i: 1, x:2, y:3, z:4, ry:5});
if(ret && ret.isSucc){
console.log(ret.res.diy)
}
</pre>

'''后端代码监听请求处理返回'''
<pre>
// 服务器收到前端请求的处理返回RegisterRpc
let host = XPopManager.instance.xHost;
//当收到坐标变化请求
host.RegisterRpc("Position", async (call: ApiCall<ReqPosition, ResPosition>) => {
let index = call.req.i;
let userData = this.usersData.get(index);
userData.setPosition(call.req.x, call.req.y, call.req.z, call.req.ry);
return call.succ({
ret: "Success",
diy: "自定义参数"
});
});
</pre>
如果想更多了解proto的结构和数据类型说明，可以参考官方链接
[tsrpc-proto格式说明](https://tsrpc.cn/docs/server/service-proto.html)

== 核心类目说明 ==
=== XPopManager ===
Bridge.d.ts中的核心类

对游戏逻辑进行了结构化的拆封和管理，

可以理解为，

库文件内处理了各种玩家的逻辑，比如登录，加载地图，分配房间，快照数据同步等等,然后关键的几个节点，暴露给外部去执行游戏逻辑。

开发者只需要去编写独立游戏模块的代码，其中，'''Xremote'''暴露给前端处理，'''Xhost'''暴露给后端处理

下面是最重要的几个生命周期函数
;onGameStart:玩家已经完成了登录步骤，已经分配好了房间，通知前端游戏开始
;onHostStart:玩家已经完成了登录步骤，已经分配好了房间，通知后端游戏开始
;onGameOver:游戏结束（一般是玩家都离开了战斗房间）
;onUpdate:每一帧会调用更新

我们在demo中，index.ts里，可以给这几个方法监听绑定函数，输出日志就可以查看

<pre>
XPopManager.onGameStart = ()=>{
new Main();
console.log("qc,XPopManager.onGameStart");
}

XPopManager.onGameOver = () => {
console.log("qc,XPopManager.onGameOver");
}

XPopManager.onHostStart = () => {
console.log("qc,XPopManager.onHostStart");
}

XPopManager.onUpdate = () => {
console.log("XPopManager.onUpdate");
}
</pre>

[[File:XPopManager生命周期.png]]

=== XRemote(前端) ===
*以下是最关键的生命周期和方法调用，调用逻辑可以自定义设计，后端代码同理
;UserID:玩家进入游戏的唯一id
;onUserEnter:每当房间内玩家进入时会调用，前端可以在此根据返回的userId来同步XHost玩家的快照数据，创建角色等等
;onUserLeave:每当房间内玩家离开时会调用，前端根据userId来处理模型的销毁
;RegisterSnapshot:用于注册绑定快照，快照类型开发者自定义，需要和XHost代码中绑定的地址一致，才可以收到OnSet回调
;Request:发送RPC请求，请求和回调的代码由protocol生成

=== XHost(后端) ===
;onUserEnter:每当房间内玩家进入时会调用，初始化玩家身上的快照数据，可以根据人数来判断游戏阶段，比如准备阶段
;onUserLeave:每当房间内玩家离开时会调用，清理玩家数据，可以根据玩家人数来判断是否进入结算或者游戏结束
;RegisterSnapshot:用于注册绑定快照，快照类型开发者自定义，需要和XRemote代码中绑定的地址一致
;RegisterRpc:注册RPC回调

=== XUIComponent(UI组件) ===
UI组件通过XUiManager.instance.OpenUI或者XUiManager.instance.CreateView加载显示
;showUI:调用后会设置active为true，当调用创建的方法，加载成功显示时也会调用一次，可以在创建时传参，每次主动调用也可以传参。
;hideUI:把该组件的active设置成false
;closeUI:把该组件从父节点移除，可以传参处理移除成功时的回调
=== XEventDispatcher(事件)===
我们可以根据已有的XEventDispatcher来封装一个单例，这样就能外部夸文件调用事件了。
如下为演示封装的单例
<pre>
export class EventManager extends XEventDispatcher{

constructor () {
super();
}

private static _instance: EventManager
public static get instance(): EventManager {
if (!this._instance) { this._instance = new EventManager(); }
return this._instance;
}

}
</pre>

事件的派发
<pre>
EventManager.instance.dispatch("new_event_name", ...args);
</pre>

事件的监听
<pre>
EventManager.instance.add("new_event_name", this, this.ParseNewEvent);

private ParseNewEvent(...args)
{
console.log("parse new event")
}
</pre>

== 常见工作流问题 ==
=== 如何把本地的项目上传到泡饭 ===
==== 建议先上传项目到自己的git仓库 ====
==== 从git拉取 ====

点击图中创建模板按钮，从git创建工程

[[File:点击从git创建工程.png]]

[[File:git项目地址.png]]

== 官方论坛 ==
*[论坛地址](https://bbs.popx.com/)
*可以由我们内部人员给出的邀请链接申请加入论坛。
*申请后，等待审核人员核实，批准后，即可浏览论坛内容，发表疑问贴。
*强烈建议多去论坛搜索关键字，发帖会有对应的专业人员回答问题，大家一起维护论坛生态。
*常见问题faq帖子会持续维护

[论坛FAQ](https://bbs.popx.com/t/topic/53)

文件:点击从git创建工程.png

2025-02-10T08:56:25Z

Liuweichen：

泡饭工坊

2025-02-10T08:56:04Z

Liuweichen：/* 从git拉取 */

== 泡饭工坊介绍 ==
===泡饭工坊是什么？===
泡饭是一套网页虚拟环境下的代码编辑工具，内嵌了多种预设和模板，集成了vscode来编辑代码，自动编译，可以方便的预览和分享给小伙伴体验。
=== 泡饭链接 ===
[链接](https://webdev.popx.com)

=== 泡饭账号登录 ===
目前支持自定义账号，记住账号密码即可，后续会优化。

== 用模板开发代码 ==
模板是泡饭的核心功能，开发者既可以快速预览学习模板的代码，又可以自己上传模板

=== 模板仓库创建工程 ===

[模板商店创建工程]
[模板商店]

=== 模板上传 ===

[模板上传设置]

=== 模板成员 ===

== 用git开发代码 ==

=== 从git拉取 ===

点击图中创建模板按钮，从git创建工程

[[File:点击从git创建工程.png]]

[[File:git项目地址.png]]

=== 上传到git ===

=== git冲突解决 ===

=== git代码上传到模板 ===

== 模板的商业化支持 ==

=== 设置公有代码 ===

=== 设置私有代码 ===

=== 代码引用的赞赏和收费 ===

== 编码操作 ==

=== 内置vscode ===

=== 导入本地文件 ===

单个文件

文件夹

=== 代码引用和注释 ===

=== 编码快捷键操作 ===

=== 自动编译 ===

=== 调试和断点 ===

== 适配PGC项目 ==

=== package.json设置 ===

==== sdk版本 ====
==== 资源版本 ====
==== 游戏id和key ====
==== 第三方包支持 ====

=== 启动模式和参数 ===

==== 大厅 ====
==== 单机 ====
==== 服务器 ====

=== 分享游戏链接 ===

=== 内置工具 ===

==== 模型查看器 ====
==== 开发者后台 ====
==== 快捷键修改 ====

=== 帮助文档支持 ===

==== 官方开发文档 ====

==== 论坛生态 ====

泡饭工坊项目流程

2025-01-17T10:42:46Z

Liuweichen：/* 多人合作冲突的解决 */

== 泡饭工坊介绍 ==
===泡饭工坊是什么？===
泡饭是一套网页虚拟环境下的代码编辑工具，内嵌了多种预设和模板，集成了vscode来编辑代码，自动编译，可以方便的预览和分享给小伙伴体验。
=== 泡饭链接 ===
[链接](https://webdev.popx.com)

=== 泡饭账号注册登录 ===

==== 没账号的需要在泡饭注册账号 ====

[[File:新注册账号手机号.png]]

'''请记住您的账号密码，这关系到后续我们管理您的使用权限'''

==== 和我们内部人员沟通，申请后台权限 ====

'''如需开通后台使用权限，将您的账号告知我们内部人员帮操作，等待通知完成后，重新刷新网页即可'''

==== 第一次需要创建一个工程 ====

[[File:新点击模板商店创建模板.png]]

[[File:新模板下载.png]]

[[File:新下载工程.png]]

==== 有了工程后，打开工程 ====

[[File:新打开我的工程.png]]

== 打开泡饭体验项目 ==

参考视频[1.泡饭运行环境演示.mp4]

== 如何用泡饭开发自己的项目 ==

=== 点击跳转后台 ===

===='''就第一次需要创建打开一个工程，才能出现地图编辑器的跳转页面''' ====

[[File:新跳转后台.png]]

=== 后台创建游戏，绑定地图 ===
* 需要泡饭跳转到后台，去新建游戏，生成独属于你的gameid和secret，这在后续的开发和上传时至关重要，请点击下方超链接，去参考其中新建gameid的部分
* [[上传流程|请看该链接中，新建游戏玩法的部分]]

=== 修改package.json进入自己的游戏和地图 ===
- 点击左侧修改配置按钮
[[File:新点击修改配置.png]]
- gameid 开发者后台中指定的游戏玩法
- secretkey 游戏玩法对应的密钥
- defaultMap 游戏玩法中，指定的地图，请在后台至少指定一张，默认填写"地图_0"
- sdkVersion sdk版本号，点击修改可以弹出下拉框，一般选用release标签的稳定版本，修改后，会去修改对应的bridge依赖，并且下载
- resVersion 美术资源版本号，会影响游戏内地图和模型的显示，一般选用最新的版本即可

=== 首次运行需要先发布 ===

当前的gameid是最新的，

目前后台服务器还没有一个初始版本的记录，所以需要在package.json中，修改完gameid之后。

首次运行要发布游戏（后续不需要每次发布，直接保存就可以编译调试）。

[[File:泡饭点击发布游戏.png]]

等待右上脚提示发布完成，即可启动进入游戏

=== 启动项目 ===

一般选用启动游戏（服务器模式）

[[File:新泡饭点击启动游戏.png]]

==== 登录界面 ====
- 运行后，浏览器将显示登陆界面。
[[File:默认地图.png]]
- 账号密码随便输入，会创建新账号
- 输入账号密码后，选择指定地图（可选），即可看到战斗服务器世界中有自己的人物。
- 默认的demo工程中，如果没有修改gameid和secretKey，地图请填写"地图_0"

== 泡饭模板的多人合作 ==

=== 发布模板 ===

[[File:发布工程多人合作.png]]

设置团队成员权限和名称

[[File:设置团队成员权限.png]]

=== 发布后管理项目 ===

发布后可以在商店模板里去修改自己发布的项目。

[[File:发布后编辑模板权限.png]]

=== 其他成员就可以在模板商店拉取模板了 ===

比如上图中的playername1的账号，就可以拉取模板了

=== 打开项目 ===

点击编辑按钮，切换到vscode运行环境。

[[File:点击编辑按钮切换vscode.png]]

=== 团队成员修改提交 ===

我们尝试写第一行代码提交下

[[File:写第一行代码.png]]

[[File:模板内git_commit.png]]

具体在vscode中，怎么使用git来提交和拉取，可以参考如下文档

[vscode使用git插件](https://blog.csdn.net/khhmd/article/details/144131405)

=== 多人合作冲突的解决(遇到冲突再看，可以先跳过) ===
==== 选择远端的master分支来merge ====

[[File:git冲突merge.png]]

[[File:gitmerge选择远端.png]]

==== 根据需求去修改冲突文件 ====

[[File:git冲突文件解决.png]]

==== 冲突文件修改完成，resolve ====
[[File:git冲突保存.png]]
[[File:解决冲突完成.png]]

==== 同步到远端 ====

[[File:gitmerge同步到远端.png]]

== 前端基础逻辑 ==

根据以下步骤，一步步进入泡泡的游戏世界，即使你是新手也无需担心。

=== 前端游戏入口 ===
- '''/src/client/index.ts''' 文件中的 `XPopManager.onGameStart` 是前端的主要入口点。

=== 创建第一个人物 ===
在 `simpleGame` 类中，我们将创建并初始化第一个游戏人物。

<pre>
export class simpleGame {
private firstModel: XModelHero;

constructor() {
// 创建第一个人物
this.firstModel = new XModelHero();
let path = 'role/model_avatar_body_default';

// 加载人物模型并播放动画
this.firstModel.loadModel(path, null, this, (success) => {
// 播放跑步动画
let actName = "act_avatar_base_run";
this.firstModel.playAniUp(`${actName}_up`);
this.firstModel.playAniDown(`${actName}_down`);

// 摄像机跟随
let camera = XPopManager.instance.xScene.camera;
camera.focus = this.firstModel;

// 定时更新人物位置
XTimer.loop(100, this, this.updateModelPos.bind(this));
});
}

updateModelPos(delta: number, frame?: string) {
// 更新人物位置
this.firstModel.position.x += 0.1;
}
}

// 设置游戏启动时执行
XPopManager.onGameStart = () => {
new simpleGame();
}
</pre>

*注意：请将原代码中的 '''new Main()''' 替换为 '''new simpleGame()''';
上述的代码我们以最简单的方式，去掉一切服务器交互，添加一个基础模型到游戏中跑动

再提醒一次，每次有代码修改后，运行前需调用命令进行编译
[[#编译]]

=== 播放人物的动作 ===
我们的人物有上下半身，在知道动画名字的情况下，需要分上下半身来播放动画

以'act_avatar_plant_collect'为例

<pre>
let animbaseStr = 'act_avatar_plant_collect';
role.model.playAniUp(`${animbaseStr}_up`);
role.model.playAniDown(`${animbaseStr}_down`);
</pre>

那么如何快速查看已有哪些动画呢？

[动作查看器](https://webdev.popx.com/v1/game/client_host.html?author=qc_jump&project=resourceviewer_0926&diyserver=1&gameid=0bkyyeesxnzsrd9s&editorFormal=true)

=== 添加按键控制 ===
看demo中的代码，提供了一个MoveComponent类
摇杆的显示资源放在'''res-extra'''目录中

[[File:摇杆资源.png]]

以下是示例中添加摇杆控制的代码
<pre>
//摇杆背景
let rocker = new XImage('res-extra/imgs/stick_bg.png');
rocker.width = rocker.height = 164;
rocker.pivotX = rocker.pivotY = 82;
rocker.pos(178, -198);
leftbottom.addChild(rocker);
//摇杆方向
let imgdir = new XImage('res-extra/imgs/stick_dir.png');
imgdir.centerX = imgdir.centerY = 0;
imgdir.anchorX = imgdir.anchorY = 0.5;
imgdir.name = "dir";
rocker.addChild(imgdir);
//摇杆中心点
let node = new XImage('res-extra/imgs/stick_rocker.png');
node.centerX = node.centerY = 0;
node.anchorX = node.anchorY = 0.5;
node.name = "node";
rocker.addChild(node);
//移动
let hero = this.heros.get(this.roleIndex);
if (hero) {
let movecomponent = rocker.addComponent(MoveComponent) as MoveComponent;
movecomponent.init(hero, ctrlayer, rocker);
}
</pre>

示例中，添加了一个触摸区域挂载在根节点的左下角，触摸反馈会根据'''XEvent'''来传递给节点
代码中根据摇杆方向变化来控制人物移动
其中涉及了部分修改玩家状态的服务器代码，可以先忽略

=== 摄像机的跟随 ===
代码中，摄像机跟随人物移动，只需要简单的一行
<pre>
let hero = new Xmodel();
//这是全局的摄像机
XPopManager.instance.xScene.camera.focus = hero;
</pre>

摄像机的旋转视角，demo中也提供了一个类'''CameraComponent'''
和摇杆的节点类似，通过'''XEvent'''来传递点击事件，
根据点击事件的拖动，来修改摄像机的旋转视角 '''xcamera.rotate'''
<pre>
private onCtrlMouseMove(e: XEvent): void {
if(this._touchId != e.touchId) return;
let xcamera = XPopManager.instance.xScene.camera as XCamera;
if(!xcamera)return;
if(this._mouseX == 0) this._mouseX = e.stageX;
if(this._mouseY == 0) this._mouseY = e.stageY;
let offx = e.stageX-this._mouseX;
let offy = e.stageY-this._mouseY;
this._mouseX = e.stageX;
this._mouseY = e.stageY;
xcamera.rotate(offx, offy);
}
</pre>
=== 砖块说明 ===
[[File:砖块说明.png]]

如图所示，我们的世界地图由若干个方形大'''地块'''组成，

每个地块里，可以划分成32*32的平面坐标，一层层叠高，可以有64层高，

转化为三维坐标系就是32*64*32，对应xyz轴，

地块上，可以添加以坐标为单位的'''砖块'''。

其中，cubeId表示砖块的类型，比如草地就是id为1的砖块，该砖块具有可以踩踏行走的特性。

某些其他的砖块具有别的特性，都通过cubeid来区分，当开发者接触地图编辑器时，就会有所了解。

我们以Demo中，'''MoveComponent'''中的一段代码来参考
<pre>
// 游戏世界地图
let scene = XPopManager.instance.xScene;
// 判断水平方向是否有砖块
// 根据坐标位置，找到世界中，其坐标对应的砖块id
let cubeid = scene.getCube(dir.x ,position.y, dir.z)
if(cubeid){
// 根据砖块id，找到砖块的类型，判断其是否和人物碰撞阻挡
scene.getCubeInfo(cubeid, this.cubeInfo);
if(this.cubeInfo.collisionPlayer){
dir.x = position.x;
dir.z = position.z;
}
}
//如果没有砖块或者有无阻挡砖块，给一个向下的位移
cubeid = scene.getCube(dir.x ,position.y-0.1, dir.z)
if(cubeid){
scene.getCubeInfo(cubeid, this.cubeInfo);
if(!this.cubeInfo.collisionPlayer){
dir.y = position.y-0.1;
}
}else{
dir.y = position.y-0.1;
}
</pre>

*再以图中为例，v3的坐标代表了地图上的位置，(24,3,26)
*如果需要设置模型在地图上的位置，用如下代码
<pre>
let pos = new XVector3(x,y,z);
xModel.position = pos;
</pre>

== 资源加载说明 ==

=== 演示加载图片 ===
<pre>
// 测试加载图片
// 创建一个全屏的挂载UI层
let mainui = new XImage();
mainui.left = mainui.right = mainui.top = mainui.bottom = 0;
XPopManager.rootNode.addChild(mainui);

// 图片路径，如果是本地的额外资源，就加上"res-extra/"前缀，否则就是远端资源
let path = 'avatarstart/ball_btn2.png';
// 创建图片
let img = new XImage(path);
// 添加到父节点显示
mainui.addChild(img);
// 设置位置
img.left = img.top = 100;
</pre>

编译，运行后，可以看到，添加了指定的图片

[[File:资源加载一.png]]

=== 公共资源 ===
PGT为开发者提供了很多基础的图片，模型，音频等等的资源。

====怎么查看有哪些公共资源呢？====

*打开项目目录下的package.json文件

[[File:资源加载二.png]]

===== 有sdkVersion =====
*调用查看当前的远端sdk版本，即资源版本，比如"sdkVersion": "1.0.15",
*具体有哪些资源版本可用，可以调用'''npm run sdklist '''来查看
*把下面链接里的v1.0.16替换成和你目前版本一致的数字，就可以查看远端资源列表

[[File:sdkVersion.png]]

[远端文件列表json](https://h5ppreview.jumpw.com/popion/sdk/v1.0.16/version.json)

===== sdkVersion>1.2.60的版本 =====

同样是查看pacakge.json，但是字段换成了"resVersion": "1.0.5"

resVersion

如下是1.0.5版本的资源列表，可以修改数字查找不同版本

[远端文件列表json](https://h5ppreview.jumpw.com/popion/popx-res/version-1.0.5.json)

也可以用命令来查找显示不同的资源版本

'''查看资源版本列表'''：npm run reslist (只包含正式发布的版本)

'''查看所有资源版本列表'''：npm run reslistall

===== 查看json文件 =====

*json文件左侧是游戏内加载的路径，右侧是实际的打过md5值的网络路径

[[File:资源加载四.png]]

这就是我们刚刚演示的加载图片

''avatarstart/ball_btn2.png": "avatarstart/ball_btn2-2c717f83a3.png''

*游戏内我们通过加载接口去加载左侧路径
*游戏外，直接在刚刚的cdnUrl后拼接带md5值的完整路径即可查看

[查看网络资源](https://h5ppreview.jumpw.com/popion/sdk/v1.0.17/avatarstart/ball_btn2-2c717f83a3.png)

[[File:资源加载五.png]]

*音频文件同理，模型文件直接游戏内调用接口显示

=== 额外资源 ===
最基础的demo中，会看到用于演示的摇杆资源是放在'''res-extra'''目录下的。

一般来说，开发者的一些特制UI，图形，可以放在这里。

加载时在路径前加上"res-extra/"即可。

*注意，额外资源调用前，要调用如下固定代码开启合图资源的配置，建议参考demo，在游戏入口就初始化调用一次
<pre>
XResManager.instance.enableAtlas("res-extra/fileconfig.json",()=>{
// 可以调用额外资源了
});
</pre>

每次在调用命令，npm run ui时，会更新上述的'''fileconfig.json'''文件。

[[#npm run ui ( 生成ui类 )]]

==== npm run ui ( 生成ui类 ) ====
如果开发者有额外的ui交互需求，希望在IDE中自己拼接UI
可以在指定目录下，
* '''ui_laya/laya/''' - 开发者可以自由扩展的ui资源目录
* '''ui_laya/laya/pages''' - 开发者创建的.scene文件目录
* '''ui_laya/laya/assets/uiextra''' - secne文件中引用到的各种美术资源，包括音频和动画

-运行后，会在client目录代码中，生成对应的XUIComponent类，[[#XUIComponent]]

-运行后，会更新'''res-extra'''文件夹下的fileconfig.json

*注意，我们目前不支持第三方模型文件，模型必须提交审核，不放在res-extra中

=== 模型查看器 ===
*除了图片资源外，为了方便开发者使用，我们额外做了一个模型查看器

[公共模型查看器](https://webdev.popx.com/client_host.html?author=qc_jump&project=resourceviewer_0926&diyserver=1&gameid=09kyye6gcmmda79s&editorFormal=true)

== UI界面开发 ==

=== git拉取ui工程到本地 ===

==== 泡饭的项目发布后获取到了git地址 ====
[[File:发布模板后获得git地址.png]]

==== 查看git密钥 ====

[[File:查看git密钥.png]]

==== 使用accesstoken来拉取项目到本地 ====

===== 常见的git工具中=====

git clone 地址

输入泡饭账号和accesstoken即可拉取，注意不是泡饭的密码，是token

===== 没有工具时用命令拉取说明=====

[[File:如何使用accesstoken拉取.png]]

=== 安装本地ui的编辑环境 ===

==== laya 版本 v2.13.1 ====
- [laya官方ide](https://ldc2.layabox.com/layadownload/?type=layaairide-LayaAir%20IDE%202.13.1)

==== 安装项目自定义封装的cmd命令库 ====
- 推荐安装方式：
<pre>
npm i popxcmd -g --registry https://registry.popx.com
</pre>

==== node 版本 v10.24.1 ====
- 必须使用指定的nodejs版本 ，推荐安装nvm以自由转换node版本。
- [nvm下载及安装方式](https://blog.csdn.net/ppz8823/article/details/130862191)

*记得nvm需要换源，否则后续安装可能会出错，按照下述操作

[[File:nvm换源.png]]

*最下面两行修改node和npm的镜像地址
<pre>
node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/
</pre>

*安装nvm后，命令行运行如下命令切换到node版本v10.24.1，一步步来:
<pre>
// 安装
nvm install 10.24.1
// 等待安装完成后，切换
nvm use 10.24.1
</pre>

*nodejs也需要用下面的命令来换源，修改镜像地址
<pre>
npm config set registry https://registry.popx.com/
</pre>

==== 修改host文件 ====
- 找到host文件，一般在`C:\WINDOWS\system32\drivers\etc`目录下。
- 在文件末尾添加：
<pre>
199.232.68.133 raw.githubusercontent.com
</pre>

=== 在编辑器中创建UI ===
==== 打开Laya工程 ====
使用指定版本的Laya编辑器打开 `demo/ui_laya/ui_laya.laya` 项目。

==== 添加.scene界面 ====
在编辑器中，可以添加一个新的scene界面，并在其上放置UI元素。

[[File:新界面.png]]

==== 界面添加UI组件 ====
例如，添加一个名为 `btnFirst` 的按钮，并确保其 `var` 属性有值，以便后续导出。

[[File:UI按钮有值.png]]

添加后，记得保存，'''ctrl+S'''

=== 额外资源的添加 ===

注意，所有上述scene中用到的美术资源，必须放在Assets/uiextra/ 目录下

否则导出ui时会失败

=== 运行生成UI命令 ===
在命令行中运行以下命令来生成UI代码：

<pre>
npm run ui
</pre>

运行成功后，生成的UI类将位于 `src/ui/popxMaxUI.ts` 文件中。

[[File:UI生成代码.png]]

其中，添加了一个和scene名相同的UI类，
并且，var有值的组件也一起生成了对应属性。

=== 修改后的资源，git上传到远端 ===

上传后，泡饭即可使用

先git commit提交
注意推送时要用如下命令

git push --force

如果弹出输入框，账号输入泡饭账号名，密码输入accesstoken

[[File:新泡饭推送到远端.png]]

=== 代码控制XUIComponent ===
==== 注册UI类的控制文件 ====
使用 `PopxBridge.regUIClass()` 方法在相应的类中注册UI类，并处理UI相关的按键逻辑。
<pre>
//注册自定义的ui类
PopxBridge.regUIClass(DemoUI.getClassName(), DemoUI);
</pre>

以下是我们新加UI的最基础代码，在界面显示的时候，注册点击事件，点击后打印日志
<pre>
export class DemoUI extends uiextra.demoUIUI{

constructor(){
super();
}

onAwake(): void {

}

onEnable(): void {
// 设置在顶层可以被点击
this.zOrder = 1;
this.first_btn.on(XEvent.CLICK, this, this.onClickFirstBtn);
}

private onClickFirstBtn(e:XEvent){
console.log("click first btn");
}
}
</pre>

==== 代码调用显示UI ====
通过 `xUiManager.instance.openUI()` 方法来调用并显示UI界面。
<pre>
// 加载对应的json文件路径，并挂载在指定父节点上
XUiManager.instance.openUI('res-extra/ui/demoUI', XPopManager.rootNode);
</pre>

-编译，运行

[[File:UI点击按钮.png]]

==== 代码调用加载组件 ====
*某些界面上的元素，比如卡牌，也可以类似做成一个scene，运行npm run ui 自动生成类
*比如类名为CardView
*注册和UI注册类似
<pre>
PopxBridge.regUIClass(CardView.getClassName(), CardView);
</pre>
*创建时，调用`XUiManager.instance.createView`
<pre>
XUiManager.instance.createView(path,parent,this.onLoadCardView,showData);

onLoadCardView(view:XUIComponent)
{
}
</pre>

== 前后端数据交互 ==

该篇会讲述服务器和前端的数据同步，如果想要先了解项目目录和工作流，建议先参考如下篇幅
[[#主要工程目录]]

=== 进入房间（游戏世界） ===
如下是最基本的开发登录流程说明
{| class="wikitable"
|-
! 步骤
! 描述
! 流向
|-
| 开始
| 流程的开始
| -> 登录页面
|-
| 登录页面
| 账号密码，选定地图，输入房间号（可不填）
| -> 远端服务器（官方）
|-
| 远端服务器（官方）
| 获取玩家账户信息，分配到房间,房间就是我们的host代码
| -> Client 和 -> Host
|-
| Client
| 监听XPopManager.onGameStart
| -> 前端逻辑开始
|-
| Host
| 监听XPopManager.onHostStart
| -> 房间战斗逻辑开始

|}

远端服务器(官方)会处理最基本的登录，分配房间，创建游戏世界的逻辑，并且同步该世界中的游戏数据。

通过'''XpopManager'''管理类，来向Client和Host抛出事件，开发者可以监听这些事件做处理。

开发者需要关心的逻辑，就是Clint和Server（上图中Host）目录下的代码。

=== 前后端协议交互 ===
项目采用proto来做相互通信，建议参考如下篇幅 [[#npm run proto（协议通信）]]

=== 前后端共用配置 ===
前端'''src/client'''目录和后端'''src/server'''目录中，都可以调用如下代码来加载所有的表格配置
<pre>
CsvManager.ins.loadCsvs(this, () => {
// Do some thing after load
});
</pre>

表格的加载逻辑和解析逻辑，可以参考CsvManager中的代码
'''src/shared/csv/CsvManager.ts'''

''如何新增配置?''
以demo中的'''item.csv'''为例.
*1.配置csv文件资源的根目录为'''res-extra/csv/''' ,在里面添加'''item.csv'''
*2.'''CsvManager.ts'''文件中，添加读取表格和解析表格的逻辑
<pre>
// loadCsvs代码中，添加你需要解析的csv名称
public loadCsvs(caller: any = null, listener: Function = null) {
let assets = [
this._prefix + "item.csv",
];
// XResManager加载本地资源
XResManager.instance.loadText(assets, () => {
// 在加载完成的回调中，处理表格数据结构，生成CItemData，不再赘述
this.onCompleted(caller, listener);
});
}
</pre>
*3.解析表格得到的'''CItemData'''结构，定义在'''src/shared/dataMgr/'''中，可以被前后端一起调用
*4.如果是加载json文件，用'''XResManager.instance.loadText'''

=== 玩家战斗数据快照 ===
游戏战斗服务器中，每个玩家的实时信息，通过快照来更新
==== XVF_SnapData ====
以demo中的'''Snap_UserData.ts'''为例
*该玩家数据中类中，包含的各种public变量，都是''XVF_SnapData''接口类型
<pre>
export class Snap_UserData {
//坐标旋转
public position: XVF_SnapData<SyncPos>;
//状态
public state: XVF_SnapData<SyncState>;
//hp
public hp: XVF_SnapData<number>;
}
</pre>
快照类型数据，前端负责注册和监听，服务器负责修改
*每次该接口类型的数据发生变化时，会调用OnSet方法，这类数据的修改逻辑是：服务器修改，前端监听变化
** 前端登录成功后，服务器注册对应玩家数据
** 前端对数据中的某个XVF_SnapData做监听，注册OnSet方法
** 服务器战斗逻辑修改了该数据时，前端根据OnSet的逻辑做表现处理

服务器先注册全局的快照
<pre>
let userData = new Snap_UserData();
XPopManager.instance.xHost.RegisterSnapshot(`UserData${i}`, userData);
</pre>

前端绑定同一个地址的快照
<pre>
this._userData = new Snap_UserData();
XPopManager.instance.xRemote.RegisterSnapshot(`UserData${index}`, this._userData);
</pre>

*XVF_SnapData数据，如果是复杂类型，需要调用UpdateData()方法，前端才能触发OnSet
如下的SyncState就是复杂类型
<pre>
public state: XVF_SnapData<SyncState>;
public setState(key:string, obj:string):void{
this.state.value.key = key;
this.state.value.obj = obj;
this.state.UpdateData();
}
</pre>
*XVF_SnapData如果是基础类型，不需要调用UpdateData()
<pre>
public hp: XVF_SnapData<number>;
public setHP(hp:number):void {
this.hp.value = hp;
}
</pre>

=== 代码如何调试 ===
==== 前端调试 ====
直接在vscode中打断点即可，
可以很方便的观察堆栈和变量信息

[[File:前端调试.png]]

==== 本地服务器调试 ====
*本地服务器在调用命令'''npm run server'''后，会启动一个Host网页
*只要是网页，那就能调试js代码
*打开网页的开发者工具（一般浏览器是f12）,找到'''index.js'''文件
*这时有个问题，发现打不了断点，原因是代码编译过程被混淆了

[[File:服务器调试一.png]]

*我们需要关闭混淆的配置，在'''rollup.config.js'''中修改

[[File:服务器调试二.png]]

*修改plugins中，关闭sourcemap，不使用terser()压缩

[[File:服务器调试三.png]]

*修改完后，每次编译后运行的服务器Host代码就都可以断点了

编译，启动服务器，运行
<pre>
npm run build
npm run server
</pre>

*这次会发现，Host的网页代码有了行号，可以断点调试了

[[File:服务器调试四.png]]
==== 调试注意事项 ====
*每次'''npm run build'''后，如果修改了服务器代码，可以在本地host的浏览器里，立刻刷新，F5或者shift+f5
*如果修改了编译脚本来调试服务器，记得最后打包上传前，把rollup的代码改回来

== 地图的制作和选取 ==
=== 地图官网地址 ===
*[[上传流程|地图编辑器页签可以操作]]

=== 地图制作导出 ===
在项目目录'''/地图编辑器操作说明'''中，有视频教程

[[File:地图编辑视频.png]]

=== 开发环境选择地图 ===
我们在登录界面，可以通过填写你gameid中的地图名字，来进入指定地图。

所以必须要先创建gameid，并且选择至少一张地图，该地图才能在调试时进入。

举例：

*上传地图到某个游戏gameid时，会从你自己的'''可用地图'''中选择。

- 可用地图指的是你自己制作上传了地图。或者其他人共享给了你地图。

*比如你的可用地图名字是"推箱子"。

*右边会有可填写的自定义地图名字，比如"第一关"

那么登录的时候就是填写 "第一关"

*'''也就是说，地图做完后，必须要在审核平台上，添加到玩法里，生成自定义的名字，才可以在测试时填写进去生效 '''

== 打包与上传 ==

[[File:泡饭点击发布游戏.png]]

点击发布后，会把构建生成的压缩包上传到远端，就可以去试玩了。

=== 玩法测试 ===

[[File:泡饭点击打开审核后台.png]]

* [[上传流程|查看文档中试玩/审核/发布的部分]]

== 项目目录 ==

=== 主要工程目录 ===
对于开发者，需要关心和操作的目录如下：

* '''node_modules/''' - 通过npm安装的PGC库文件，对外暴露的方法，可以通过bridge.d.ts来外部引用
* '''res-extra/''' - 开发者除了PGC的远程资源外，需要额外使用到的资源目录，比如UI，图片，音频，表格，最后会打包上传到PGC远端资源服务器
* '''ui/''' - 开发者自己在laya编辑器中，拼接的界面json文件，运行命令后，会转化为PGT指定的XUIComponent存放于此
* '''src/''' - 开发者所有的战斗逻辑代码修改都在此进行
* '''src/client/''' - 前端代码，入口文件index.ts，监听XPopManager.onGameStart，前端游戏逻辑
* '''src/server/''' - 后端代码，入口文件index.ts，监听XPopManager.onHostStart，后端游戏逻辑
* '''src/shared/''' - 前后端共用的数据结构，包括表格，协议，玩家数据
* '''dist/''' - 编译后，生成的运行文件，包含前后端代码
* '''dist/client/''' - 编译后生成的混淆的前端代码
* '''dist/host/''' - 编译后服务端的代码文件，里面也包括表格数据的缓存

=== 前后端协议通信生成 ===

[[File:泡饭点击生成协议.png]]

==== 协议通信 ====
该命令会用到tsrpc的proto协议，
把'''src/shared/protocols'''下的指定格式文件，
转换到'''src/shared/protocols/generated/serviceProto'''文件中，

* 文件名为：Ptl{接口名}.ts '''（Ptl 是 Protocol 的缩写，l是小写的L）'''
* 请求类型名为： Req{接口名}，通过 interface 或 type 定义，需 export
* 响应类型名为：Res{接口名}，通过 interface 或 type 定义，需 export

例如，添加'''PtlPosition.ts'''文件
文件代码如下
<pre>
// 该接口用于向服务器同步自身的坐标
export interface ReqPosition {
i: number;
x: number;
y: number;
z: number;
ry: number;
}
export interface ResPosition {
ret: string;
diy: string;
}
</pre>

'''serviceProto.ts'''中会增加可外部调用的api类型
<pre>
export interface ServiceType {
api: {
"Position": {
req: ReqPosition,
res: ResPosition
},
},
msg: {

}
}
</pre>

'''前端代码调用请求'''
<pre>
// 前端可以用promise语法来调用同步位置的Request，异步处理服务器的返回值
let remote = XPopManager.instance.xRemote;
let ret = await remote.Request('Position', {i: 1, x:2, y:3, z:4, ry:5});
if(ret && ret.isSucc){
console.log(ret.res.diy)
}
</pre>

'''后端代码监听请求处理返回'''
<pre>
// 服务器收到前端请求的处理返回RegisterRpc
let host = XPopManager.instance.xHost;
//当收到坐标变化请求
host.RegisterRpc("Position", async (call: ApiCall<ReqPosition, ResPosition>) => {
let index = call.req.i;
let userData = this.usersData.get(index);
userData.setPosition(call.req.x, call.req.y, call.req.z, call.req.ry);
return call.succ({
ret: "Success",
diy: "自定义参数"
});
});
</pre>
如果想更多了解proto的结构和数据类型说明，可以参考官方链接
[tsrpc-proto格式说明](https://tsrpc.cn/docs/server/service-proto.html)

== 核心类目说明 ==
=== XPopManager ===
Bridge.d.ts中的核心类

对游戏逻辑进行了结构化的拆封和管理，

可以理解为，

库文件内处理了各种玩家的逻辑，比如登录，加载地图，分配房间，快照数据同步等等,然后关键的几个节点，暴露给外部去执行游戏逻辑。

开发者只需要去编写独立游戏模块的代码，其中，'''Xremote'''暴露给前端处理，'''Xhost'''暴露给后端处理

下面是最重要的几个生命周期函数
;onGameStart:玩家已经完成了登录步骤，已经分配好了房间，通知前端游戏开始
;onHostStart:玩家已经完成了登录步骤，已经分配好了房间，通知后端游戏开始
;onGameOver:游戏结束（一般是玩家都离开了战斗房间）
;onUpdate:每一帧会调用更新

我们在demo中，index.ts里，可以给这几个方法监听绑定函数，输出日志就可以查看

<pre>
XPopManager.onGameStart = ()=>{
new Main();
console.log("qc,XPopManager.onGameStart");
}

XPopManager.onGameOver = () => {
console.log("qc,XPopManager.onGameOver");
}

XPopManager.onHostStart = () => {
console.log("qc,XPopManager.onHostStart");
}

XPopManager.onUpdate = () => {
console.log("XPopManager.onUpdate");
}
</pre>

[[File:XPopManager生命周期.png]]

=== XRemote(前端) ===
*以下是最关键的生命周期和方法调用，调用逻辑可以自定义设计，后端代码同理
;UserID:玩家进入游戏的唯一id
;onUserEnter:每当房间内玩家进入时会调用，前端可以在此根据返回的userId来同步XHost玩家的快照数据，创建角色等等
;onUserLeave:每当房间内玩家离开时会调用，前端根据userId来处理模型的销毁
;RegisterSnapshot:用于注册绑定快照，快照类型开发者自定义，需要和XHost代码中绑定的地址一致，才可以收到OnSet回调
;Request:发送RPC请求，请求和回调的代码由protocol生成

=== XHost(后端) ===
;onUserEnter:每当房间内玩家进入时会调用，初始化玩家身上的快照数据，可以根据人数来判断游戏阶段，比如准备阶段
;onUserLeave:每当房间内玩家离开时会调用，清理玩家数据，可以根据玩家人数来判断是否进入结算或者游戏结束
;RegisterSnapshot:用于注册绑定快照，快照类型开发者自定义，需要和XRemote代码中绑定的地址一致
;RegisterRpc:注册RPC回调

=== XUIComponent(UI组件) ===
UI组件通过XUiManager.instance.OpenUI或者XUiManager.instance.CreateView加载显示
;showUI:调用后会设置active为true，当调用创建的方法，加载成功显示时也会调用一次，可以在创建时传参，每次主动调用也可以传参。
;hideUI:把该组件的active设置成false
;closeUI:把该组件从父节点移除，可以传参处理移除成功时的回调
=== XEventDispatcher(事件)===
我们可以根据已有的XEventDispatcher来封装一个单例，这样就能外部夸文件调用事件了。
如下为演示封装的单例
<pre>
export class EventManager extends XEventDispatcher{

constructor () {
super();
}

private static _instance: EventManager
public static get instance(): EventManager {
if (!this._instance) { this._instance = new EventManager(); }
return this._instance;
}

}
</pre>

事件的派发
<pre>
EventManager.instance.dispatch("new_event_name", ...args);
</pre>

事件的监听
<pre>
EventManager.instance.add("new_event_name", this, this.ParseNewEvent);

private ParseNewEvent(...args)
{
console.log("parse new event")
}
</pre>

== 官方论坛 ==
*[论坛地址](https://bbs.popx.com/)
*可以由我们内部人员给出的邀请链接申请加入论坛。
*申请后，等待审核人员核实，批准后，即可浏览论坛内容，发表疑问贴。
*强烈建议多去论坛搜索关键字，发帖会有对应的专业人员回答问题，大家一起维护论坛生态。
*常见问题faq帖子会持续维护

[论坛FAQ](https://bbs.popx.com/t/topic/53)