# 开发指南

<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)