mirror of
https://github.com/potato47/ccc-devtools.git
synced 2026-04-06 13:22:32 +00:00
feat: 整体重构
This commit is contained in:
Next
162
README.md
162
README.md
@@ -1,85 +1,137 @@
|
||||
> 主干分支适用 Cocos Creator 3.4+ 版本，其他版本查看其他分支
|
||||
# cccdev
|
||||
|
||||
# ccc-devtools
|
||||
Cocos Creator 网页预览调试工具 — 实时查看节点树、修改属性、性能分析。
|
||||
|
||||
## 简介
|
||||
|
||||
|
||||
ccc-devtools 是一款用于 Cocos Creator 网页端预览的调试工具，可以实时显示场景的节点树，并对节点属性进行同步更改。
|
||||
|
||||
|
||||
## 功能
|
||||
|
||||
- 实时节点树浏览
|
||||
- 节点属性同步编辑
|
||||
- 输出节点/组件引用到控制台
|
||||
- UI 节点位置标记
|
||||
- 独立调试信息面板（FPS 等）
|
||||
- Profiler 性能分析
|
||||
|
||||
## 使用
|
||||
|
||||
下载打包好的 [preview-template.zip](https://github.com/potato47/ccc-devtools/raw/master/release/preview-template.zip) 文件(release目录下)，解压到 Cocos Creator 项目目录下，刷新预览时的浏览器即可。
|
||||
节点属性修改不赘述，重点介绍几个独特的小功能：
|
||||
在 Cocos Creator 项目根目录下运行：
|
||||
|
||||
- 输出节点、组件引用到控制台，配合调试比较常用
|
||||
```bash
|
||||
# 推荐: 通过 npx/bunx 始终使用最新版本
|
||||
npx cccdev@latest init
|
||||
|
||||
|
||||
# 或
|
||||
bunx cccdev@latest init
|
||||
```
|
||||
|
||||
- 标记UI节点在场景中的位置
|
||||
如需覆盖已有的 `preview-template/`：
|
||||
|
||||
|
||||
```bash
|
||||
npx cccdev@latest init --force
|
||||
```
|
||||
|
||||
- 调试信息独立显示，再也不怕浅背景看不清 FPS 了
|
||||
CLI 会自动检测 Cocos Creator 版本，将 devtools 模板安装到 `preview-template/` 目录。刷新浏览器预览即可使用。
|
||||
|
||||
|
||||
```
|
||||
$ npx cccdev@latest init
|
||||
|
||||
检测到 Cocos Creator 3.x 项目
|
||||
|
||||
✓ 模板安装成功!
|
||||
|
||||
preview-template/
|
||||
index.ejs
|
||||
devtools/
|
||||
assets/
|
||||
index.js
|
||||
style.css
|
||||
|
||||
刷新浏览器预览即可使用 devtools。
|
||||
```
|
||||
|
||||
### 选项
|
||||
|
||||
```
|
||||
Usage: cccdev <command> [options]
|
||||
|
||||
Commands:
|
||||
init 安装 devtools 预览模板到 Cocos Creator 项目
|
||||
|
||||
Options:
|
||||
--help, -h 显示帮助
|
||||
--version 显示版本号
|
||||
--force 覆盖已存在的 preview-template
|
||||
```
|
||||
|
||||
## 开发
|
||||
|
||||
项目依据文档中自定义预览模板一节进行开发，未接触过相关概念可以先阅读一下官方文档
|
||||
>自定义预览模板
|
||||
预览支持自定义模板方便用户自定义需要的预览效果，自定义的预览模板可以放置在项目目录的 preview-template 文件夹中。或者点击编辑器主菜单中的 项目 -> 生成预览模板 就可以在项目目录下创建一个最新的预览模板。编辑器中的预览也是使用模板来注入最新的项目数据，预览时将会查找该目录下的 index 文件，如果存在就是要该文件作为预览的模板。
|
||||
preview-template 文件夹的结构类似：
|
||||
project-folder
|
||||
|--assets
|
||||
|--build
|
||||
|--preview-template
|
||||
// 必须的入口文件
|
||||
|--index.ejs
|
||||
// 其他文件可根据想要实现的预览效果进行添加
|
||||
### 前置要求
|
||||
|
||||
本项目主要修改index.ejs，注入一段 Vue 绑定的自定义html，核心修改见下图
|
||||
- [Bun](https://bun.sh) >= 1.0
|
||||
|
||||
### 项目结构
|
||||
|
||||
|
||||
```
|
||||
ccc-devtools/
|
||||
├── bin/cccdev.ts # CLI 入口
|
||||
├── src/
|
||||
│ ├── cli.ts # 命令路由
|
||||
│ ├── commands/init.ts # cccdev init 实现
|
||||
│ └── utils/ # detect, logger
|
||||
├── template/ # 构建产物 (gitignored, 发布时打入包)
|
||||
│ └── 3x/
|
||||
├── packages/
|
||||
│ └── cccdev-template-3x/ # CC 3.x 模板源码 (private, 不发布)
|
||||
│ ├── src/ # Preact 源码
|
||||
│ ├── template/ # vite 构建输出
|
||||
│ └── vite.config.ts # IIFE 构建配置
|
||||
```
|
||||
|
||||
在浏览器环境中 cc 是一个全局变量，可以通过 cc.director.getScene().children 获取场景中的节点，知道这点就可以开发了，剩下的就是节点数据如何展示出来的问题了。
|
||||
技术栈为 Vue3 + ElementPlus + TypeScript + Vite，熟悉前端的朋友欢迎来仓库贡献。
|
||||
项目结构如下：
|
||||
### 安装依赖
|
||||
|
||||
|
||||
```bash
|
||||
cd packages/cccdev-template-3x && bun install
|
||||
```
|
||||
|
||||
项目开发需配合本地已有的 Cocos Creator 3.x 项目，将 ccc-devtools 克隆到本地后，打开scripts/setup.js，将 projectTemplatePath 改为你的本地测试 Creator 项目路径。
|
||||
### 常用脚本
|
||||
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `bun run build` | 构建模板并复制到 `template/3x/` |
|
||||
| `bun run type-check` | TypeScript 类型检查（根目录 CLI 代码） |
|
||||
| `bun run lint` | oxlint 代码检查 |
|
||||
| `bun run lint:fix` | oxlint 自动修复 |
|
||||
| `bun run fmt` | oxfmt 格式化代码 |
|
||||
| `bun run fmt:check` | oxfmt 检查格式（不写入） |
|
||||
|
||||
开发流程：
|
||||
### 本地测试
|
||||
|
||||
- 安装依赖
|
||||
`yarn`
|
||||
|
||||
- 修改代码
|
||||
- 构建项目
|
||||
`yarn build`
|
||||
|
||||
- 安装构建产物到项目
|
||||
`yarn setup`
|
||||
|
||||
- 刷新浏览器查看效果
|
||||
在 Cocos Creator 项目中使用本地开发版本：
|
||||
|
||||
## 插件商店版
|
||||
```bash
|
||||
cd /path/to/cocos-project
|
||||
bun run /path/to/ccc-devtools/bin/cccdev.ts init
|
||||
```
|
||||
|
||||
[插件版](https://store.cocos.com/app/detail/3922)自带了一份工具代码，提供了自动安装功能。适合多个项目快速安装、卸载工具。
|
||||
### 发布
|
||||
|
||||
|
||||
```bash
|
||||
bun run build
|
||||
npm publish
|
||||
```
|
||||
|
||||
## 备注
|
||||
### 技术栈
|
||||
|
||||
- 源码地址：https://github.com/potato47/ccc-devtools
|
||||
- 打包文件：https://github.com/potato47/ccc-devtools/raw/master/release/preview-template.zip
|
||||
- UI 组件库：https://element-plus.org
|
||||
- 自定义网页预览文档：https://docs.cocos.com/creator/manual/zh/editor/preview/browser.html
|
||||
- 插件地址：https://store.cocos.com/app/detail/3922
|
||||
|
||||
- **视图层**: Preact + Signals (~3KB runtime)
|
||||
- **构建**: Vite (IIFE library mode)
|
||||
- **CLI**: Bun 原生 TS 执行，零运行时依赖
|
||||
|
||||
## 相关链接
|
||||
|
||||
- 自定义网页预览文档: https://docs.cocos.com/creator/manual/zh/editor/preview/browser.html
|
||||
- Cocos Creator 插件商店: https://store.cocos.com/app/detail/3922 （功能完全一样，仅供支持本人开发）
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user