drgame-cc 1.0.12 → 1.0.13

package/README.md

@@ -0,0 +1,351 @@
+# drgame-cc
+
+**道然游戏 Cocos Creator 适配包** - 专为 Cocos Creator 项目设计的资源管理与构建优化工具
+
+[![npm version](https://img.shields.io/npm/v/drgame-cc.svg)](https://www.npmjs.com/package/drgame-cc)
+[![license](https://img.shields.io/npm/l/drgame-cc.svg)](https://github.com/your-repo/drgame-cc/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/drgame-cc.svg)](https://nodejs.org)
+
+## 📖 项目简介
+
+drgame-cc 是一个用于 **Cocos Creator 项目**的 npm 工具包，提供以下核心功能：
+
+- ✅ **自动资源管理**：安装时自动将 UI 组件和构建模板同步到你的 Cocos Creator 项目
+- ✅ **TVUI 组件库**：内置电视游戏 UI 组件，开箱即用
+- ✅ **构建模板优化**：预配置 Web Mobile 构建模板，包含 HLS 视频支持、启动画面等
+- ✅ **TypeScript 支持**：完整的类型定义，开发体验友好
+- ✅ **CLI 工具**：提供命令行接口，方便集成到自动化流程
+
+## 🚀 快速开始
+
+### 环境要求
+
+- **Node.js**: >= 18.0.0
+- **npm**: >= 8.0.0
+- **Cocos Creator**: 2.4.x+
+
+### 安装
+
+```bash
+# 在你的 Cocos Creator 项目根目录执行
+npm install drgame-cc
+```
+
+### 手动触发资源拷贝
+
+由于 npm v10+ 的安全机制限制，postinstall 脚本可能需要手动执行：
+
+```bash
+cd node_modules/drgame-cc
+node scripts/postinstall.js
+```
+
+成功后会看到：
+```
+✅ 开始拷贝资源
+📦 宿主项目: /path/to/your/project
+📦 目标目录: /path/to/your/project
+✅ build-templates 拷贝完成
+✅ tvui 拷贝完成
+🎉 资源拷贝完成！
+```
+
+## 📁 项目结构
+
+```
+drgame-cc/
+├── bin/                    # 命令行工具
+│   ├── drgame.js          # 主入口
+│   └── drgame.d.ts        # 类型定义
+├── build-templates/        # Cocos Creator 构建模板
+│   └── web-mobile/        # Web Mobile 平台模板
+│       ├── src/hls.min.js # HLS 流媒体支持
+│       ├── index.html     # 入口 HTML
+│       └── main.js        # 主逻辑
+├── tvui/                   # TV UI 组件资源
+├── scripts/
+│   └── postinstall.js    # 安装后脚本（自动拷贝资源）
+├── gulpfile.js            # Gulp 构建配置
+├── tsconfig.json          # TypeScript 配置
+└── package.json           # 包配置
+```
+
+## ⚙️ 功能详解
+
+### 1. TVUI 组件系统
+
+安装后，TVUI 组件会自动复制到 `assets/resources/tvui` 目录，包含：
+
+- 预制体组件
+- UI 样式资源
+- 图标素材
+
+在 Cocos Creator 中使用：
+```typescript
+import { SomeComponent } from 'drgame-cc';
+```
+
+### 2. Web Mobile 构建模板
+
+内置优化的 Web Mobile 构建模板，特性包括：
+
+- **HLS 视频支持**：内置 hls.min.js，支持 HTTP Live Streaming
+- **自定义启动画面**：中英文启动页支持
+- **加载动画**：进度条动画效果
+- **响应式布局**：移动端适配样式
+
+模板位置：`build-templates/web-mobile/`
+
+### 3. 环境变量配置
+
+可通过 `.env` 文件自定义配置（仅本地开发用，不会发布）：
+
+```env
+# Cocos Creator 项目根目录（相对于当前目录）
+COCOS_CREATOR_ROOT=../my-cocos-project
+```
+
+> ⚠️ **注意**：`.env` 文件已加入 `.npmignore`，不会发布到 npm
+
+## 🛠️ 开发指南
+
+### 本地开发设置
+
+```bash
+# 1. 克隆仓库
+git clone <repository-url>
+cd drgame-cc
+
+# 2. 安装依赖
+npm install
+
+# 3. 构建 TypeScript
+npm run build
+
+# 4. 运行测试
+npm test
+```
+
+### 可用的 npm Scripts
+
+| 命令 | 说明 |
+|------|------|
+| `npm run build` | 编译 TypeScript 并拷贝资源 |
+| `npm run buildJs` | 仅编译 JavaScript |
+| `npm run buildDts` | 仅生成类型定义 |
+| `npm run copyResources` | 拷贝资源到 Cocos Creator 项目 |
+
+### 开发流程
+
+1. **修改代码**
+   ```bash
+   # 编辑 src/ 目录下的 TypeScript 文件
+   ```
+
+2. **实时编译（推荐）**
+   ```bash
+   # 使用 tsc --watch 实时编译
+   npx tsc --watch
+   ```
+
+3. **测试修改**
+   ```bash
+   # 在测试项目中链接本地版本
+   cd /path/to/test-project
+   npm link ../drgame-cc
+   
+   # 或者直接引用本地路径
+   # 在 package.json 中:
+   # "drgame-cc": "file:../drgame-cc"
+   ```
+
+4. **手动运行 postinstall 测试**
+   ```bash
+   node scripts/postinstall.js
+   ```
+
+## 📦 发布指南
+
+### 发布前检查清单
+
+- [ ] 更新 `package.json` 中的版本号
+- [ ] 更新 CHANGELOG.md（如有）
+- [ ] 运行测试确保功能正常
+- [ ] 确保 `.env` 不会被发布（已配置 `.npmignore`）
+- [ ] 检查 `files` 字段只包含必要文件
+
+### 发布步骤
+
+```bash
+# 1. 更新版本号（遵循语义化版本）
+npm version patch     # 补丁版本：1.0.x -> 1.0.(x+1)
+npm version minor     # 次版本：1.x.y -> 1.(x+1).0
+npm version major     # 主版本：x.y.z -> (x+1).0.0
+
+# 2. 登录 npm（首次需要）
+npm login
+
+# 3. 干跑测试（查看将要发布的文件列表）
+npm pack --dry-run
+
+# 4. 正式发布
+npm publish
+
+# 5. 打 tag（可选）
+git push origin main --tags
+```
+
+### 版本号规则
+
+我们遵循 [语义化版本](https://semver.org/lang/zh-CN/)规范：
+
+- **MAJOR**：不兼容的 API 修改
+- **MINOR**：向下兼容的功能性新增
+- **PATCH**：向下兼容的问题修正
+
+示例：
+```
+1.0.12 -> 1.0.13 (patch: 修复 bug)
+1.0.12 -> 1.1.0 (minor: 新增功能)
+1.0.12 -> 2.0.0 (major: 重构或 breaking changes)
+```
+
+### 发布内容验证
+
+发布的 npm 包将包含以下文件（见 `package.json` 的 `files` 字段）：
+
+```
+drgame-cc-1.0.12.tgz
+├── tvui/**/*              # TVUI 组件资源
+├── build-templates/**/*   # 构建模板
+├── scripts/postinstall.js # 安装脚本
+└── bin/**/*               # CLI 工具
+```
+
+**不会包含的内容**：
+- ❌ `.env` / `.env.*` （环境变量配置）
+- ❌ `node_modules/` （依赖）
+- ❌ `dist/` / `*.tsbuildinfo` （编译产物）
+- ❌ `src/` （源码）
+- ❌ `.vscode/` / `.idea/` （编辑器配置）
+
+## 🔧 故障排除
+
+### 问题 1：postinstall 未自动执行
+
+**症状**：安装成功但没有拷贝资源
+
+**原因**：npm v10+ 默认阻止自动执行 install scripts
+
+**解决方案**：
+```bash
+# 方法 1：批准脚本
+npm approve-scripts drgame-cc
+
+# 方法 2：手动执行
+cd node_modules/drgame-cc
+node scripts/postinstall.js
+```
+
+### 问题 2：找不到目标目录
+
+**症状**：报错 `ENOENT: no such file or directory`
+
+**解决方案**：
+```bash
+# 创建 .env 文件并配置正确路径
+echo "COCOS_CREATOR_ROOT=/absolute/path/to/cocos" > .env
+```
+
+### 问题 3：权限错误 (EPERM)
+
+**症状**：Windows 上删除 node_modules 失败
+
+**解决方案**：
+```powershell
+# 以管理员身份运行 PowerShell
+# 或使用 rimraf
+npx rimraf node_modules
+npm install
+```
+
+### 问题 4：TypeScript 编译错误
+
+**症状**：`Cannot find module 'xxx'`
+
+**解决方案**：
+```bash
+# 清除缓存重新安装
+rm -rf node_modules package-lock.json
+npm install
+
+# 检查 TypeScript 版本
+npx tsc --version  # 应该是 5.9.3
+```
+
+## 📚 API 文档
+
+### CLI 使用
+
+```bash
+# 查看帮助
+drgame-cc --help
+
+# 拷贝资源
+drgame-cc copy
+```
+
+### TypeScript 接口
+
+```typescript
+// 导入主模块
+import { SomeClass } from 'drgame-cc';
+
+// 类型定义自动支持
+const instance: SomeClass = new SomeClass();
+```
+
+详细 API 文档请参考 `bin/dgame.d.ts`。
+
+## 🤝 贡献指南
+
+欢迎贡献代码！请遵循以下流程：
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'Add some amazing feature'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 提交 Pull Request
+
+### 代码规范
+
+- 使用 TypeScript 编写代码
+- 遵循 ESLint 配置（项目已配置）
+- 提交信息使用 Conventional Commits 规范
+
+## 📄 许可证
+
+本项目基于 [MIT License](LICENSE) 开源。
+
+## 🙏 致谢
+
+- [Cocos Creator](https://www.cocos.com/) - 游戏引擎
+- [Gulp](https://gulpjs.com/) - 构建工具
+- [TypeScript](https://www.typescriptlang.org/) - 编程语言
+
+---
+
+## 📞 联系方式
+
+- **问题反馈**：[GitHub Issues](https://github.com/your-repo/drgame-cc/issues)
+- **功能建议**：[GitHub Discussions](https://github.com/your-repo/drgame-cc/discussions)
+
+---
+
+<div align="center">
+
+**⭐ 如果这个项目对你有帮助，请给一个 Star！⭐**
+
+Made with ❤️ by [道然游戏](https://your-company.com)
+
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drgame-cc",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "道然游戏适配包",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",