# cocosGameAIworkflow

**Repository Path**: defiphoenix/cocos-game-aiworkflow

## Basic Information

- **Project Name**: cocosGameAIworkflow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-29
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cocos Game AI Workflow

探索通过 AI 制作 Cocos 小游戏的工作流：从需求和界面设计，到可运行、可验证的游戏。项目先把 UI 批量生成这一步做成可重复执行的工具，再逐步探索玩法、动画和交付环节。

## 工作流与当前进度

```text
需求拆解 → UI / 素材 → Prefab → 玩法逻辑 → 运行验证 → 反馈迭代
```

| 环节 | 当前状态 |
| --- | --- |
| 需求拆解 | 待探索：把游戏目标拆成页面、交互和验收条件 |
| UI / 素材 | 已约定布局 JSON、资源清单和独立 PNG；生图、切图由外部工具完成 |
| Prefab | 已实现 UI 批量生成器：校验、坐标转换、资源导入、组件配置和保存 |
| 玩法逻辑 / 动画 | 默认不生成；可选用 Funplay 在已有工程中挂接和调试 |
| 运行验证 / 迭代 | 有结构检查、离线预览和 Creator 构建；可选 Funplay 编辑器检查，实际交互按任务验收 |
| 打包交付 | 有 Creator 3.8.8 Web Mobile 构建脚本；完整游戏运行验收和产物归档待完善 |

仓库目前交付的是 **UI 批量生成器、编辑器接入助手和示例**，还不是完整小游戏生成系统。这里不包含 Cocos 引擎、编辑器或业务游戏源码。

## 当前工具

AI 输出布局 JSON 和资源清单，生成器通过官方 [cocos-cli](https://github.com/cocos/cocos-cli) 的 MCP 接口创建 UI 节点和组件，并保存为 Prefab。

- 支持容器、图片、文本、按钮、ScrollView、列表布局，以及锚点、Widget、九宫格和字体资源。
- `plan` 离线预检输入、资源和输出；`generate` 将计划写入指定 Cocos 工程。
- 默认拒绝覆盖已有 Prefab；显式 `--replace` 会重建整个 Prefab，手工添加的脚本和事件不会合并保留。
- 输入使用结构化布局数据，不直接解析任意 HTML/CSS；业务数据、按钮事件和复杂控件需自行接入。

完整输入约定、命令及边界见 [UI 批量生成器](docs/ui-generator.md)。

## 参考图生成 UI Skill（探索成果）

[cocos-ui-from-reference](skills/cocos-ui-from-reference/SKILL.md) 将“参考图拆解 → 独立素材 → 布局 JSON → Prefab → 完整工程 → 验证”封装为可复用技能。模型主要负责识图和填写布局，脚本处理坐标、资源 UUID、对象图和工程配置。

- 自包含 Creator **3.8.8** 编译后端，可直接输出主场景、可编辑 Prefab、素材和完整工程，无需启动 Cocos 4.0 alpha MCP。
- 带环境检查、简单 PNG 素材生成、离线预览、结构核验及官方编辑器构建脚本。Prefab 编译只需 Node.js 22.17+；素材与预览需要可用的 `sharp` 模块。
- 已通过完整属性面板和滚动/字体/Widget 综合示例的 Creator 3.8.8 实际构建，以及只提供参考图和技能的独立试用。构建检查、离线预览与实际交互验收分别报告。
- 默认生成独立 UI 工程，按钮业务事件由游戏接入；已有工程可选择 Funplay 编辑器模式增量维护，其他 Creator 版本需要另行适配。
- Main 场景中的 UI 与输出 Prefab 是独立拷贝；要联动更新，可通过编辑器改为真正的 Prefab 实例。

将整个 `skills/cocos-ui-from-reference/` 目录复制到 `$CODEX_HOME/skills/`（未设置时为 `~/.codex/skills/`），上传参考图后调用：

```text
使用 $cocos-ui-from-reference，把这张参考图还原为可编辑 UI，
生成 Creator 3.8.8 工程、Prefab 和预览，并执行验证。
```

技能包含输入约定、素材配方和入门示例；识图能力仍决定布局拆解与美术还原的质量。下方分别介绍可选 Funplay 模式和原有 Cocos 4 alpha MCP 生成器。

## 可选 Funplay 编辑器模式

[Funplay Cocos MCP](https://github.com/FunplayAI/funplay-cocos-mcp) 补充现有工程的增量编辑和真实预览。推荐流程是：

```text
参考图 → 布局/素材 → 离线编译独立工程 → 安装项目级 Funplay
       → Creator 打开工程 → 只读接入检查 → 增量编辑/保存 → 实际预览与交互验收
```

也可以直接对已安装 Funplay 的已有 Creator 3.8.x 工程进行调整。离线编译保持固定 3.8.8；安装助手使用固定的 Funplay 0.6.7 提交，不修改客户端全局配置：

```powershell
node skills/cocos-ui-from-reference/scripts/funplay.mjs install --project "E:\YourCocosProject" --report artifacts/funplay-install.json
```

使用本地源码时增加 `--source "E:\FunplaySource"`，要求该 Git 仓库干净且位于助手固定的提交。扩展安装到目标工程的 `extensions/funplay-cocos-mcp/`；一致副本会跳过，未知或手工修改的副本拒绝覆盖。打开或重新加载 Creator，从 `Funplay > MCP Server` 读取 URL，再运行：

```powershell
node skills/cocos-ui-from-reference/scripts/funplay.mjs check --project "E:\YourCocosProject" --endpoint "<面板实际URL>" --report artifacts/funplay-check.json
```

检查只证明 MCP 可用、工程身份/版本及编辑场景相符。后续可以用客户端已连接的 Funplay MCP 工具；客户端未注册该服务时，也可通过助手继续完成已授权任务。先读取实时工具目录和输入 schema：

```powershell
node skills/cocos-ui-from-reference/scripts/funplay.mjs tools --project "E:\YourCocosProject" --endpoint "<面板实际URL>" --report artifacts/funplay-tools.json
```

按报告中的 `tools[].inputSchema` 准备参数。例如创建 `artifacts/funplay-args.json`：

```json
{}
```

再做一次只读层级查询：

```powershell
node skills/cocos-ui-from-reference/scripts/funplay.mjs call --project "E:\YourCocosProject" --endpoint "<面板实际URL>" --tool get_hierarchy --args artifacts/funplay-args.json --report artifacts/funplay-hierarchy.json
```

`call` 在同一 MCP 会话内先核对工程和编辑场景，检查工具公开状态与必需参数，再执行一次；失败不重试。参数通过 JSON 文件传入，修改场景前先读工具 schema；报告的 `result` 保留 Funplay 返回 envelope，实际工具数据在 `result.data`。本路径不写客户端全局配置。工具调用成功仍需检查保存结果、脚本诊断、真实预览和交互。编辑场景脚本和 Game View 是不同上下文，外部浏览器预览需用浏览器工具检查。操作边界见 [Funplay 编辑器模式](skills/cocos-ui-from-reference/references/funplay-editor.md)。

Funplay 接入不改变生成文件的所有权保护：手改后的文件不再由离线 `--replace` 覆盖。继续在编辑器维护，或重新生成到新目录。每次任务是否通过实际编辑器验收以对应报告为准，安装或接通不能代替验收。

## 原有 Cocos 4 alpha MCP 生成器

需要 Node.js **22.17+**，以及已安装且可正常运行的官方 `cocos-cli`。本工具没有第三方 npm 依赖，目标为官方 Cocos 4.0 alpha 工具链；Creator 3.x 兼容性未验证。

在本仓库根目录运行以下命令，将 `E:\YourCocosProject` 替换为独立的测试工程绝对路径。创建命令只在工程尚不存在时执行：

```powershell
cocos create --project "E:\YourCocosProject" --type 2d
cocos start-mcp-server --project "E:\YourCocosProject" --port 9527
```

保持服务终端运行，在另一个终端进入本仓库，先预检两个示例，再生成：

```powershell
node bin/cocos-ui.mjs plan --batch examples/batch.json --project "E:\YourCocosProject" --out artifacts/batch.plan.json
node bin/cocos-ui.mjs generate --batch examples/batch.json --project "E:\YourCocosProject" --endpoint http://127.0.0.1:9527/mcp --report artifacts/batch.report.json
```

`http://127.0.0.1:9527/mcp` 是当前电脑上的 **MCP 工具接口**，不是可打开查看 UI 的公共网站。必须先启动对应工程的服务；Prefab 效果需要通过 Cocos 工程预览或运行查看。

示例生成到目标工程的 `assets/generated-ui/`。输出已存在时，确认允许重建后在生成命令中加 `--replace`。资源清单也应使用独立的生成目录，避免覆盖手工维护的美术。

## 验证记录

已实测官方 cocos-cli `0.0.1-alpha.43`、Cocos 引擎 `4.0.0-alpha.35`、Node.js `22.17.0`：

- 30 项自动化测试通过。
- ShopPanel 和 ConfirmDialog 两个示例共生成 37 个节点，保存后重新打开核对资源引用和组件。
- 直接解析生成 Prefab 的独立检查共 488 项通过。

这些记录验证的是生成及回读链路。浏览器截图、实际点击 / 滚动、多屏幕比例和完整游戏运行尚未验收。

```powershell
npm test
```

测试范围为 `test/*.test.mjs`；不要直接执行 `node --test`，以免扫描本地运行工程。

### Funplay 接入验证（2026-10-19）

- 环境：Node.js 24.12.0、Creator 3.8.8、Funplay 0.6.7（来源提交见 Skill 内固定来源文件）。
- 完整测试集 105 项通过、0 失败、0 跳过，包含原生成器、扩展安装保护、固定提交来源及真实 HTTP MCP 夹具。
- 隔离工程实测：固定版本下载及项目级安装、幂等检查、39 个实时工具 schema、目标工程身份和 Main 场景核对均通过。
- 通过 Funplay 修改 Label、编辑器保存、独立读取磁盘文件，并重启 Creator 后重新读取，确认内容持久化。
- Game View 启动返回 running=true、toolbarSynchronized=true；独立复制整份 Skill 后，也完成了真实工程只读检查和 Canvas 层级查询。
- 隐藏测试窗口不满足校准截图条件，截图、实际点击/滚动、多比例和设备运行不计为通过。

本机报告保存在已忽略的 artifacts/funplay-*.json、artifacts/forward-funplay-*.json 和 artifacts/funplay-tests-final.log；测试工程位于 .runtime/funplay-e2e-388，不随仓库提交。

## 仓库入口

- [生成器使用说明](docs/ui-generator.md)
- [批量任务示例](examples/batch.json)、[商店布局](examples/shop.layout.json)、[资源清单](examples/shop.assets.json)
- [参考图生成 UI Skill](skills/cocos-ui-from-reference/SKILL.md)：参考图到可编辑 UI、Prefab 和 Creator 3.8.8 工程的自包含技能。
- [Funplay 编辑器模式](skills/cocos-ui-from-reference/references/funplay-editor.md)：项目级安装、只读接入检查和运行验收边界。
- [生成器源码](src/)、[命令入口](bin/cocos-ui.mjs)、[自动化测试](test/)
- [示例图片来源与许可](examples/assets/SOURCES.md)

`.runtime/` 中的本地 Cocos 工程和 `artifacts/` 中的测试报告、运行产物不随仓库上传。示例 PNG 来自官方测试夹具，仅用于验证生成链路，请在游戏中替换为实际美术资源。