heros/.qoder/repowiki/zh/content/开发指南.md

开发指南

**本文档引用的文件** - [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)

目录

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 系统

md extensions
cd extensions
git clone -b master https://gitee.com/dgflash/oops-plugin-framework.git
git pull

macOS 系统

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
• using.md
• builder.json

代码规范与配置

TypeScript 编译设置

tsconfig.json 文件定义了项目的 TypeScript 编译选项：

{
  "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 文件定义了项目的基本信息和依赖：

{
  "name": "pixel_hero",
  "dependencies": {
    "crypto-es": "^2.1.0"
  }
}

• name: 项目名称为 "pixel_hero"
• dependencies: 使用 crypto-es 库进行加密操作

云函数配置

微信云函数位于 build-templates/wechatgame/cloud_functions/cocos_cloud 目录，其 package.json 依赖如下：

{
  "dependencies": {
    "wx-server-sdk": "~3.0.1"
  }
}

该配置确保云函数能够使用微信官方的服务器 SDK 进行数据库操作和用户认证。

Section sources

• tsconfig.json
• package.json
• cloud package.json

调试技巧

启动流程分析

Main.ts 是游戏的主入口文件，负责初始化核心系统：

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 全局变量访问：

export var smc: SingletonModuleComp = ecs.getSingleton(SingletonModuleComp);

该模块包含：

• 游戏初始化状态
• 地图数据
• 用户数据（金币、英雄等）
• MVVM 数据绑定

云函数调试

WxCloudApi.ts 封装了微信云函数调用：

public static async login(): Promise<...> {
    return await wx?.cloud.callFunction({
        name: 'cocos_cloud',
        data: { cmd: "login" }
    });
}

调试时可检查：

• 云环境 ID 是否正确初始化
• 网络连接状态
• 云函数返回的错误码

Section sources

• Main.ts
• SingletonModuleComp.ts
• WxCloudApi.ts

项目维护流程

参考信息管理

cankao.md 文件包含游戏设计参考数据，主要用于：

• 角色特性平衡设计
• 技能效果参数设定
• 游戏数值策划参考

文件采用 Markdown 表格格式，突出显示核心机制（加粗文本），便于快速查阅。

待办事项管理

todo.md 文件采用 Markdown 任务列表管理开发进度：

- [ ] 整个对战流程制作
- [x] cards 展示逻辑修改
- [x] 攻击加80%

该文件还定义了装备系统三维度分层模型：

1. 基础值: 单件装备的初始强度
2. 品质系数: 决定特效能力与成长潜力
3. 等级成长系数: 强化基础值和特效

此模型为装备系统提供了清晰的设计框架。

Section sources

• cankao.md
• todo.md

常见问题解决方案

构建失败

问题: 构建时出现资源打包错误
解决方案:

1. 检查 builder.json 中的压缩设置
2. 确保 resources 目录下的资源正确标记
3. 清理临时文件后重新构建

云函数部署错误

问题: Error: Cannot find module 'wx-server-sdk'
解决方案（参考 deploy.md）:

1. 安装依赖

npm install

2. 验证依赖

ls node_modules/wx-server-sdk

3. 重新部署 使用微信开发者工具上传并部署云函数

4. 检查配置

• 确认云开发环境已初始化
• 检查云函数名称一致性
• 验证网络连接和 npm 源

UI绑定异常

问题: MVVM 数据绑定失效
解决方案:

1. 确保调用 vmAdd() 方法注册数据
2. 检查数据字段命名一致性
3. 验证 UI 组件的绑定路径

Section sources

• deploy.md
• SingletonModuleComp.ts

性能优化建议

资源管理

• 合理使用 resources 目录，避免资源冗余
• 利用 Cocos Creator 的自动图集功能减少 Draw Call
• 对非关键资源采用异步加载

代码优化

• 减少 update() 方法中的复杂计算
• 复用对象实例，避免频繁创建销毁
• 使用对象池管理频繁创建的节点

网络优化

• 批量处理云函数调用，减少网络请求次数
• 对游戏数据进行增量同步而非全量覆盖
• 在弱网环境下提供本地缓存机制

构建优化

• 合理划分资源包，利用微信小游戏的子包机制
• 压缩纹理资源，平衡画质与包大小
• 移除未使用的依赖库

Section sources

• builder.json
• SingletonModuleComp.ts