UE+AirSim无人机仿真：从环境搭建到多机编队实战

简介：围绕虚幻引擎与AirSim构建的无人机作战仿真环境，这份资源提供完整项目源码与配套文档，面向人工智能、自动化、电子信息、物联网等专业的学生与开发者，可用于毕业设计、课程设计、作业或项目初期演示，也方便在源码基础上升级功能或二次开发，兼顾小白学习进阶。压缩包共162个文件，整体约93.22MB，以Python源码和pyc编译文件为主，同时包含xml/yml配置、Matlab辅助脚本、TensorBoard事件日志、说明文档和GIF演示动图，可覆盖环境配置、仿真运行、任务设定、训练记录与结果可视化等环节。资源内置详细说明文档，并提供“无人机突防”等任务配置文件，目录结构清晰，便于按模块检索；即便缺少完整Python解释器，也可通过pyc调用部分编译模块。两个GIF录屏则能直观展示任务执行过程，降低上手门槛。目前已有180人学习或下载，适合搭建定制化无人机作战场景、开展相关仿真训练的读者参考。

1. 从真机到仿真：无人机作战环境为什么先用 UE + AirSim 搭

基于虚幻引擎和 AirSim 的仿真系统，我去年拆完用到现在，最大的感受是：它把无人机作战场景的验证成本直接打下来了。当时接了个多无人机协同搜索的任务，方案要求先把路径规划、视觉感知和编队逻辑在仿真里跑通才让上真机。直接飞四轴真机测一遍的代价很现实——机架、动力、机载电脑加保险，轻松五位数预算，炸一次机后面一周排期全废。

用虚幻引擎加 AirSim 搭定制化无人机作战仿真系统，是目前最接近真机的验证路径：无人机动力学、相机、激光雷达全在一个可交互的三维场景里，还能用 Python 直接下发飞控指令，软件栈和真机几乎同构。这套资料把 UE 工程、AirSim 编译产物、Python 控制脚本和详细文档打包齐全，场景、车辆、传感器配置都是现成可改的。

适合做无人机路径规划、视觉感知和集群算法的开发者，尤其是需要反复验证、大量重复实验，又不想一直烧预算飞真机的人。这套环境能把验证周期从周压缩到小时，前提是你先把环境对齐，这正是下一章要解决的事。

2. 环境搭建三件套：UE 版本配对、AirSim 编译与 Python 连通性

拿到资源包别急着解压就开跑，第一步是把环境版本对齐。AirSim 对版本极度敏感，UE 差一个次版本号，编译好的插件可能直接加载失败，报错只给一句 "Plugin is incompatible"，排查起来跟玄学一样。我拆这套资料时，先翻文档目录里的版本说明和根目录 README，确认配套的引擎版本和 AirSim 分支，再决定是直接用现成二进制还是重新编译。这一步省下来的时间，远大于后面任何一个环节。

2.1 版本配对：UE4.27 稳定版还是 UE5 开发版

AirSim 的发布节奏和 UE 的版本更新并不同步。官方 Release 分支长期维护的是 UE4.27，这套组合最稳，文档、社区问答和 ROS 桥接方案全都基于它；UE5 需要自己拉 master 分支编译，能吃到 Lumen 光照和更好的植被渲染，适合视觉感知类任务，但会多出一堆编译环境上的坑。我一般建议：目标是飞控算法、路径规划、多机协同验证的，用 UE4.27 + Release 分支；目标是视觉感知、要拿高渲染质量做数据集的，再上 UE5。

资源包里的 UE 工程如果标注的是 4.27，配套的 AirSim 二进制也应该对应 1.8 系列。不要拿 UE5 的工程去硬开 4.27 的编辑器，引擎版本迁移会触发蓝图引用失效，迁移完一堆节点标红，等于整个场景重来，连后悔药都没得吃。

2.2 编译并挂载 AirSim 插件到 UE 工程

资源包通常给两种形态：一种是编译好的 Plugins/AirSim 文件夹，直接丢进工程根目录就能加载；另一种只给源码和文档，需要自己编译。就算给了现成二进制，如果对方机器的编译环境和你的不一致，也建议重编一遍，避免编辑器右下角持续弹 "Plugin 'AirSim' failed to load"。

# 拉取 AirSim 源码并切换到与 UE 匹配的分支 git clone https://github.com/microsoft/AirSim.git cd AirSim git checkout v1.8.1 # Windows 下编译，--Clean 会清掉历史中间产物，避免增量缓存冲突 ./build.cmd --Clean # 把编译好的插件拷进 UE 工程（Linux 用 build.sh，参数一致） cp -r Unreal/Plugins/AirSim /path/to/your/Project/Plugins/

build.cmd 做的事是把 Unreal/Plugins/AirSim 编译成 UE 能识别的模块，最后一步拷贝决定了 UE 工程能不能挂载这个插件。注意目标路径是工程根目录下的 Plugins/，不是 Content/。挂载成功后，编辑器菜单栏会出现 AirSim 专属菜单项；还有一种快速验证方法：打开工程后看 Output Log 里有没有 AirSim 的初始化日志，有就说明插件加载成功了。

2.3 settings.json 与 Python 接口连通性验证

AirSim 的运行时配置几乎全在 Documents/AirSim/settings.json，引擎工程本身不存这些参数。SimMode、车辆类型、传感器、时钟倍速全由它控制。先把最简配置写进去，能跑通再逐步叠加。

{ "SettingsVersion": 1.2, "SimMode": "Multirotor", "ClockSpeed": 1.0, "Vehicles": { "drone1": { "VehicleType": "SimpleFlight", "DefaultVehicleState": "Armed" } } }

SettingsVersion 和 SimMode 是必填项。SimMode 填 Multirotor 才有完整的多旋翼动力学，填 ComputerVision 就退化成纯视觉模式，物理和旋翼全被拿掉。Vehicles 里的 VehicleType 用 SimpleFlight 表示内置简易飞控，不需要外部控制器；后面接 PX4 固件时再改成 PX4。

连通性验证脚本很短，但每次搭新环境都建议先跑一遍：

import airsim client = airsim.MultirotorClient() client.confirmConnection() # 未就绪时自动重试，默认最多 60 秒 print("vehicles:", client.getVehicleNames()) state = client.getMultirotorState() print("position:", state.kinematics_estimated.position)

confirmConnection 是关键，它不是简单尝试一次连接，而是轮询等待仿真环境就绪，所以你会看到脚本先挂起一会儿再打印结果。getVehicleNames 用来和 settings.json 对照，确认 drone1 是否被正确识别；如果返回空列表，说明车辆配置没加载成功，先回头查 settings 文件的位置和 JSON 语法。这一关过了，后面的 Python 控制脚本才有意义。

3. 用 Python 下发飞控指令：从单机起飞到多机编队的完整链路

环境连通之后，核心玩法就是用 Python 控制无人机。AirSim 的 API 设计成和真实飞控的指令序列一一对应：接管、解锁、起飞、平移、悬停、降落。把这条调用链吃透，多机和传感器部分都是它的延伸。

3.1 单机控制的完整调用链

import airsim import time client = airsim.MultirotorClient() client.confirmConnection() # 1. 接管控制权，否则内置自动飞控会覆盖外部指令 client.enableApiControl(True) # 2. 解锁电机，和真机解锁逻辑一致 client.armDisarm(True) # 3. 起飞到默认高度（约 1 米），超时 10 秒 client.takeoffAsync(timeout_sec=10).join() # 4. 以 5 m/s 向 x 正方向飞 3 秒，z 用 -2 表示爬到 2 米高度 client.moveByVelocityAsync(5, 0, -2, duration=3).join() time.sleep(1) client.hoverAsync().join() client.landAsync(timeout_sec=20).join() client.armDisarm(False) client.enableApiControl(False)

moveByVelocityAsync 的四个参数是 NED 坐标系下的三轴速度加持续时间。注意 AirSim 全部用 NED，z 轴朝下，所以向上飞是负值，这个坐标系是后面最常翻车的地方，第五章专门展开。takeoffAsync 返回的是 Future，.join() 是阻塞等待它完成；不 join 直接发下一条指令，动作会叠在一起，轻则轨迹乱飞，重则直接触发坠机判定。我习惯每个动作后面都跟 join，慢半秒无所谓，指令顺序错乱才是大忌。

3.2 多机编队：settings 定义车辆池，Python 按名字驱动

多机场景不需要额外写集群框架，AirSim 天然支持多车辆，前提是 settings.json 里把每台车的初始位置和默认状态都定义好：

{ "SettingsVersion": 1.2, "SimMode": "Multirotor", "Vehicles": { "drone1": { "VehicleType": "SimpleFlight", "DefaultVehicleState": "Armed", "Position": {"x": 0, "y": 0, "z": 0} }, "drone2": { "VehicleType": "SimpleFlight", "DefaultVehicleState": "Armed", "Position": {"x": 5, "y": 0, "z": 0} } } }

Position 是车辆出生点，单位是米，坐标偏移要足够大，否则起飞时旋翼会互相穿透。Python 侧给每个 vehicle_name 建一个客户端实例，AirSim 内部按名字路由指令：

import airsim c1 = airsim.MultirotorClient(vehicle_name="drone1") c2 = airsim.MultirotorClient(vehicle_name="drone2") c1.confirmConnection() c2.confirmConnection() # 编队起飞：两机同时解锁、同时起飞 for c in (c1, c2): c.enableApiControl(True) c.armDisarm(True) c.takeoffAsync(timeout_sec=10).join() # 编队平移：保持 5 米的 y 向间距，整体向前推进 c1.moveByVelocityAsync(5, 0, -3, duration=10).join() c2.moveByVelocityAsync(5, 0, -3, duration=10).join()

这里有一个实战经验：多个 MultirotorClient 实例各自 confirmConnection 是可以的，但尽量不要在多个线程里同时对同一台车下发指令。AirSim 对同一车辆的指令是串行处理的，多线程并不会加速，只会把指令顺序打乱。真要做分布式协同，我一般在主线程里按时间片轮询，或者用 asyncio 把指令按 tick 对齐下发，否则编队间距会越跑越偏。

3.3 传感器参数：相机、激光雷达和 IMU 的采集配置

作战场景里视觉和感知是最重要的载荷。AirSim 的传感器参数也在 settings.json 里按车辆配置，先给相机和激光雷达都加上：

"Camera": { "CaptureSettings": [ { "ImageType": 0, "Width": 1280, "Height": 720, "FOV_Horizontal": 90, "AutoExposureSpeed": 3 } ] }, "Lidar": { "NumberOfLasers": 16, "PointsPerSecond": 100000, "Range": 50, "HorizontalFOVStart": -180, "HorizontalFOVEnd": 180, "VerticalFOVStart": -15, "VerticalFOVEnd": 15 }

ImageType 0 是场景相机，1 是深度，2 是分割，3 是表面法线，做视觉感知时深度图和分割图要单独开通道。激光雷达参数直接影响点云密度和避障表现——16 线、10 万点每秒、50 米探测距离是低空场景的起步配置；如果场景里有大量细小目标，建议把线数提到 32，否则 50 米外的电线杆只会被扫到一两帧，算法根本反应不过来。

调用端读取数据的代码：

import airsim import numpy as np client = airsim.MultirotorClient() client.confirmConnection() # 请求场景图和深度图，超时 10 秒 responses = client.simGetImages([ airsim.ImageRequest("0", airsim.ImageType.Scene, False, False), airsim.ImageRequest("0", airsim.ImageType.DepthPlanar, True, False) ]) for resp in responses: if resp.pixels_as_float: img = np.array(resp.image_data_float, dtype=np.float32).reshape(resp.height, resp.width) else: img = np.frombuffer(resp.image_data_uint8, dtype=np.uint8).reshape(resp.height, resp.width, 3)

simGetImages 第二个参数对应相机的 ExternalID，默认 "0" 是机载主相机。深度图要设 True 的 pixels_as_float，拿到的是 float32 的深度值，单位是米；场景图则是 uint8 的 RGB。两张图的分辨率由 CaptureSettings 里的 Width 和 Height 决定，和 UE 视口分辨率无关，这点别搞混。

4. 定制化作战场景：地形掩体、动态目标与任务触发器

仿真跑通以后，真正拉开差距的是场景定制能力。默认的街区场景拿来验证飞控没问题，但做作战任务验证，需要的是符合任务设定的地形、掩体、目标和天气。这块和 UE 编辑器直接相关，也是这套资料的核心值钱部分。

4.1 场景搭建流程：地形、建筑掩体与布防点

作战环境里，无人机通常要在低空穿行，地形起伏和建筑掩体会直接改变路径规划结果。UE 编辑器里搭建的常见做法是先用 Landscape 工具拉出任务区域地形，再在目标区域放置建筑静态网格作为掩体，最后在关键位置摆好 PlayerStart。AirSim 对场景没有特殊要求，普通 UE 关卡就能跑，但有几个注意点：

1. 无人机出生点区域要平整，避免起飞时初始姿态异常。
2. 掩体高度要高于巡航高度，不然路径规划算法不会把掩体纳入避障考虑。
3. 场景命名用英文和数字，避免中文文件名在打包和路径引用时出问题。

资源包里如果带了现成的 .umap 关卡，直接把它设成默认关卡就行。如果是从空白场景开始，记得在关卡加载后刷新 AirSim 的 NavMesh，否则后续用路径跟随接口时会提示找不到可行路径。场景层面还有一个常用技巧：把目标区用 Trigger Volume 框起来，无人机进入触发区就改变任务状态。这个可以直接在 UE 蓝图里做，也可以在 Python 端用 simGetObjectPose 轮询判断，后者改起来更方便，不需要反复进编辑器。

4.2 用 API 动态生成与移动目标

静态场景测完，要验证作战任务就得有动态目标。AirSim 提供了运行时生成和移动物体的能力，不用回编辑器改场景：

import airsim client = airsim.MultirotorClient() client.confirmConnection() # 动态生成目标物体，碰撞开启，网格用场景里已有的资产 pose = airsim.Pose(airsim.Vector3r(20, 10, 0), airsim.Quaternionr()) obj = client.simSpawnObject( "target_01", "/Game/StarterContent/Props/SM_Shelf", pose, scale=airsim.Vector3r(1, 1, 1), physics_enabled=True ) print("spawned:", obj)

simSpawnObject 的第一个参数是物体在场景中的名字，第二个是资产路径，必须是 Content 下已有资源。physics_enabled 设 True 后物体受重力影响，适合投掷、坠落类任务；设 False 则是按固定锚点摆放。动态目标的移动我一般配合 simSetObjectPose 在每个 tick 更新位置，模拟移动的车辆或人员。注意高频更新 pose 时，物理引擎可能来不及结算碰撞，目标速度超过 10 m/s 建议直接用 moveToPositionAsync 来驱动。

4.3 路径规划与避障算法的仿真验证

路径规划是这套环境的重点应用场景。常见做法是先在离线阶段用 RRT 或 A* 生成一条全局路径，再把路径点逐个发给 AirSim 执行。AirSim 给的接口是 moveToPositionAsync，按航点串起来就是一个完整的路径跟随器：

import airsim waypoints = [ (10, 0, -10), (15, 8, -12), (5, 15, -10), (0, 0, -8) ] client = airsim.MultirotorClient() client.confirmConnection() client.enableApiControl(True) client.armDisarm(True) client.takeoffAsync(timeout_sec=10).join() for x, y, z in waypoints: # velocity 5 m/s，每段加超时保护，防止飞控卡在某个航点 client.moveToPositionAsync(x, y, z, velocity=5, timeout_sec=20).join() client.hoverAsync().join()

moveToPositionAsync 的参数顺序是 xyz 坐标、速度、超时，z 依然用 NED 负值，所以高度 10 米写成 -10。timeout_sec 很关键：如果目标点在障碍物后面，飞控会因为碰撞保护一直悬停，没有超时保护的话整个脚本就挂在那里不走了。航点疏密直接影响验证效果——稀疏航点下轨迹会被飞控拉直，稠密航点下才是真正的路径跟随测试，我一般把相邻航点间距控制在 5 米以内，转弯处加密到 2 米。

避障算法验证通常和传感器挂钩：激光雷达点云做局部避障，路径点只提供全局指引。这种组合在 AirSim 里有一个典型坑，下一章专门讲。

5. 避坑手册：坐标系混用、时钟倍速漂移与连接超时

这套环境用下来，真正拖慢进度的不是功能缺失，而是几个隐蔽的配置和环境问题。下面五条是反复踩过的，按现象、原因、解决写清楚，希望对得上号。

5.1 NED 和 ENU 坐标系混用：无人机直接朝着反方向飞

现象：把真机上用的路径点直接搬进 AirSim，发现无人机 z 方向反着来，飞控指令给的上升变成下降，甚至直接撞地。

原因：AirSim 沿用航空领域的 NED 坐标系，z 轴朝下；而 ROS 和大部分地图库用 ENU，z 朝上。真机代码里 +z 是上升，到 AirSim 里就变成下沉，两套体系混着写就会出现这个问题。

解决：在接入层统一做一次坐标转换，所有交给 AirSim 的位置和速度都过一遍 NED 映射。我一般在项目里封装一个 convert_to_ned 函数，入口收 ENU，出口只出 NED，其他模块完全不感知。

注意：moveByVelocityAsync 和 moveToPositionAsync 的 z 参数都是 NED 语义，负值才是上升。方向对了，后续才谈得上精度。

5.2 ClockSpeed 调高后物理漂移加剧

现象：为了加快实验进度把 ClockSpeed 设成 3 或 5，跑起来后发现无人机轨迹比 1.0 时抖动明显，悬停时反复振荡。

原因：ClockSpeed 是时间倍速，物理引擎的步长被压缩，控制器的更新频率跟不上速度，等效于真机上控制周期变得不稳定。你加速了世界，但飞控的反应没有等比加快。

解决：ClockSpeed 维持在 1.0，数据采样和算法验证都不要用加速解决。真要缩短实验时间，把场景做小、把航点间距缩短，比调快时钟更有效。多机同步测试时，多个实例的 ClockSpeed 不一致还会导致时间基准错乱，这个尤其要统一。

5.3 渲染帧率与物理帧率不同步：视觉数据和位姿对不上

现象：保存的场景图和同时刻的无人机位姿错位明显，深度图和 RGB 图拍的不是同一帧的内容。

原因：AirSim 的渲染和物理模拟是两套 tick，显卡性能不足时渲染帧率掉到物理帧率以下，simGetImages 取到的是渲染管线里的旧帧。

解决：把渲染帧率锁住并压低画质，保证渲染不成为瓶颈。我一般打开 VSync、阴影和后期处理降到中档，跑视觉任务时优先保帧率。分割图和深度图建议在无交互的窗口模式跑，帧对齐会好很多。

5.4 ROS bridge 启动超时：仿真在跑，话题里却没有数据

现象：AirSim 正常起飞，但 rviz 里收不到位姿话题，roslaunch 报连接超时。

原因：airsim_ros_pkgs 默认连的端口或 vehicle_name 和 settings.json 对不上。最常见的是多机配置下没给 ROS 桥接节点指定车辆名，它默认去连一个不存在的 default 车辆。

解决：启动 ROS 桥接时显式传 vehicle_name 参数，和一键启动脚本里的名字保持一致。另外确认 AirSim 的端口没有被防火墙拦，Windows 上 UWP 网络隔离会静默丢包，这个坑排查起来很折磨人。

5.5 高速度指令下姿态发散

现象：moveByVelocityAsync 给到 20 m/s，飞控直接姿态发散，机器翻滚坠落，不是简单的撞墙。

原因：SimpleFlight 内置飞控的限速能力和响应带宽有限，超限速度下姿态环来不及收敛。真正能到 20 m/s 级别的飞控需要 PX4 固件配合，SimpleFlight 更接近教学级。

解决：需要高速机动的任务，先切换到 PX4 车辆类型跑仿真，再谈速度上限。单纯做路径规划验证的话，速度控制在 8 m/s 以内，SimpleFlight 稳定得多。背后的原则是：内置飞控用于验证算法链路，不是给最终机动性能兜底的。

6. 硬件在环与数据回放：把仿真结果落到真实飞控

仿真跑到最后一步，是让真实飞控硬件跑仿真数据。AirSim 支持接入 PX4 开源飞控，飞行控制器以为自己连着真机，实际输入输出全走仿真链路。硬件在环的核心价值是拿真机固件和参数做验证，同时不用承担炸机成本。

6.1 PX4 硬件在环的接入方式

常见做法是先把 PX4 固件跑在 SITL 模式，用 QGroundControl 做地面站，再让 AirSim 的车辆类型指向 PX4 并配对端口：

{ "SettingsVersion": 1.2, "SimMode": "Multirotor", "Vehicles": { "px4_drone": { "VehicleType": "PX4", "UseSerial": false, "TcpPort": 14560 } } }

VehicleType 换成 PX4 后，AirSim 会把仿真状态编码成 MAVLink 送出去。第一次接入时把日志打开，重点看电机指令和姿态估计是否连续；有断流先查 TCP 端口，再查地面站是否被防火墙拦截。

6.2 数据回放：把仿真日志当测试用例

相比实时联调，我更常用数据回放。AirSim 每次飞行都能落盘，位姿、传感器、指令全量保留，之后不管是重放给新算法做离线评估，还是复现现场问题，都是同一份输入。我的习惯是每轮实验前把场景、机型、传感器参数、控制频率写进实验清单，数据文件和清单一一对应。

从那以后我每次拿到新的仿真资源，都会强制先花半小时过一遍版本配对、连通性验证和时钟倍速检查，再开始任何算法实验。这套资料里的文档其实已经把这些坑写得很全，但自己踩一遍才记得住。希望帮到你。

本文还有配套的精品资源，点击获取