ue5-editor-control

UE5 编辑器控制

UE5 编辑器的 HTTP API。插件 UE5AIAssistant 在 localhost:58080 上运行。

自动设置流程（首次使用时必须遵循）

每次需要使用此技能时，从这里开始：

步骤 1：检查插件是否已在运行

curl -s --max-time 3 http://localhost:58080/api/ping

• 如果响应包含 "success": true → 跳转到下方的快速入门
• 如果连接被拒绝／超时 → 插件未运行，继续步骤 2

步骤 2：查找用户的 UE5 项目

询问用户："你的 UE5 项目路径是什么？"

或自动检测（查找 .uproject 文件）：

# macOS common locations
find ~/Documents ~/Desktop ~/Projects ~/codeprojects -maxdepth 3 -name "*.uproject" 2>/dev/null

保存项目路径以供后续使用。

步骤 3：检查项目中是否已安装插件

# Check if plugin exists in the UE5 project
test -f "<UE5_PROJECT_PATH>/Plugins/UE5AIAssistant/UE5AIAssistant.uplugin" && echo "INSTALLED" || echo "NOT INSTALLED"

• 如果为 INSTALLED → 告知用户："插件已安装，请打开 UE5 编辑器然后告诉我"
• 如果为 NOT INSTALLED → 继续步骤 4

步骤 4：安装插件

选项 A — 下载预编译二进制文件（推荐，无需 C++）：

bash scripts/install.sh "<UE5_PROJECT_PATH>"

如果失败（尚未发布任何版本），则改用选项 B。

选项 B — 复制源代码（需要 UE5 C++ 编译）：

此技能的 GitHub 仓库包含 C++ 源代码。克隆并复制：

# Clone the repo (if not already available)
git clone https://github.com/1103837067/ue5-editor-control.git /tmp/ue5-editor-control

# Copy plugin source to UE5 project
mkdir -p "<UE5_PROJECT_PATH>/Plugins/UE5AIAssistant"
cp -r /tmp/ue5-editor-control/Source "<UE5_PROJECT_PATH>/Plugins/UE5AIAssistant/"
cp /tmp/ue5-editor-control/UE5AIAssistant.uplugin "<UE5_PROJECT_PATH>/Plugins/UE5AIAssistant/"

然后告知用户："插件已复制到项目中。请打开 UE5 编辑器，它会自动编译插件。打开后告诉我。"

步骤 5：验证连接

curl -s --max-time 3 http://localhost:58080/api/ping

如果仍然失败，请让用户检查：

• UE5 编辑器已打开并加载了正确的项目
• 检查输出日志中是否有 "UE5AIAssistant: HTTP server started on port 58080"
• 插件已启用：编辑 → 插件 → 搜索 "UE5AIAssistant"

前置条件摘要

要求	详情
UE5	已安装 5.4+ 并已创建项目
操作系统	macOS / Windows / Linux
curl	macOS/Linux 上预装；Windows 上使用 Git Bash
UE5 编辑器	必须正在运行且已启用插件
C++（仅选项 B）	仅在你的平台没有可用的预编译二进制文件时需要

快速入门

# Execute command (preferred for complex JSON)
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"command":"get_actors_in_level","args":{}}' \
  http://localhost:58080/api/execute

# Simple commands via helper
bash scripts/ue5cmd.sh exec get_actors_in_level '{}'

响应：{ "success": true|false, "data": {...}|null, "error": "..."|null }

常见错误 — 请勿

• 请勿逐个添加节点 — 始终使用 batch_execute
• 请勿猜测 C++ 函数名称 — 先使用 list_functions
• 请勿硬编码引脚名称 — 从响应的 pins 数组中读取
• 编辑后请勿跳过 compile_blueprint
• 请勿将 ue5cmd.sh 用于复杂 JSON — 直接使用 curl

任务路由器 — 阅读相应模块

根据用户的任务，只阅读相关模块文件，了解详细命令、参数和工作流：

用户想要……	阅读此文件
使用演员（生成、删除、变换、属性）	references/actor.md
构建蓝图结构和逻辑（创建 BP、变量、函数、节点、batch_execute）	references/blueprint.md
创建材质（表达式、连接、应用）	references/material.md
构建动画蓝图（状态机、状态、转换）	references/animation.md
通过反射访问任意属性、管理资源（创建／读取／写入）	references/property.md
设置 Enhanced Input、配置角色移动、构建端到端角色	references/input-character.md

规则：

1. 只阅读当前任务所需的模块 — 请勿阅读所有文件
2. 如果不确定该选哪个模块，请查看上表或阅读用户的意图
3. 多个任务可能需要多个模块（例如，角色 = blueprint + input-character）

65 个命令概览（仅供快速了解）

类别	命令	数量
Actor	get_actors_in_level, find_actors_by_name, get_selected_actors, spawn_actor, delete_actor, set_actor_transform, get_actor_properties, set_actor_property, attach_actor, detach_actor	10
Blueprint 结构	create_blueprint, compile_blueprint, read_blueprint_content, create_variable, add_component_to_blueprint, create_function, add_function_parameter, create_event_dispatcher, create_blueprint_interface, implement_interface, add_widget_child	11
Blueprint 发现	list_node_types, list_blueprint_classes, list_functions	3
Blueprint 节点	add_node, connect_nodes, remove_node, get_node_pins, set_pin_default, batch_execute, add_pin, auto_layout_graph	8
材质	create_material, add_material_expression, connect_material_expressions, apply_material_to_actor, get_available_materials	5
资产	search_assets, get_assets_by_class, get_asset_details	3
编辑器	focus_viewport, get_current_level_info, save_all, get_project_settings, set_project_setting, get_world_settings, set_world_setting	7
动画	create_anim_blueprint, get_anim_blueprint_info, add_anim_state_machine, add_anim_state, add_anim_transition, set_anim_state_animation, compile_anim_blueprint	7
通用反射	list_components, list_properties, get_component_property, set_component_property, create_asset, get_asset_property, set_asset_property, call_function, get_object, modify_array_property, execute_python	11

错误速查

错误模式	修复方法
"not found"	使用发现命令（find_actors_by_name、search_assets、list_functions、list_node_types、list_properties）
"Pin 'xxx' not found"	错误响应会列出所有可用引脚，请使用正确的名称
compile_blueprint 诊断信息	阅读 references/blueprint.md 中的错误处理部分