1 line
4.3 KiB
JSON
1 line
4.3 KiB
JSON
{"repo": "chexiongsheng/mazerunnerdemo", "files": {"README.md": {"1831638c52a162985cfa119b5c52873c3813bcb3": {"t": 1785674236.8170097, "n": 2687, "h": "ffcf003b9064ce2e", "c": "项目附带了一个 AI 自主走迷宫的 Demo，展示 Agent 通过截屏观察 + 工具调用来探索 3D 迷宫。\r\n也接入了Puerts助手，包括Agent版和MCP版。\r\n\r\n## 准备工作\r\n\r\n### 克隆仓库\r\n\r\n本项目包含 Git submodule，克隆时请使用 `--recursive` 参数以同时拉取所有子模块：\r\n\r\n```bash\r\ngit clone --recursive https://github.com/chexiongsheng/MazeRunnerDemo\r\n```\r\n\r\n如果已经克隆但忘记加 `--recursive`，可以补充初始化子模块：\r\n\r\n```bash\r\ngit submodule update --init --recursive\r\n```\r\n\r\n### 获取 PuerTS 插件二进制\r\n\r\n项目依赖的 [PuerTS](https://github.com/Tencent/puerts) submodule 中**不包含**编译好的二进制插件，需要手动从 PuerTS 的 GitHub Releases 页面下载并解压。\r\n\r\n以 `Unity_v3.0.1` 为例，下载地址：\r\n> https://github.com/Tencent/puerts/releases/tag/Unity_v3.0.1\r\n\r\n需要下载以下三个插件包，并将各自的 `Plugins` 目录内容放置到对应的 UPM 包路径下：\r\n\r\n| 插件包 | 说明 | 放置路径 |\r\n|--------|------|----------|\r\n| **PuerTS-Core** | PuerTS 核心插件 | `puerts/unity/upms/core/Plugins/` |\r\n| **PuerTS-V8** | V8 引擎后端插件 | `puerts/unity/upms/v8/Plugins/` |\r\n| **PuerTS-Nodejs** | Node.js 后端插件 | `puerts/unity/upms/nodejs/Plugins/` |\r\n\r\n> ⚠️ **注意**：不要放到 `Assets/Plugins/`，应放到各 UPM 包自身的 `Plugins` 目录下。\r\n\r\n## Agent版本Puerts助手\r\n\r\n点击菜单\"Puerts Agent/New Chat Window\"\r\n\r\n## MCP版本Puerts助手\r\n\r\n点击菜单\"Puerts/MCP Server\"\r\n\r\n在IDE配置\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"puerts-unity-editor-assistant\": {\r\n \"url\": \"http://127.0.0.1:3100/sse\"\r\n }\r\n }\r\n}\r\n```\r\n\r\n## Demo: AI 迷宫探索\r\n\r\n### 1. 生成迷宫场景\r\n\r\n菜单栏 **Tools → Maze Runner → Generate Maze Scene**，打开迷宫生成器窗口：\r\n\r\n| 参数 | 说明 | 默认值 | 范围 |\r\n|------|------|--------|------|\r\n| Maze Width | 迷宫宽度（格数） | 8 | 4–16 |\r\n| Maze Height | 迷宫高度（格数） | 8 | 4–16 |\r\n| Cell Size | 每格大小（米） | 2.0 | 1.5–4.0 |\r\n| Wall Height | 墙壁高度（米） | 1.2 | 0.5–5.0 |\r\n| Wall Thickness | 墙壁厚度（米） | 0.2 | 0.1–0.5 |\r\n\r\n点击 **Generate Maze Scene** 按钮，将自动生成一个完整的迷宫场景，包含：\r\n- 使用递归回溯算法生成的随机迷宫\r\n- 带 CharacterController 的玩家角色（起点在左下角）\r\n- 红色目标标记（终点在右上角）\r\n- 俯视相机\r\n- MazeDemoManager 和 MazeAgentUI 组件\r\n\r\n场景保存在 `Assets/Scenes/MazeDemo.unity`。\r\n\r\n### 2. 配置 API Key\r\n\r\n生成场景后，在 Hierarchy 中选中 **MazeDemoManager** 对象，在 Inspector 面板中配置以下字段：\r\n\r\n| 字段 | 说明 | 示例 |\r\n|------|------|------|\r\n| **Api Key** | LLM 服务的 API Key（必填） | `sk-xxxxxxxx` |\r\n| **Base URL** | API 端点地址（兼容 OpenAI 格式，留空使用默认值） | `https://dashscope.aliyuncs.com/compatible-mode/v1` |\r\n| **Model** | 模型名称（留空使用默认值） | `qwen-plus` |\r\n| **Max Steps** | 最大工具调用步数，0 = 无限制 | `0` |\r\n\r\n### 3. 构建迷宫 Demo 的 TypeScript\r\n\r\n迷宫 Demo 有独立的 TypeScript 工程 `TsMazeRunner/`，需要单独构建：\r\n\r\n```bash\r\ncd TsMazeRunner\r\nnpm install\r\nnpm run build\r\n```\r\n\r\n构建产物输出到 `Assets/Resources/maze-runner/builtins/`。\r\n\r\n### 4. 运行 Demo\r\n\r\n1. 打开 `Assets/Scenes/MazeDemo.unity` 场景\r\n2. 确认 MazeDemoManager 上已配置好 API Key\r\n3. 点击 Unity 的 **Play** 按钮进入运行模式\r\n4. 点击屏幕右上角的 **▶ Start Exploration** 按钮启动 AI 探索\r\n5. AI 将自动截屏观察环境、规划路径、调用移动接口来走迷宫\r\n6. 到达终点后会自动宣布成功\r\n\r\n运行时还可以使用以下控制按钮：\r\n- **⏹ Stop** — 中止当前探索\r\n- **🔄 Reset** — 重置迷宫和对话历史\r\n"}}}} |