 全流程与兼容性修复指南)
1. 项目概述与核心价值最近在折腾一个无人机仿真项目需要用到微软开源的AirSim但发现官方仓库的更新似乎有些滞后对最新的UE5.6引擎支持不够友好。经过一番搜索发现CodexLabs维护的Colosseum项目是一个更活跃的AirSim分支号称对UE5有更好的兼容性。于是我决定在Windows 11系统上用UE5.6引擎完整走一遍Colosseum的编译和运行流程。这个过程远不止是点几下鼠标那么简单它涉及到Visual Studio环境配置、C依赖管理、UE插件编译以及最棘手的UE5.6 API兼容性适配。如果你也正卡在某个编译错误上或者对在Windows上搭建一个可用的、基于最新引擎的AirSim仿真环境感到头疼那么这篇从零开始的踩坑实录或许能帮你省下大把时间。整个流程的核心目标就是让Colosseum这个强大的仿真平台能在你的UE5.6编辑器中顺利跑起来并能够通过Python API进行控制。2. 环境准备与工具链搭建工欲善其事必先利其器。在Windows上编译C项目尤其是像Colosseum这样深度集成Unreal Engine的大型项目一个正确且完整的开发环境是成功的第一步。很多人编译失败问题往往就出在环境准备这一步。2.1 系统与引擎版本选择首先明确我的基础环境操作系统是Windows 11 22H2但Windows 10 21H2及以上版本同样适用。最关键的是Unreal Engine版本我选择了UE5.6。选择这个版本有几个考量一是它是最新的长期支持LTS版本之一稳定性和新特性兼顾二是许多新的项目插件和资产开始以5.6为基准进行开发三是Colosseum项目本身也在向5.6迁移虽然过程中会有兼容性问题但解决了就意味着获得了在新引擎上运行仿真的能力。不建议使用更老的UE5.0或UE4.27因为Colosseum的后续更新可能会逐渐放弃对旧版本的支持。2.2 Visual Studio 2022的精确安装这是整个流程中最关键、也最容易出错的一环。Colosseum的编译脚本和UE5.6的源码构建都强依赖VS2022的特定组件。很多人图省事只安装了默认的“.NET桌面开发”或“使用C的桌面开发”工作负载这往往会导致后续编译时找不到Windows SDK或者MSVC工具链。我的安装步骤如下运行Visual Studio Installer选择Visual Studio 2022 Community专业版或企业版亦可点击“修改”。在工作负载Workloads页面必须勾选“使用C的桌面开发”。这个工作负载包含了基础的编译器、链接器和标准库。这还不够需要切换到“单个组件”Individual components标签页进行精细化勾选。以下是必须安装的组件列表你可以直接搜索并勾选MSVC v143 - VS 2022 C x64/x86 生成工具 (最新)这是编译器的核心版本号v143必须匹配。Windows 10 SDK (10.0.19041.0) 或 Windows 11 SDKUE5.6对SDK版本有要求10.0.19041.0是一个被广泛验证兼容的版本。如果安装列表里有10.0.20348.0或更新版本也可以但建议优先使用19041。C CMake 工具用于CMake项目的支持虽然Colosseum主要用自带的.cmd脚本但安装上无害。对 v143 生成工具最新的 C/CLI 支持一些底层交互可能需要。.NET Framework 4.8 SDK 和 .NET Framework 4.8 目标包AirSim的某些工具或脚本可能依赖.NET。.NET Framework 4.8.1 SDK 和 .NET Framework 4.8.1 目标包同上与4.8 SDK可以共存不冲突。注意安装完成后务必从开始菜单打开“Developer Command Prompt for VS 2022”或“x64 Native Tools Command Prompt for VS 2022”来进行后续的所有命令行操作。直接使用普通的CMD或PowerShell会导致环境变量如cl.exe,link.exe的路径未正确设置从而编译失败。这是一个非常常见的低级错误。2.3 项目目录结构规划清晰的目录结构能避免很多路径相关的麻烦。我推荐如下结构D:\Dev\Simulation\ (或任何你喜欢的路径避免中文和空格) └── Colosseum/ (Colosseum仓库根目录) ├── AirLib/ (AirSim的核心算法库) ├── PythonClient/ (Python API客户端) ├── Unreal/ │ ├── Plugins/ │ │ └── AirSim/ (编译后生成的UE插件) │ └── Environments/ │ └── BlocksV2/ (示例项目) └── build.cmd (核心编译脚本)后文我将使用ColosseumRoot指代Colosseum仓库的根目录。绝对不要把项目放在C:\Program Files或C:\Windows这类需要管理员权限的目录否则在文件生成、删除时会频繁遭遇权限错误。3. 获取源码与首次编译尝试环境就绪后我们开始获取代码并进行第一次编译。这个过程会暴露出依赖缺失和系统环境配置问题。3.1 克隆Colosseum仓库打开之前提到的“Developer Command Prompt for VS 2022”导航到你的工作目录例如D:\Dev\Simulation执行克隆命令。为了确保所有子模块如Eigen一并下载使用--recursive参数是最佳实践git clone --recursive https://github.com/CodexLabsLLC/Colosseum.git cd Colosseum如果网络连接GitHub不畅克隆过程可能会很慢甚至失败。如果--recursive失败你可以先克隆主仓库再手动更新子模块git clone https://github.com/CodexLabsLLC/Colosseum.git cd Colosseum git submodule update --init --recursive3.2 首次运行build.cmd及其典型报错进入Colosseum根目录直接运行其提供的编译脚本cd ColosseumRoot build.cmd这个脚本的任务是编译AirLib库并准备Unreal插件所需的文件。对于很多国内开发者来说十有八九会在这里遇到第一个拦路虎。报错现象脚本运行片刻后提示类似以下错误Setup Eigen dependency for AirLib Submodule ExternalRepositories\Colosseum_Eigen not properly initialized. Try running git submodule update --init Build failed!原因分析Colosseum依赖于一个名为Eigen的C模板库进行矩阵运算该库作为子模块存放在ExternalRepositories\Colosseum_Eigen目录。当网络无法访问GitLabEigen的主仓库时子模块初始化就会失败。即使你成功执行了git submodule update --init --recursive也可能因为网络问题导致这个特定子模块拉取失败。3.3 手动解决Eigen依赖问题既然自动下载不行我们就手动解决。这是绕过网络限制最直接有效的方法。下载Eigen源码你需要Eigen 3.4.0版本。在能正常访问外网的机器上访问https://gitlab.com/libeigen/eigen/-/archive/3.4.0/eigen-3.4.0.zip下载压缩包。如果无法访问GitLab也可以从Gitee等国内镜像站搜索“eigen 3.4.0”进行下载。解压与放置将下载的eigen-3.4.0.zip解压。关键步骤来了你需要将解压后文件夹内的所有内容即Eigen、unsupported目录和CMakeLists.txt等文件直接复制到ColosseumRoot\ExternalRepositories\Colosseum_Eigen\目录下。正确路径ColosseumRoot\ExternalRepositories\Colosseum_Eigen\Eigen\这个Eigen目录里应该直接是Core,Dense等文件夹。错误路径ColosseumRoot\ExternalRepositories\Colosseum_Eigen\eigen-3.4.0\Eigen\多了一层eigen-3.4.0目录脚本会识别失败。验证在命令行中执行dir ColosseumRoot\ExternalRepositories\Colosseum_Eigen\Eigen如果能列出Core、Dense等目录说明放置正确。4. 攻克编译警告与错误解决了Eigen依赖再次运行build.cmd我们进入了下一个“坑”编译器警告被视为错误。这在中文字符集的Windows系统上尤为常见。4.1 解决C4819编码警告错误报错现象编译Eigen头文件时出现大量类似以下的错误warning C4819: 该文件包含不能在当前代码页(936)中表示的字符。请将该文件保存为 Unicode 格式以防止数据丢失。 error C2220: 以下警告被视为错误。这个错误是因为Eigen的某些头文件如Half.h,BFloat16.h中包含UTF-8编码的字符可能是作者名字或特殊注释而中文Windows默认的命令行代码页是GBK936MSVC编译器无法正确识别从而产生C4819警告。又因为项目编译设置将警告视为错误/WX所以升级为C2220导致编译失败。解决方案我们需要在编译时临时改变命令行环境的代码页并告诉编译器忽略特定警告。 在运行build.cmd之前执行以下命令cd ColosseumRoot chcp 65001 set CL/wd4819 build.cmdchcp 65001将当前控制台的代码页切换到UTF-8。set CL/wd4819设置MSVC编译器的命令行参数/wd4819表示禁用disable4819号警告。4.2 解决C4127常量表达式警告错误压掉C4819后很可能立刻遇到下一个类似错误warning C4127: 条件表达式是常量。 error C2220: 以下警告被视为错误。这是Eigen库内部一些条件编译语句触发的警告同样被当成了错误。解决方案我们需要同时忽略C4819和C4127警告并且最好也关闭“将警告视为错误”的选项一劳永逸。使用更完整的命令集cd ColosseumRoot chcp 65001 set CL/wd4819 /wd4127 set _CL_/wd4819 /wd4127 /WX- build.cmdset CL...和set _CL_...CL环境变量用于设置给cl.exe编译器的参数。同时设置CL和_CL_是为了确保在复杂的构建脚本中参数能正确传递。/WX-就是关闭“将警告视为错误”的开关。如果上述方法仍有个别文件报编码错误可以尝试强制指定源码为UTF-8编码cd ColosseumRoot chcp 65001 set CL/utf-8 /wd4819 /wd4127 set _CL_/utf-8 /wd4819 /wd4127 /WX- build.cmd/utf-8参数指示编译器假定源文件是UTF-8编码。4.3 编译成功后的状态当命令执行完毕没有出现红色的错误提示并最终显示编译过程完成时就成功了。你可能会在输出中看到一些“系统找不到指定的文件”或“Could Not Find ...”的提示这通常是编译脚本在尝试清理旧的构建产物如Build、Intermediate文件夹时因为文件不存在而发出的非致命性信息可以忽略。成功的标志是在ColosseumRoot\Unreal\Plugins\AirSim\Source\AirLib\lib\x64\目录下生成了Debug、Release等不同配置的AirLib.lib静态库文件。这表示AirSim的核心库已经编译完成并且相关文件已经被复制到了Unreal插件目录中为下一步在UE编辑器中编译插件做好了准备。5. 在Unreal Editor中编译与运行BlocksV2Colosseum本体编译通过只算成功了一半。接下来我们要在UE5.6中打开示例项目并编译AirSim插件这才是真正的挑战因为UE5.6的API相比之前版本有变动。5.1 生成并打开Visual Studio解决方案进入BlocksV2示例项目的目录ColosseumRoot\Unreal\Environments\BlocksV2。你会看到一个BlocksV2.uproject文件。如果目录下已经存在BlocksV2.sln文件直接双击用Visual Studio 2022打开即可。如果没有右键点击BlocksV2.uproject文件选择“Generate Visual Studio project files”。等待命令完成就会生成对应的.sln解决方案文件。用VS2022打开BlocksV2.sln后注意右上角的编译配置配置选择Development Editor平台选择Win64将BlocksV2设为启动项目右键项目 - “设为启动项目”。建议先进行一次完整的重新生成以确保所有依赖都被正确编译。在VS中点击菜单栏的“生成 - 重新生成解决方案”。5.2 修复UE5.6 API不兼容错误直接编译几乎100%会失败因为Colosseum插件中的部分代码使用了UE5.6中已废弃或更改的API。我们需要手动修改几处关键源码。重要提示修改的是BlocksV2项目内部的插件副本路径是ColosseumRoot\Unreal\Environments\BlocksV2\Plugins\AirSim\Source\而不是Colosseum根目录下的插件模板。5.2.1 修复 PawnSimApi.cpp 中的 LineBatcher 错误错误信息error C2039: “LineBatcher”: 不是 “UWorld” 的成员。 在UE5.6中UWorld::LineBatcher和PersistentLineBatcher成员变量已被移除画线功能应使用DrawDebugLine函数。打开文件BlocksV2Root\Plugins\AirSim\Source\PawnSimApi.cpp。在文件顶部的#include区域添加#include DrawDebugHelpers.h在文件中搜索LineBatcher。你会找到类似下面的代码段params_.pawn-GetWorld()-LineBatcher-DrawLine( params_.pawn-GetActorLocation(), target_location, color, SDPG_World, 10, -1 );将其替换为DrawDebugLine( params_.pawn-GetWorld(), params_.pawn-GetActorLocation(), target_location, color.ToFColor(true), // 关键转换FLinearColor - FColor false, // 是否持久化Persistent -1.0f, // 生命周期-1表示仅当前帧 SDPG_World, 10.0f // 线宽 );注意原color变量通常是FLinearColor类型而DrawDebugLine需要FColor类型因此必须使用color.ToFColor(true)进行转换。true参数表示使用sRGB颜色空间通常能获得更准确的显示效果。5.2.2 修复 WorldSimApi.cpp 中的 PersistentLineBatcher 错误错误信息error C2039: “PersistentLineBatcher”: 不是 “UWorld” 的成员。 修复思路同上。打开文件BlocksV2Root\Plugins\AirSim\Source\WorldSimApi.cpp。在#include区域添加#include DrawDebugHelpers.h。搜索PersistentLineBatcher找到类似代码simmode_-GetWorld()-PersistentLineBatcher-DrawLine( point1, point2, color, SDPG_World, 4, 999999 );替换为DrawDebugLine( simmode_-GetWorld(), point1, point2, color.ToFColor(true), true, // 此处应为true表示持久化线条 999999.0f, // 生命周期很长 SDPG_World, 4.0f );5.2.3 修复 SimHUD.cpp 中的 TObjectPtr 转换错误错误信息error C2440: “初始化”: 无法从“TObjectPtrAPawn”转换为“APawn *”。 在UE5.6中GetPawn()等函数返回的不再是裸指针而是TObjectPtrT这是一种更安全的对象引用包装。我们需要调用其.Get()方法来获取原始指针。打开文件BlocksV2Root\Plugins\AirSim\Source\SimHUD\SimHUD.cpp。找到获取Pawn的代码行通常是auto* pawn player_controller-GetPawn();将其修改为APawn* pawn player_controller-GetPawn().Get(); // 调用.Get()获取指针此外同一文件或附近可能还有将FString转换为std::string的代码在UE5.6中TCHAR_TO_ANSI宏可能有问题建议替换为// 将类似这样的代码 std::string pawn_name std::string(TCHAR_TO_ANSI(*pawn-GetName())); // 替换为 std::string pawn_name(TCHAR_TO_UTF8(*pawn-GetName()));TCHAR_TO_UTF8在跨平台和字符集兼容性上更好。5.3 重新编译与运行完成上述三处修改并保存所有文件后回到Visual Studio再次点击“生成 - 重新生成解决方案”。这次编译应该能顺利通过输出窗口会显示类似“1 成功0 失败”的信息。编译成功后点击工具栏上的“本地Windows调试器”或按F5这将启动Unreal Editor并加载BlocksV2项目。等待编辑器完全打开后在编辑器视口中点击绿色的“播放”Play按钮。如果一切顺利你将看到BlocksV2的默认场景并且可以自由飞行默认按键是WASD控制移动鼠标控制视角。这标志着Colosseum AirSim插件已经在你的UE5.6环境中成功运行6. 配置Python客户端与基础测试AirSim的强大之处在于其Python API允许我们通过脚本控制仿真中的车辆如无人机、汽车。为了让Python能调用我们刚编译好的、最新的Colosseum API我们需要安装本地的Python客户端而不是PyPI上的稳定版。6.1 安装本地PythonClient打开一个新的命令行窗口可以是普通的CMD或PowerShell无需VS开发人员命令提示符导航到Colosseum的PythonClient目录cd ColosseumRoot\PythonClient建议先卸载可能已安装的旧版airsim包避免冲突pip uninstall airsim使用“可编辑模式”-e安装当前目录下的源码包pip install -e .-e参数意味着安装的是一个链接到源码的包后续如果你修改了PythonClient下的源码无需重新安装即可生效。6.2 验证安装与基础连接测试安装完成后创建一个简单的Python脚本来测试连接。首先确认Python环境能找到正确的airsim模块python -c import airsim; print(airsim.__file__)输出路径应该指向ColosseumRoot\PythonClient\airsim\__init__.py这表明你使用的是本地编译的版本。然后创建一个测试脚本test_connection.pyimport airsim import time # 连接到仿真器默认连接到本地localhost:41451 client airsim.MultirotorClient() client.confirmConnection() # 阻塞直到连接成功 print(成功连接到AirSim仿真器) # 解锁并起飞 client.enableApiControl(True) client.armDisarm(True) print(无人机已解锁。) # 起飞到2米高度 client.takeoffAsync().join() print(起飞指令已发送。) time.sleep(2) # 获取并打印当前状态 state client.getMultirotorState() print(f无人机位置: {state.kinematics_estimated.position}) print(f无人机姿态: {state.kinematics_estimated.orientation}) # 降落并上锁 client.landAsync().join() time.sleep(2) client.armDisarm(False) client.enableApiControl(False) print(测试完成无人机已降落。)运行此脚本前请确保UE编辑器中的BlocksV2场景正处于“播放”Play状态。然后在命令行运行python test_connection.py如果脚本能正常打印连接成功信息、控制无人机起飞降落说明整个Colosseum环境——从UE插件到Python API——已经全部打通。7. 常见问题深度排查与进阶技巧即便按照上述步骤操作由于系统环境、软件版本差异你可能还会遇到一些其他问题。这里我汇总了更多可能遇到的“坑”及其解决方案。7.1 编译阶段问题问题1build.cmd执行时提示“cmake不是内部或外部命令”原因CMake没有安装或未添加到系统PATH。解决从CMake官网下载并安装CMake安装时务必勾选“Add CMake to the system PATH for all users”。安装后需要重启命令行窗口。问题2Visual Studio编译时提示“找不到Windows SDK”或“工具集版本不匹配”原因VS安装时遗漏了特定版本的Windows SDK或者项目要求的工具集与已安装的不符。解决重新运行Visual Studio Installer在“单个组件”中搜索并安装对应版本的Windows SDK如10.0.19041.0。对于工具集确保项目属性右键项目-属性-常规中的“平台工具集”设置为“Visual Studio 2022 (v143)”。问题3编译AirSim插件时出现“无法打开包括文件: ‘Eigen/Dense’”原因Eigen头文件路径没有被正确包含。虽然我们手动放置了Eigen但可能编译脚本或项目设置未能正确引用。解决检查ColosseumRoot\build.cmd脚本看其是否正确地设置了Eigen的包含路径。更常见的是需要确保手动放置的Eigen目录结构完全正确如第3.3节所述。可以尝试在VS的项目属性中手动为AirSim插件添加包含目录$(ColosseumRoot)\ExternalRepositories\Colosseum_Eigen。7.2 运行阶段问题问题4点击Play后编辑器崩溃或无人机无响应原因可能是物理引擎冲突、插件加载失败或Python API版本不匹配。排查检查编辑器输出日志Window - Developer Tools - Output Log查看崩溃前的错误信息。确保BlocksV2场景中只有一个“AirSim”插件实例。有时旧的插件缓存会导致冲突可以尝试删除BlocksV2Root\Saved、Binaries、Intermediate文件夹然后右键.uproject文件重新生成项目文件。确认Python脚本中连接的端口与AirSim设置一致。默认是localhost:41451。检查AirSim插件的设置文件BlocksV2Root\Settings\settings.json中ApiServerPort是否为41451。问题5Python脚本能连接但无法控制无人机API控制失败原因最常见的是没有在UE中启用“播放”模式或者无人机在场景中未正确初始化。解决绝对确保UE编辑器处于“播放”模式视图端口有黄色边框。在BlocksV2场景中确保存在一个PlayerStart和一个名为“Flier1”的无人机蓝图这是默认的。你可以从内容浏览器搜索“BP_FlyingPawn”并将其拖入场景。在Python脚本中enableApiControl(True)和armDisarm(True)必须在任何移动命令之前调用。7.3 性能优化与调试技巧技巧1关闭编辑器不必要的功能以提升仿真帧率在UE编辑器中运行仿真性能开销较大。可以尝试在编辑器偏好设置中关闭“实时”Realtime模式下的高保真视觉效果。在“播放”Play设置中勾选“新进程窗口”New Process Window这会在一个独立的、优化过的游戏窗口中运行仿真性能通常更好。降低场景复杂度或使用更简单的网格体替代复杂模型。技巧2使用AirSim的日志功能进行调试AirSim提供了详细的日志。在settings.json中增加以下配置可以将日志输出到文件和控制台{ SeeDocsAt: https://github.com/Microsoft/AirSim/blob/main/docs/settings.md, SettingsVersion: 1.2, SimMode: Multirotor, LogMessagesVisible: true, ApiServerPort: 41451 }在Python脚本中也可以设置日志级别import airsim import logging logging.basicConfig(levellogging.INFO) # 设置日志级别为INFO可看到更多信息 client airsim.MultirotorClient()技巧3将修改后的插件迁移到其他UE项目你为BlocksV2修改的AirSim插件可以复用到你自己的UE5.6项目中。将BlocksV2Root\Plugins\AirSim整个文件夹复制到你项目的Plugins目录下。在你的项目的.uproject文件上右键选择“Generate Visual Studio project files”。打开生成的项目解决方案编译即可。警告不要直接复制Colosseum根目录下Unreal\Plugins\AirSim里的原始插件那里面没有我们为UE5.6做的兼容性修改会导致编译失败。8. 项目总结与核心命令速查回顾整个流程在Windows UE5.6上成功运行Colosseum核心是跨越三道关卡依赖获取关手动解决Eigen、环境配置关VS组件与编译参数、API兼容关修改源码适配UE5.6。这个过程虽然繁琐但每一步都有明确的逻辑和解决方案。一旦打通你就拥有了一个在最新版Unreal Engine上运行的高保真、可编程的机器人仿真平台这对于无人机算法开发、自动驾驶测试等应用来说价值巨大。最后附上整个过程中最常用的命令方便你快速查阅和复现1. 设置环境并编译Colosseum核心库cd ColosseumRoot chcp 65001 set CL/utf-8 /wd4819 /wd4127 set _CL_/utf-8 /wd4819 /wd4127 /WX- build.cmd2. 安装本地Python客户端cd ColosseumRoot\PythonClient pip uninstall airsim pip install -e .3. 验证Python客户端路径python -c import airsim; print(airsim.__file__)4. 清理UE项目缓存遇到奇怪问题时使用手动删除项目目录下的Saved、Binaries、Intermediate、.vs文件夹然后重新生成.sln文件。5. 快速测试连接UE需处于播放模式import airsim client airsim.MultirotorClient() client.confirmConnection() print(连接成功)整个搭建过程像是一次精细的考古与修复工作你需要把来自不同“年代”不同版本依赖和“产地”不同开源项目的部件在Windows和UE5.6这个新平台上重新组装并调试到能运转。过程中每一个报错都不是终点而是一个线索。掌握这套方法后你不仅能搞定Colosseum未来面对其他复杂的C/UE开源项目集成时也会更有底气和思路。
1. 项目概述与核心价值最近在折腾一个无人机仿真项目需要用到微软开源的AirSim但发现官方仓库的更新似乎有些滞后对最新的UE5.6引擎支持不够友好。经过一番搜索发现CodexLabs维护的Colosseum项目是一个更活跃的AirSim分支号称对UE5有更好的兼容性。于是我决定在Windows 11系统上用UE5.6引擎完整走一遍Colosseum的编译和运行流程。这个过程远不止是点几下鼠标那么简单它涉及到Visual Studio环境配置、C依赖管理、UE插件编译以及最棘手的UE5.6 API兼容性适配。如果你也正卡在某个编译错误上或者对在Windows上搭建一个可用的、基于最新引擎的AirSim仿真环境感到头疼那么这篇从零开始的踩坑实录或许能帮你省下大把时间。整个流程的核心目标就是让Colosseum这个强大的仿真平台能在你的UE5.6编辑器中顺利跑起来并能够通过Python API进行控制。2. 环境准备与工具链搭建工欲善其事必先利其器。在Windows上编译C项目尤其是像Colosseum这样深度集成Unreal Engine的大型项目一个正确且完整的开发环境是成功的第一步。很多人编译失败问题往往就出在环境准备这一步。2.1 系统与引擎版本选择首先明确我的基础环境操作系统是Windows 11 22H2但Windows 10 21H2及以上版本同样适用。最关键的是Unreal Engine版本我选择了UE5.6。选择这个版本有几个考量一是它是最新的长期支持LTS版本之一稳定性和新特性兼顾二是许多新的项目插件和资产开始以5.6为基准进行开发三是Colosseum项目本身也在向5.6迁移虽然过程中会有兼容性问题但解决了就意味着获得了在新引擎上运行仿真的能力。不建议使用更老的UE5.0或UE4.27因为Colosseum的后续更新可能会逐渐放弃对旧版本的支持。2.2 Visual Studio 2022的精确安装这是整个流程中最关键、也最容易出错的一环。Colosseum的编译脚本和UE5.6的源码构建都强依赖VS2022的特定组件。很多人图省事只安装了默认的“.NET桌面开发”或“使用C的桌面开发”工作负载这往往会导致后续编译时找不到Windows SDK或者MSVC工具链。我的安装步骤如下运行Visual Studio Installer选择Visual Studio 2022 Community专业版或企业版亦可点击“修改”。在工作负载Workloads页面必须勾选“使用C的桌面开发”。这个工作负载包含了基础的编译器、链接器和标准库。这还不够需要切换到“单个组件”Individual components标签页进行精细化勾选。以下是必须安装的组件列表你可以直接搜索并勾选MSVC v143 - VS 2022 C x64/x86 生成工具 (最新)这是编译器的核心版本号v143必须匹配。Windows 10 SDK (10.0.19041.0) 或 Windows 11 SDKUE5.6对SDK版本有要求10.0.19041.0是一个被广泛验证兼容的版本。如果安装列表里有10.0.20348.0或更新版本也可以但建议优先使用19041。C CMake 工具用于CMake项目的支持虽然Colosseum主要用自带的.cmd脚本但安装上无害。对 v143 生成工具最新的 C/CLI 支持一些底层交互可能需要。.NET Framework 4.8 SDK 和 .NET Framework 4.8 目标包AirSim的某些工具或脚本可能依赖.NET。.NET Framework 4.8.1 SDK 和 .NET Framework 4.8.1 目标包同上与4.8 SDK可以共存不冲突。注意安装完成后务必从开始菜单打开“Developer Command Prompt for VS 2022”或“x64 Native Tools Command Prompt for VS 2022”来进行后续的所有命令行操作。直接使用普通的CMD或PowerShell会导致环境变量如cl.exe,link.exe的路径未正确设置从而编译失败。这是一个非常常见的低级错误。2.3 项目目录结构规划清晰的目录结构能避免很多路径相关的麻烦。我推荐如下结构D:\Dev\Simulation\ (或任何你喜欢的路径避免中文和空格) └── Colosseum/ (Colosseum仓库根目录) ├── AirLib/ (AirSim的核心算法库) ├── PythonClient/ (Python API客户端) ├── Unreal/ │ ├── Plugins/ │ │ └── AirSim/ (编译后生成的UE插件) │ └── Environments/ │ └── BlocksV2/ (示例项目) └── build.cmd (核心编译脚本)后文我将使用ColosseumRoot指代Colosseum仓库的根目录。绝对不要把项目放在C:\Program Files或C:\Windows这类需要管理员权限的目录否则在文件生成、删除时会频繁遭遇权限错误。3. 获取源码与首次编译尝试环境就绪后我们开始获取代码并进行第一次编译。这个过程会暴露出依赖缺失和系统环境配置问题。3.1 克隆Colosseum仓库打开之前提到的“Developer Command Prompt for VS 2022”导航到你的工作目录例如D:\Dev\Simulation执行克隆命令。为了确保所有子模块如Eigen一并下载使用--recursive参数是最佳实践git clone --recursive https://github.com/CodexLabsLLC/Colosseum.git cd Colosseum如果网络连接GitHub不畅克隆过程可能会很慢甚至失败。如果--recursive失败你可以先克隆主仓库再手动更新子模块git clone https://github.com/CodexLabsLLC/Colosseum.git cd Colosseum git submodule update --init --recursive3.2 首次运行build.cmd及其典型报错进入Colosseum根目录直接运行其提供的编译脚本cd ColosseumRoot build.cmd这个脚本的任务是编译AirLib库并准备Unreal插件所需的文件。对于很多国内开发者来说十有八九会在这里遇到第一个拦路虎。报错现象脚本运行片刻后提示类似以下错误Setup Eigen dependency for AirLib Submodule ExternalRepositories\Colosseum_Eigen not properly initialized. Try running git submodule update --init Build failed!原因分析Colosseum依赖于一个名为Eigen的C模板库进行矩阵运算该库作为子模块存放在ExternalRepositories\Colosseum_Eigen目录。当网络无法访问GitLabEigen的主仓库时子模块初始化就会失败。即使你成功执行了git submodule update --init --recursive也可能因为网络问题导致这个特定子模块拉取失败。3.3 手动解决Eigen依赖问题既然自动下载不行我们就手动解决。这是绕过网络限制最直接有效的方法。下载Eigen源码你需要Eigen 3.4.0版本。在能正常访问外网的机器上访问https://gitlab.com/libeigen/eigen/-/archive/3.4.0/eigen-3.4.0.zip下载压缩包。如果无法访问GitLab也可以从Gitee等国内镜像站搜索“eigen 3.4.0”进行下载。解压与放置将下载的eigen-3.4.0.zip解压。关键步骤来了你需要将解压后文件夹内的所有内容即Eigen、unsupported目录和CMakeLists.txt等文件直接复制到ColosseumRoot\ExternalRepositories\Colosseum_Eigen\目录下。正确路径ColosseumRoot\ExternalRepositories\Colosseum_Eigen\Eigen\这个Eigen目录里应该直接是Core,Dense等文件夹。错误路径ColosseumRoot\ExternalRepositories\Colosseum_Eigen\eigen-3.4.0\Eigen\多了一层eigen-3.4.0目录脚本会识别失败。验证在命令行中执行dir ColosseumRoot\ExternalRepositories\Colosseum_Eigen\Eigen如果能列出Core、Dense等目录说明放置正确。4. 攻克编译警告与错误解决了Eigen依赖再次运行build.cmd我们进入了下一个“坑”编译器警告被视为错误。这在中文字符集的Windows系统上尤为常见。4.1 解决C4819编码警告错误报错现象编译Eigen头文件时出现大量类似以下的错误warning C4819: 该文件包含不能在当前代码页(936)中表示的字符。请将该文件保存为 Unicode 格式以防止数据丢失。 error C2220: 以下警告被视为错误。这个错误是因为Eigen的某些头文件如Half.h,BFloat16.h中包含UTF-8编码的字符可能是作者名字或特殊注释而中文Windows默认的命令行代码页是GBK936MSVC编译器无法正确识别从而产生C4819警告。又因为项目编译设置将警告视为错误/WX所以升级为C2220导致编译失败。解决方案我们需要在编译时临时改变命令行环境的代码页并告诉编译器忽略特定警告。 在运行build.cmd之前执行以下命令cd ColosseumRoot chcp 65001 set CL/wd4819 build.cmdchcp 65001将当前控制台的代码页切换到UTF-8。set CL/wd4819设置MSVC编译器的命令行参数/wd4819表示禁用disable4819号警告。4.2 解决C4127常量表达式警告错误压掉C4819后很可能立刻遇到下一个类似错误warning C4127: 条件表达式是常量。 error C2220: 以下警告被视为错误。这是Eigen库内部一些条件编译语句触发的警告同样被当成了错误。解决方案我们需要同时忽略C4819和C4127警告并且最好也关闭“将警告视为错误”的选项一劳永逸。使用更完整的命令集cd ColosseumRoot chcp 65001 set CL/wd4819 /wd4127 set _CL_/wd4819 /wd4127 /WX- build.cmdset CL...和set _CL_...CL环境变量用于设置给cl.exe编译器的参数。同时设置CL和_CL_是为了确保在复杂的构建脚本中参数能正确传递。/WX-就是关闭“将警告视为错误”的开关。如果上述方法仍有个别文件报编码错误可以尝试强制指定源码为UTF-8编码cd ColosseumRoot chcp 65001 set CL/utf-8 /wd4819 /wd4127 set _CL_/utf-8 /wd4819 /wd4127 /WX- build.cmd/utf-8参数指示编译器假定源文件是UTF-8编码。4.3 编译成功后的状态当命令执行完毕没有出现红色的错误提示并最终显示编译过程完成时就成功了。你可能会在输出中看到一些“系统找不到指定的文件”或“Could Not Find ...”的提示这通常是编译脚本在尝试清理旧的构建产物如Build、Intermediate文件夹时因为文件不存在而发出的非致命性信息可以忽略。成功的标志是在ColosseumRoot\Unreal\Plugins\AirSim\Source\AirLib\lib\x64\目录下生成了Debug、Release等不同配置的AirLib.lib静态库文件。这表示AirSim的核心库已经编译完成并且相关文件已经被复制到了Unreal插件目录中为下一步在UE编辑器中编译插件做好了准备。5. 在Unreal Editor中编译与运行BlocksV2Colosseum本体编译通过只算成功了一半。接下来我们要在UE5.6中打开示例项目并编译AirSim插件这才是真正的挑战因为UE5.6的API相比之前版本有变动。5.1 生成并打开Visual Studio解决方案进入BlocksV2示例项目的目录ColosseumRoot\Unreal\Environments\BlocksV2。你会看到一个BlocksV2.uproject文件。如果目录下已经存在BlocksV2.sln文件直接双击用Visual Studio 2022打开即可。如果没有右键点击BlocksV2.uproject文件选择“Generate Visual Studio project files”。等待命令完成就会生成对应的.sln解决方案文件。用VS2022打开BlocksV2.sln后注意右上角的编译配置配置选择Development Editor平台选择Win64将BlocksV2设为启动项目右键项目 - “设为启动项目”。建议先进行一次完整的重新生成以确保所有依赖都被正确编译。在VS中点击菜单栏的“生成 - 重新生成解决方案”。5.2 修复UE5.6 API不兼容错误直接编译几乎100%会失败因为Colosseum插件中的部分代码使用了UE5.6中已废弃或更改的API。我们需要手动修改几处关键源码。重要提示修改的是BlocksV2项目内部的插件副本路径是ColosseumRoot\Unreal\Environments\BlocksV2\Plugins\AirSim\Source\而不是Colosseum根目录下的插件模板。5.2.1 修复 PawnSimApi.cpp 中的 LineBatcher 错误错误信息error C2039: “LineBatcher”: 不是 “UWorld” 的成员。 在UE5.6中UWorld::LineBatcher和PersistentLineBatcher成员变量已被移除画线功能应使用DrawDebugLine函数。打开文件BlocksV2Root\Plugins\AirSim\Source\PawnSimApi.cpp。在文件顶部的#include区域添加#include DrawDebugHelpers.h在文件中搜索LineBatcher。你会找到类似下面的代码段params_.pawn-GetWorld()-LineBatcher-DrawLine( params_.pawn-GetActorLocation(), target_location, color, SDPG_World, 10, -1 );将其替换为DrawDebugLine( params_.pawn-GetWorld(), params_.pawn-GetActorLocation(), target_location, color.ToFColor(true), // 关键转换FLinearColor - FColor false, // 是否持久化Persistent -1.0f, // 生命周期-1表示仅当前帧 SDPG_World, 10.0f // 线宽 );注意原color变量通常是FLinearColor类型而DrawDebugLine需要FColor类型因此必须使用color.ToFColor(true)进行转换。true参数表示使用sRGB颜色空间通常能获得更准确的显示效果。5.2.2 修复 WorldSimApi.cpp 中的 PersistentLineBatcher 错误错误信息error C2039: “PersistentLineBatcher”: 不是 “UWorld” 的成员。 修复思路同上。打开文件BlocksV2Root\Plugins\AirSim\Source\WorldSimApi.cpp。在#include区域添加#include DrawDebugHelpers.h。搜索PersistentLineBatcher找到类似代码simmode_-GetWorld()-PersistentLineBatcher-DrawLine( point1, point2, color, SDPG_World, 4, 999999 );替换为DrawDebugLine( simmode_-GetWorld(), point1, point2, color.ToFColor(true), true, // 此处应为true表示持久化线条 999999.0f, // 生命周期很长 SDPG_World, 4.0f );5.2.3 修复 SimHUD.cpp 中的 TObjectPtr 转换错误错误信息error C2440: “初始化”: 无法从“TObjectPtrAPawn”转换为“APawn *”。 在UE5.6中GetPawn()等函数返回的不再是裸指针而是TObjectPtrT这是一种更安全的对象引用包装。我们需要调用其.Get()方法来获取原始指针。打开文件BlocksV2Root\Plugins\AirSim\Source\SimHUD\SimHUD.cpp。找到获取Pawn的代码行通常是auto* pawn player_controller-GetPawn();将其修改为APawn* pawn player_controller-GetPawn().Get(); // 调用.Get()获取指针此外同一文件或附近可能还有将FString转换为std::string的代码在UE5.6中TCHAR_TO_ANSI宏可能有问题建议替换为// 将类似这样的代码 std::string pawn_name std::string(TCHAR_TO_ANSI(*pawn-GetName())); // 替换为 std::string pawn_name(TCHAR_TO_UTF8(*pawn-GetName()));TCHAR_TO_UTF8在跨平台和字符集兼容性上更好。5.3 重新编译与运行完成上述三处修改并保存所有文件后回到Visual Studio再次点击“生成 - 重新生成解决方案”。这次编译应该能顺利通过输出窗口会显示类似“1 成功0 失败”的信息。编译成功后点击工具栏上的“本地Windows调试器”或按F5这将启动Unreal Editor并加载BlocksV2项目。等待编辑器完全打开后在编辑器视口中点击绿色的“播放”Play按钮。如果一切顺利你将看到BlocksV2的默认场景并且可以自由飞行默认按键是WASD控制移动鼠标控制视角。这标志着Colosseum AirSim插件已经在你的UE5.6环境中成功运行6. 配置Python客户端与基础测试AirSim的强大之处在于其Python API允许我们通过脚本控制仿真中的车辆如无人机、汽车。为了让Python能调用我们刚编译好的、最新的Colosseum API我们需要安装本地的Python客户端而不是PyPI上的稳定版。6.1 安装本地PythonClient打开一个新的命令行窗口可以是普通的CMD或PowerShell无需VS开发人员命令提示符导航到Colosseum的PythonClient目录cd ColosseumRoot\PythonClient建议先卸载可能已安装的旧版airsim包避免冲突pip uninstall airsim使用“可编辑模式”-e安装当前目录下的源码包pip install -e .-e参数意味着安装的是一个链接到源码的包后续如果你修改了PythonClient下的源码无需重新安装即可生效。6.2 验证安装与基础连接测试安装完成后创建一个简单的Python脚本来测试连接。首先确认Python环境能找到正确的airsim模块python -c import airsim; print(airsim.__file__)输出路径应该指向ColosseumRoot\PythonClient\airsim\__init__.py这表明你使用的是本地编译的版本。然后创建一个测试脚本test_connection.pyimport airsim import time # 连接到仿真器默认连接到本地localhost:41451 client airsim.MultirotorClient() client.confirmConnection() # 阻塞直到连接成功 print(成功连接到AirSim仿真器) # 解锁并起飞 client.enableApiControl(True) client.armDisarm(True) print(无人机已解锁。) # 起飞到2米高度 client.takeoffAsync().join() print(起飞指令已发送。) time.sleep(2) # 获取并打印当前状态 state client.getMultirotorState() print(f无人机位置: {state.kinematics_estimated.position}) print(f无人机姿态: {state.kinematics_estimated.orientation}) # 降落并上锁 client.landAsync().join() time.sleep(2) client.armDisarm(False) client.enableApiControl(False) print(测试完成无人机已降落。)运行此脚本前请确保UE编辑器中的BlocksV2场景正处于“播放”Play状态。然后在命令行运行python test_connection.py如果脚本能正常打印连接成功信息、控制无人机起飞降落说明整个Colosseum环境——从UE插件到Python API——已经全部打通。7. 常见问题深度排查与进阶技巧即便按照上述步骤操作由于系统环境、软件版本差异你可能还会遇到一些其他问题。这里我汇总了更多可能遇到的“坑”及其解决方案。7.1 编译阶段问题问题1build.cmd执行时提示“cmake不是内部或外部命令”原因CMake没有安装或未添加到系统PATH。解决从CMake官网下载并安装CMake安装时务必勾选“Add CMake to the system PATH for all users”。安装后需要重启命令行窗口。问题2Visual Studio编译时提示“找不到Windows SDK”或“工具集版本不匹配”原因VS安装时遗漏了特定版本的Windows SDK或者项目要求的工具集与已安装的不符。解决重新运行Visual Studio Installer在“单个组件”中搜索并安装对应版本的Windows SDK如10.0.19041.0。对于工具集确保项目属性右键项目-属性-常规中的“平台工具集”设置为“Visual Studio 2022 (v143)”。问题3编译AirSim插件时出现“无法打开包括文件: ‘Eigen/Dense’”原因Eigen头文件路径没有被正确包含。虽然我们手动放置了Eigen但可能编译脚本或项目设置未能正确引用。解决检查ColosseumRoot\build.cmd脚本看其是否正确地设置了Eigen的包含路径。更常见的是需要确保手动放置的Eigen目录结构完全正确如第3.3节所述。可以尝试在VS的项目属性中手动为AirSim插件添加包含目录$(ColosseumRoot)\ExternalRepositories\Colosseum_Eigen。7.2 运行阶段问题问题4点击Play后编辑器崩溃或无人机无响应原因可能是物理引擎冲突、插件加载失败或Python API版本不匹配。排查检查编辑器输出日志Window - Developer Tools - Output Log查看崩溃前的错误信息。确保BlocksV2场景中只有一个“AirSim”插件实例。有时旧的插件缓存会导致冲突可以尝试删除BlocksV2Root\Saved、Binaries、Intermediate文件夹然后右键.uproject文件重新生成项目文件。确认Python脚本中连接的端口与AirSim设置一致。默认是localhost:41451。检查AirSim插件的设置文件BlocksV2Root\Settings\settings.json中ApiServerPort是否为41451。问题5Python脚本能连接但无法控制无人机API控制失败原因最常见的是没有在UE中启用“播放”模式或者无人机在场景中未正确初始化。解决绝对确保UE编辑器处于“播放”模式视图端口有黄色边框。在BlocksV2场景中确保存在一个PlayerStart和一个名为“Flier1”的无人机蓝图这是默认的。你可以从内容浏览器搜索“BP_FlyingPawn”并将其拖入场景。在Python脚本中enableApiControl(True)和armDisarm(True)必须在任何移动命令之前调用。7.3 性能优化与调试技巧技巧1关闭编辑器不必要的功能以提升仿真帧率在UE编辑器中运行仿真性能开销较大。可以尝试在编辑器偏好设置中关闭“实时”Realtime模式下的高保真视觉效果。在“播放”Play设置中勾选“新进程窗口”New Process Window这会在一个独立的、优化过的游戏窗口中运行仿真性能通常更好。降低场景复杂度或使用更简单的网格体替代复杂模型。技巧2使用AirSim的日志功能进行调试AirSim提供了详细的日志。在settings.json中增加以下配置可以将日志输出到文件和控制台{ SeeDocsAt: https://github.com/Microsoft/AirSim/blob/main/docs/settings.md, SettingsVersion: 1.2, SimMode: Multirotor, LogMessagesVisible: true, ApiServerPort: 41451 }在Python脚本中也可以设置日志级别import airsim import logging logging.basicConfig(levellogging.INFO) # 设置日志级别为INFO可看到更多信息 client airsim.MultirotorClient()技巧3将修改后的插件迁移到其他UE项目你为BlocksV2修改的AirSim插件可以复用到你自己的UE5.6项目中。将BlocksV2Root\Plugins\AirSim整个文件夹复制到你项目的Plugins目录下。在你的项目的.uproject文件上右键选择“Generate Visual Studio project files”。打开生成的项目解决方案编译即可。警告不要直接复制Colosseum根目录下Unreal\Plugins\AirSim里的原始插件那里面没有我们为UE5.6做的兼容性修改会导致编译失败。8. 项目总结与核心命令速查回顾整个流程在Windows UE5.6上成功运行Colosseum核心是跨越三道关卡依赖获取关手动解决Eigen、环境配置关VS组件与编译参数、API兼容关修改源码适配UE5.6。这个过程虽然繁琐但每一步都有明确的逻辑和解决方案。一旦打通你就拥有了一个在最新版Unreal Engine上运行的高保真、可编程的机器人仿真平台这对于无人机算法开发、自动驾驶测试等应用来说价值巨大。最后附上整个过程中最常用的命令方便你快速查阅和复现1. 设置环境并编译Colosseum核心库cd ColosseumRoot chcp 65001 set CL/utf-8 /wd4819 /wd4127 set _CL_/utf-8 /wd4819 /wd4127 /WX- build.cmd2. 安装本地Python客户端cd ColosseumRoot\PythonClient pip uninstall airsim pip install -e .3. 验证Python客户端路径python -c import airsim; print(airsim.__file__)4. 清理UE项目缓存遇到奇怪问题时使用手动删除项目目录下的Saved、Binaries、Intermediate、.vs文件夹然后重新生成.sln文件。5. 快速测试连接UE需处于播放模式import airsim client airsim.MultirotorClient() client.confirmConnection() print(连接成功)整个搭建过程像是一次精细的考古与修复工作你需要把来自不同“年代”不同版本依赖和“产地”不同开源项目的部件在Windows和UE5.6这个新平台上重新组装并调试到能运转。过程中每一个报错都不是终点而是一个线索。掌握这套方法后你不仅能搞定Colosseum未来面对其他复杂的C/UE开源项目集成时也会更有底气和思路。
