268 lines
7.7 KiB
Markdown
268 lines
7.7 KiB
Markdown
# 开发指南
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [README.md](file://doc/using.md)
|
||
- [using.md](file://doc/using.md)
|
||
- [tsconfig.json](file://tsconfig.json)
|
||
- [package.json](file://package.json)
|
||
- [cankao.md](file://assets/script/cankao.md)
|
||
- [todo.md](file://assets/script/todo.md)
|
||
- [Main.ts](file://assets/script/Main.ts)
|
||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||
- [builder.json](file://settings/v2/packages/builder.json)
|
||
- [deploy.md](file://build-templates/wechatgame/cloud_functions/cocos_cloud/deploy.md)
|
||
- [cloud package.json](file://build-templates/wechatgame/cloud_functions/cocos_cloud/package.json)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [环境搭建](#环境搭建)
|
||
2. [代码规范与配置](#代码规范与配置)
|
||
3. [调试技巧](#调试技巧)
|
||
4. [项目维护流程](#项目维护流程)
|
||
5. [常见问题解决方案](#常见问题解决方案)
|
||
6. [性能优化建议](#性能优化建议)
|
||
|
||
## 环境搭建
|
||
|
||
本项目基于 Cocos Creator 引擎开发，采用 Oops Framework 插件架构。以下是详细的开发环境配置步骤：
|
||
|
||
### Cocos Creator 版本要求
|
||
根据 `package.json` 文件中的信息，本项目使用 **Cocos Creator 3.8.6** 版本开发。建议开发者使用相同版本以确保兼容性。
|
||
|
||
### 框架安装与更新
|
||
Oops Framework 以插件形式集成到项目中，位于 `extensions/oops-plugin-framework` 目录。可通过以下命令自动更新至最新版本：
|
||
|
||
**Windows 系统**
|
||
```bash
|
||
md extensions
|
||
cd extensions
|
||
git clone -b master https://gitee.com/dgflash/oops-plugin-framework.git
|
||
git pull
|
||
```
|
||
|
||
**macOS 系统**
|
||
```bash
|
||
mkdir -p extensions
|
||
cd extensions
|
||
git clone -b master https://gitee.com/dgflash/oops-plugin-framework.git
|
||
git pull
|
||
```
|
||
|
||
### 微信开发者工具集成
|
||
项目已配置微信小游戏平台支持。在构建时选择 "wechatgame" 平台，系统会自动应用 `builder.json` 中的子包压缩设置，确保符合微信小游戏的包大小限制。
|
||
|
||
**Section sources**
|
||
- [package.json](file://package.json#L1-L13)
|
||
- [using.md](file://doc/using.md#L1-L20)
|
||
- [builder.json](file://settings/v2/packages/builder.json#L1-L128)
|
||
|
||
## 代码规范与配置
|
||
|
||
### TypeScript 编译设置
|
||
`tsconfig.json` 文件定义了项目的 TypeScript 编译选项：
|
||
|
||
```json
|
||
{
|
||
"extends": "./temp/tsconfig.cocos.json",
|
||
"compilerOptions": {
|
||
"strict": false,
|
||
"target": "es2017",
|
||
"lib": ["es2017", "dom"]
|
||
}
|
||
}
|
||
```
|
||
|
||
- **extends**: 继承 Cocos Creator 自动生成的基础配置
|
||
- **strict**: 关闭严格模式，提供更灵活的类型检查
|
||
- **target**: 编译目标为 ES2017，确保现代 JavaScript 特性支持
|
||
- **lib**: 包含 ES2017 和 DOM 类型定义，支持浏览器环境开发
|
||
|
||
### 项目依赖管理
|
||
`package.json` 文件定义了项目的基本信息和依赖：
|
||
|
||
```json
|
||
{
|
||
"name": "pixel_hero",
|
||
"dependencies": {
|
||
"crypto-es": "^2.1.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
- **name**: 项目名称为 "pixel_hero"
|
||
- **dependencies**: 使用 `crypto-es` 库进行加密操作
|
||
|
||
### 云函数配置
|
||
微信云函数位于 `build-templates/wechatgame/cloud_functions/cocos_cloud` 目录，其 `package.json` 依赖如下：
|
||
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
"wx-server-sdk": "~3.0.1"
|
||
}
|
||
}
|
||
```
|
||
|
||
该配置确保云函数能够使用微信官方的服务器 SDK 进行数据库操作和用户认证。
|
||
|
||
**Section sources**
|
||
- [tsconfig.json](file://tsconfig.json#L1-L12)
|
||
- [package.json](file://package.json#L1-L13)
|
||
- [cloud package.json](file://build-templates/wechatgame/cloud_functions/cocos_cloud/package.json#L1-L15)
|
||
|
||
## 调试技巧
|
||
|
||
### 启动流程分析
|
||
`Main.ts` 是游戏的主入口文件，负责初始化核心系统：
|
||
|
||
```typescript
|
||
export class Main extends Root {
|
||
protected async run() {
|
||
smc.initialize = ecs.getEntity<Initialize>(Initialize);
|
||
smc.vmAdd()
|
||
}
|
||
|
||
protected initGui() {
|
||
oops.gui.init(UIConfigData);
|
||
}
|
||
}
|
||
```
|
||
|
||
- **run()**: 初始化 ECS 实体和单例模块
|
||
- **initGui()**: 初始化 GUI 系统，加载 UI 配置
|
||
|
||
### 单例模块调试
|
||
`SingletonModuleComp.ts` 提供了全局游戏状态管理，通过 `smc` 全局变量访问：
|
||
|
||
```typescript
|
||
export var smc: SingletonModuleComp = ecs.getSingleton(SingletonModuleComp);
|
||
```
|
||
|
||
该模块包含：
|
||
- 游戏初始化状态
|
||
- 地图数据
|
||
- 用户数据（金币、英雄等）
|
||
- MVVM 数据绑定
|
||
|
||
### 云函数调试
|
||
`WxCloudApi.ts` 封装了微信云函数调用：
|
||
|
||
```typescript
|
||
public static async login(): Promise<...> {
|
||
return await wx?.cloud.callFunction({
|
||
name: 'cocos_cloud',
|
||
data: { cmd: "login" }
|
||
});
|
||
}
|
||
```
|
||
|
||
调试时可检查：
|
||
- 云环境 ID 是否正确初始化
|
||
- 网络连接状态
|
||
- 云函数返回的错误码
|
||
|
||
**Section sources**
|
||
- [Main.ts](file://assets/script/Main.ts#L1-L41)
|
||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L195)
|
||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts#L1-L94)
|
||
|
||
## 项目维护流程
|
||
|
||
### 参考信息管理
|
||
`cankao.md` 文件包含游戏设计参考数据，主要用于：
|
||
|
||
- 角色特性平衡设计
|
||
- 技能效果参数设定
|
||
- 游戏数值策划参考
|
||
|
||
文件采用 Markdown 表格格式，突出显示核心机制（加粗文本），便于快速查阅。
|
||
|
||
### 待办事项管理
|
||
`todo.md` 文件采用 Markdown 任务列表管理开发进度：
|
||
|
||
```markdown
|
||
- [ ] 整个对战流程制作
|
||
- [x] cards 展示逻辑修改
|
||
- [x] 攻击加80%
|
||
```
|
||
|
||
该文件还定义了**装备系统三维度分层模型**：
|
||
1. **基础值**: 单件装备的初始强度
|
||
2. **品质系数**: 决定特效能力与成长潜力
|
||
3. **等级成长系数**: 强化基础值和特效
|
||
|
||
此模型为装备系统提供了清晰的设计框架。
|
||
|
||
**Section sources**
|
||
- [cankao.md](file://assets/script/cankao.md#L1-L45)
|
||
- [todo.md](file://assets/script/todo.md#L1-L110)
|
||
|
||
## 常见问题解决方案
|
||
|
||
### 构建失败
|
||
**问题**: 构建时出现资源打包错误
|
||
**解决方案**:
|
||
1. 检查 `builder.json` 中的压缩设置
|
||
2. 确保 `resources` 目录下的资源正确标记
|
||
3. 清理临时文件后重新构建
|
||
|
||
### 云函数部署错误
|
||
**问题**: `Error: Cannot find module 'wx-server-sdk'`
|
||
**解决方案**（参考 `deploy.md`）:
|
||
|
||
1. **安装依赖**
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
2. **验证依赖**
|
||
```bash
|
||
ls node_modules/wx-server-sdk
|
||
```
|
||
|
||
3. **重新部署**
|
||
使用微信开发者工具上传并部署云函数
|
||
|
||
4. **检查配置**
|
||
- 确认云开发环境已初始化
|
||
- 检查云函数名称一致性
|
||
- 验证网络连接和 npm 源
|
||
|
||
### UI绑定异常
|
||
**问题**: MVVM 数据绑定失效
|
||
**解决方案**:
|
||
1. 确保调用 `vmAdd()` 方法注册数据
|
||
2. 检查数据字段命名一致性
|
||
3. 验证 UI 组件的绑定路径
|
||
|
||
**Section sources**
|
||
- [deploy.md](file://build-templates/wechatgame/cloud_functions/cocos_cloud/deploy.md#L1-L32)
|
||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L195)
|
||
|
||
## 性能优化建议
|
||
|
||
### 资源管理
|
||
- 合理使用 `resources` 目录，避免资源冗余
|
||
- 利用 Cocos Creator 的自动图集功能减少 Draw Call
|
||
- 对非关键资源采用异步加载
|
||
|
||
### 代码优化
|
||
- 减少 `update()` 方法中的复杂计算
|
||
- 复用对象实例，避免频繁创建销毁
|
||
- 使用对象池管理频繁创建的节点
|
||
|
||
### 网络优化
|
||
- 批量处理云函数调用，减少网络请求次数
|
||
- 对游戏数据进行增量同步而非全量覆盖
|
||
- 在弱网环境下提供本地缓存机制
|
||
|
||
### 构建优化
|
||
- 合理划分资源包，利用微信小游戏的子包机制
|
||
- 压缩纹理资源，平衡画质与包大小
|
||
- 移除未使用的依赖库
|
||
|
||
**Section sources**
|
||
- [builder.json](file://settings/v2/packages/builder.json#L1-L128)
|
||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L195) |