最近在学习用python端来调用ue5进行图像保存，踩了一些坑，记录一下，便于自己日后再复盘

前置条件（重要）

1. 项目类型要求

• UE5项目必须是C++项目，不能是蓝图专用项目
• 原因：UnrealCV需要编译源代码，蓝图项目无法进行C++编译

2. UnrealCV插件

什么是UnrealCV？

• 开源项目，帮助计算机视觉研究人员利用UE构建虚拟世界
• 通过插件扩展UE功能，实现UE与外部程序（如Python）的通信
• 提供了一组命令与虚拟世界交互
• 支持编译游戏二进制文件或在UE编辑器中直接使用

原文参考：https://blog.csdn.net/gitblog_00205/article/details/142247834

踩坑记录

坑1️⃣：插件编译失败导致链接错误

现象：

• UnrealCV插件在Visual Studio（2022版本）没有正确编译或使用了不兼容的预编译版本

根本原因：

• 插件放置位置不正确

解决方案：

1. 安装 UnrealCV 源码：

git clone https://github.com/unrealcv/unrealcv.git UnrealCV

注意：目录结构项目文件下为 YourProject/Plugins/UnrealCV/UnrealCV.uplugin（确保UnrealCV插件文件在正确位置：Plugins/UnrealCV/）放在项目的 Plugins 文件夹（不是引擎目录）

·可参考https://github.com/unrealcv/unrealcv中的README
2. 在Visual Studio中打开UE项目，右键 .uproject 文件然后"Generate Visual Studio project files"，生成 VS 项目文件
3. 用 Visual Studio 编译：

        (1)双击 .sln 打开 VS (2)Configuration: Development Editor

        编译过程中UnrealCV插件会自动编译

启发：

• 插件编译是UE与Python通信的基础，必须确保编译成功

坑2️⃣：Python客户端无法连接到UE

现象：

• Python脚本运行时无法连接到UE5
• 连接超时或被拒绝

根本原因：

• UE5项目没有处于运行/PLAY状态
• UnrealCV只在游戏运行时才监听Socket连接

解决方案：

✓ 确保UE项目正在运行（点击PLAY按钮或运行编辑器）
✓ Python客户端连接之前，UE必须已启动
✓ 检查UnrealCV监听端口（默认通常是9000，具体见插件配置）

启发：

• UnrealCV是一个客户端-服务器架构：UE是服务器，Python是客户端
• 必须先启动"服务器"（UE），再启动"客户端"（Python）
• 这是异步通信的基本要求

坑3️⃣：Unreal Engine plugin for Visual Studio插件安装（手动）

官方参考链接https://github.com/microsoft/vc-ue-extensions

在重新编译好unrealCV后还是缺少插件（从VS打开项目会自动识别缺少的插件，然后按照提示一步步进行补充安装就行）

安装步骤：

（1）克隆仓库

git clone https://github.com/microsoft/vc-ue-extensions.git

（2）构建插件

msbuild -p:UnrealEngine=<虚幻引擎的绝对路径>

比如我的："D:\Epic Games\UE_5.4"

注意：msbuild 命令。需要使用 Visual Studio 的开发者工具--搜索 "Developer Command Prompt for VS 2022"

导航到插件目录并构建：

cd C:\Users\yourname\vc-ue-extensions
msbuild -p:UnrealEngine="D:\Epic Games\UE_5.4"

（3）复制插件到目标位置（虚幻引擎能找到的地方）

• 确认插件已经构建好

ls ./bin

• 两个可以放插件的位置（引擎的插件文件夹和项目的插件文件夹）

Move-Item -Path ./bin -Destination "D:\Epic Games\UE_5.4\Engine\Plugins\VisualStudioTools"

- 把 `C:\Users\SUNTING\vc-ue-extensions\bin` 文件夹 - 移动到 `D:\Epic Games\UE_5.4\Engine\Plugins\` - 并改名为 `VisualStudioTools`

我将其放到自己项目下D:\MyGame\Plugins\这样只影响这一个项目

4：配置 HLSL Tools 插件

创建一个配置文件来告诉插件：

1. 你的代码里用了哪些预处理器定义（#define）
2. #include 的文件应该去哪些文件夹找
3. （如果用 Unreal）虚拟路径映射到哪里

步骤 1：创建配置文件

在 shader 文件所在目录（或项目根目录）创建一个名为 shadertoolsconfig.json 的文件

步骤 2：填写配置内容（.josn）

{
  "hlsl.preprocessorDefinitions": {
    "MY_DEFINE": "SomeValue",
    "ANOTHER_DEFINE": 1
  },
  "hlsl.additionalIncludeDirectories": [
    "C:\\你的包含文件目录A",
    "C:\\你的包含文件目录B",
    ".",
    "..\\相对路径目录"
  ],
  "hlsl.virtualDirectoryMappings": {
    "/Project": "C:\\你的UE项目\\Shaders"
  }
}

我自己的：

{
  "hlsl.virtualDirectoryMappings": {
    "/Project": "D:\\unreal_projects\\cppproject\\Shaders",
    "/Engine": "D:\\Epic Games\\UE_5.4\\Engine\\Shaders"
  },
  "hlsl.additionalIncludeDirectories": [
    "D:\\unreal_projects\\cppproject\\Shaders",
    "D:\\Epic Games\\UE_5.4\\Engine\\Shaders",
    "."
  ]
}

### **虚拟目录映射：** -

• `/Project` → 映射到你项目的 Shaders 文件夹
• - `/Engine` → 映射到 UE 引擎的 Shaders 文件夹

关键知识点总结

1. 架构理解
   • UnrealCV采用Socket通信方式，基于客户端-服务器模型
   • UE作为服务器持续监听，Python作为客户端发送命令
2. 流程

   创建C++项目 → 安装UnrealCV插件 → Visual Studio编译 
   → UE Editor PLAY → Python客户端连接 → 发送命令采集图像