# UE5编辑器AI控制插件

`UE5` `虚幻引擎` `AI代理` `C++插件` `编辑器自动化`

# UE5 编辑器控制

English | [中文](README.zh-CN.md)

> 一个 [Agent Skill](https://agentskills.io/) + UE5 C++ 插件，让 AI 代理能够完全控制 Unreal Engine 5 编辑器。

AI 代理可以直接生成 Actor、构建蓝图、创建材质、配置动画，并通过自然语言读写任意 UObject 属性。

## 安装

### 1. 安装 Skill

```bash
npx skills add 1103837067/ue5-editor-control
```

> 支持 35+ 种 AI 工具：Claude Code、Cursor、Codex、Copilot、Windsurf、Cline、Roo、Trae 等[更多](https://skills.sh/docs)。

CLI 仅安装 `skills/ue5-editor-control/` 目录（Markdown + 脚本），C++ 源代码**不会**被复制到你的 AI 工具中。

### 2. 安装 UE5 插件

```bash
# 从 GitHub Releases 自动下载预编译二进制文件
bash ~/.cursor/skills/ue5-editor-control/scripts/install.sh /path/to/your/UE5Project
```

脚本会自动检测你的平台（Mac/Windows）并下载对应的预编译二进制文件，无需 C++ 编译器。

### 3. 验证

打开 UE5 编辑器，然后执行：

```bash
curl -s http://localhost:58080/api/ping | python3 -m json.tool
```

### 4. 使用

直接与你的 AI 代理对话：

> "创建一个名为 BP_Enemy 的蓝图，包含一个网格体组件和 500 点生命值变量"

> "设置一个支持 WASD 移动、鼠标视角和跳跃的 FPS 角色"

---

## 面向 AI 代理

请参阅 [`AGENTS.md`](AGENTS.md)，其中包含代理专属说明、命令参考和工作流指引。

参考文档（由代理按需加载）：

| 模块 | 文件 |
|------|------|
| Actor 管理 | [skills/ue5-editor-control/references/actor.md](skills/ue5-editor-control/references/actor.md) |
| 蓝图结构与节点 | [skills/ue5-editor-control/references/blueprint.md](skills/ue5-editor-control/references/blueprint.md) |
| 材质系统 | [skills/ue5-editor-control/references/material.md](skills/ue5-editor-control/references/material.md) |
| 动画蓝图 | [skills/ue5-editor-control/references/animation.md](skills/ue5-editor-control/references/animation.md) |
| 通用反射与资产 | [skills/ue5-editor-control/references/property.md](skills/ue5-editor-control/references/property.md) |
| 增强输入与角色 | [skills/ue5-editor-control/references/input-character.md](skills/ue5-editor-control/references/input-character.md) |

---

## 功能特性

- **65 条命令**，涵盖 9 个类别
- **零硬编码** — 基于发现驱动：代理查询类型/函数/属性后再使用
- **通用反射** — `call_function`、`get_object`、`modify_array_property`、`execute_python`
- **批量执行** — 通过单次 HTTP 调用构建完整的蓝图图表
- **开放标准** — 兼容任何支持 [SKILL.md](https://agentskills.io/specification) 的代理

## 项目结构

```
ue5-editor-control/
├── skills/
│   └── ue5-editor-control/       # Skill（由 npx skills add 安装）
│       ├── SKILL.md              # agentskills.io 标准入口
│       ├── references/           # 详细命令文档（按需懒加载）
│       └── scripts/
│           ├── install.sh        # 从 Releases 下载预编译插件
│           └── ue5cmd.sh         # CLI 测试辅助工具
├── Source/UE5AIAssistant/        # C++ 插件源码（不由 skills CLI 安装）
│   ├── Public/Commands/*.h
│   └── Private/Commands/*.cpp
├── UE5AIAssistant.uplugin
├── scripts/
│   └── build-plugin.sh           # 构建预编译二进制（开发者使用）
├── AGENTS.md                     # AI 代理说明
├── CLAUDE.md                     # -> AGENTS.md
├── README.md                     # 本文件
└── LICENSE
```

说明：`npx skills add` 仅安装 `skills/ue5-editor-control/` 目录。C++ 源码保留在仓库中供开发使用，用户通过 GitHub Releases 获取预编译二进制文件。

## 从源码构建（面向开发者）

```bash
# 构建预编译插件二进制
bash scripts/build-plugin.sh

# 上传至 GitHub Releases
gh release create v1.0.0 dist/UE5AIAssistant-Mac-arm64-UE5.7.zip
```

需要本地安装 UE5 引擎。运行 `scripts/build-plugin.sh --help` 查看更多选项。

## 兼容性

| 要求 | 详情 |
|------|------|
| UE5 版本 | 5.4+（已在 5.7 测试） |
| 操作系统 | macOS、Windows、Linux |
| AI 工具 | 任何支持 [SKILL.md](https://agentskills.io/) 的代理（35+） |
| 依赖项 | `curl` |

## 许可证

MIT