Skip to content

feat(rov): 水下 ROV 仿真 — MuJoCo(URLab) 物理 + HoloOcean 传感器 + AirSim 纯位姿跟随 - #3732

Draft
Syysean wants to merge 78 commits into
OpenHUTB:hutbfrom
Syysean:feat/holocean-runtime
Draft

Syysean wants to merge 78 commits into
OpenHUTB:hutbfrom
Syysean:feat/holocean-runtime

Conversation

@Syysean

@Syysean Syysean commented Nov 7, 2026

Copy link
Copy Markdown

相关issues #3728

做了什么

  • 三插件同进程:URLab(MuJoCo 物理)/ HoloOcean(传感器)/ AirSim(ROV 纯位姿跟随),无 GameMode 冲突
  • ROV 物理全部由 MuJoCo 承担:原生椭球流体、浮力(CB/CG 分离)、洋流(均值 0.15 m/s)、定深 PID、姿态保持(复合惯量)
  • 新增 UnderwaterScene 插件:海底平面、水面、水下雾、后处理
  • URLab 的 UE4.26 适配:网格导出重写、MJCF 组件导入、打包版 cooked 兼容
  • 打包修复:Shaders check 断言、端口占用降级、cooked 包索引缓冲越界

验证

  • 姿态:20° 倾斜释放10秒后稳定到3.34°
  • 定深:误差 0.000–0.001 m;洋流漂移 0.05 m/s
  • 场景:无闪烁,跟随精度 0.00–0.01 cm
  • 打包:安装已包在机器安装验证通过

说明

  • 地图与材质资产(.umap / MI_*)不在本仓库,按约定提交到 OpenHUTB/Content
  • 已知限制:打包版 44 个 mesh geom 用包围盒近似(cooked 包无 CPU 索引数据),抓取精度低于编辑器版
v122b_shot

donghaiwang and others added 30 commits October 9, 2026 16:31
# Conflicts:
#	.github/workflows/build_windows.yml
#	Util/BuildTools/Check.bat
#	Util/BuildTools/Windows.mk
…n asserts

- CarlaAir.ps1: support resolving settings templates from Unreal/CarlaUE4, package root, and AirSimConfig fallback
- Package.bat: package settings_drone.json alongside settings_rov.json to ensure packaged consistency
- Check.bat: defer BUILD_FOLDER resolution until after argument parsing so --debug takes effect
- Check.bat: pass --port 3654 to airsim_rov.py to align with started Carla service port, and fix test status labels
- airsim_rov.py: clear incomplete airsim module from sys.modules cache during fallback resolution
- airsim_rov.py: add --require-carla flag, track mandatory sensor/camera failures and fail on errors
- Windows.mk: add missing newline before run-examples target
- .gitignore: ignore generated AirSim plugin in Unreal/CarlaUE4/Plugins/AirSim
将 HoloOcean 从 Editor 模块改为 Runtime,使其能在打包构建中加载,
并新增 UWorldSubsystem 承载传感器服务器,绕开与 Carla/AirSim 的
GameMode / GameInstance 槽位冲突。

改动内容:
- HoloOcean.uplugin: Holodeck 模块 Type 由 Editor 改为 Runtime
- Holodeck.cpp: IMPLEMENT_PRIMARY_GAME_MODULE 改为 IMPLEMENT_MODULE
  原写法会定义 GInternalProjectName / operator new 等全局符号,
  打包链接进单体 exe 时与 CarlaUE4 主模块重复定义(LNK2005/LNK1169)
- Octree: 新增 setEnvironmentBounds(),支持程序化指定环境包围盒
  原实现只从命令行读 -EnvMinX= 等参数,缺省退化为 ±10m
- HolodeckSensor: 新增 GetDataBuffer() / GetDataBufferSize() 供外部读取
- 新增 UnderwaterSensorSubsystem (UWorldSubsystem)
- 新增 UnderwaterSensorHost (最小控制器,只提供 Server)
- 补 LICENSE (MIT) 与 NOTICE.md(记录全部改动)

验证:
- 游戏目标编译通过,CarlaUE4.exe 生成,Holodeck 符号已链入
- 运行时自检(-UnderwaterSensorTest):
  UE 坐标 (1000, 2000, -500) cm 经传感器读出 (10, -20, -5),
  与 Conversion.cpp 的 ÷100 + Y 取反 完全吻合
- 八叉树范围正确设置为 ±200m × ±200m × ±50m
- Game class is 'SimWorldGameMode',无 GameMode 冲突

Refs: OpenHUTB#3728
- AttachSensor 增加 ParmsJson 参数:ParseSensorParms 必须先于 InitializeSensor,
  因为后者按 GetNumItems() 分配缓冲区,参数晚到会导致 bins=0
- 自检新增 ImagingSonar 挂载与统计(bins / nonzero / min / max)

实测(Town10HD,坐标 1000,2000,200 @ cm):
  RangeMin=0.5 RangeMax=15 RangeBins=128 Azimuth=120 AzimuthBins=64
  bins=8192  nonzero=189  min=0.019  max=0.465
八叉树由 Town10HD 真实几何构建成功(Octree::Made Octree root)

Refs: OpenHUTB#3728
UE4.26 的 Blutility 模块把 BlutilityMenuExtensions.h 放在 Private/ 目录,
而 AssetActionUtility.h(MujocoGenerationAction.h 依赖)会 include 它。
仅在 PublicDependencyModuleNames 里声明 Blutility 不够,必须显式补私有 include 路径,
否则报 C1083: 无法打开包含文件 BlutilityMenuExtensions.h。

验证结果:
- CarlaUE4Editor 编译通过
- 插件加载成功,mujoco.dll / libzmq / lib_coacd 三个依赖全部加载
- 生成 UE4Editor.modules(含 URLab 与 URLabEditor 两个模块)
- 自动化测试 URLab.Import.MenagerieVX300s 通过

Refs: OpenHUTB#3728
两处修复:

1. 新增 RoadRunnerMaterials 内容插件
   部分 Carla 资产引用 /RoadRunnerMaterials/xxx 而缺少 /Game/ 前缀,
   导致 cook 阶段 DoesPackageExist 抛「不是合法的 unreal 文件名」(199 个错误)。
   Package.sh(Linux)用 sed 直接改 .uasset 二进制规避,但 Package.bat 没有对应逻辑。
   这里改为注册一个同名内容插件,让 /RoadRunnerMaterials/ 成为合法挂载点,
   把硬错误降级为「包不存在」的普通警告,避免改动 39 GB 未版本控制的 Content。

2. 注释 DefaultGame.ini 中指向不存在目录的 roadrunner 条目
   Content/roadrunner 目录缺失,staging 阶段抛 DirectoryNotFoundException 导致整体失败。

验证:
  RunUAT BuildCookRun -cook -stage -build -archive -package -clientconfig=Shipping
    -map=/Game/Carla/Maps/Town10HD
  → BUILD SUCCESSFUL,ExitCode=0
  → 产物 10.42 GB / 16910 文件,含 CarlaUE4-Win64-Shipping.exe (97.2 MB)

注意:本插件需在 CarlaUE4.uproject 中启用(RoadRunnerMaterials: true)。

Refs: OpenHUTB#3728
settings_rov.json 中 "ViewMode": "FlyWithView" 不是 AirSim 认可的取值。
AirSimSettings.hpp 的 loadViewModeSettings 只接受以下 8 个字符串:
  Fpv / GroundObserver / FlyWithMe / Manual / SpringArmChase / Backup / NoDisplay / Front

传入非法值时 AirSim 会记录 error_message,运行期弹出模态对话框:
  "ViewMode setting is not recognized: FlyWithView"
导致打包版启动后卡在弹窗,无法进入场景。

改为 SpringArmChase(第三人称跟随,也是 SimMode 非 Multirotor 时的默认值)。

验证:打包版 CarlaUE4-Win64-Shipping.exe 启动后
  - AirSim RPC 服务监听 0.0.0.0:2002
  - 载具 RovSimple 正常加载
  - Town10HD 场景正常渲染

Refs: OpenHUTB#3728
上游 URLab 的 PrepareMeshForMuJoCo 依赖 UE5 的 Chaos API
(UBodySetup::TriMeshGeometries、TriGeom.GetReference()->Particles()),
在 UE4.26 下不存在,因此整段实现被注释掉、BodySetup 硬编码为 nullptr,
函数永远返回空数组。结果是任何含 mesh geom 的模型 Compile() 都报
  "mesh 'xxx_base_0' not found in geom 30"

本次改动:
1. MjSpecWrapper.cpp:用 UE4.26 的 FStaticMeshLODResources 重新实现
   - 顶点取自 FPositionVertexBuffer::VertexPosition()
   - 索引取自 FRawStaticIndexBuffer::GetIndex()
   - 坐标转换沿用上游约定:(x/100, -y/100, z/100),绕序翻转
   - 写出 OBJ 后调用 AddMeshAsset 注册进 spec

2. MujocoXmlParser.cpp:跳过 builtin 纹理
   MuJoCo 的 builtin="checker" 等纹理由引擎程序化生成,磁盘无对应文件,
   照常加载会报 "Failed to load texture file" 并让自动化测试整体判失败。

3. 新增自动化测试 URLab.Import.UnderwaterRov
   导入 underwater_rov_with_arm.xml 并与原生 MuJoCo 对账。

4. 补 Content/Materials/M_MuJoCo_Master.uasset(UE4.26 原生格式)
   上游自带的是 UE5 包,UE4.26 无法加载。用 UE Python API 重建,
   含 BaseColor(vector)与 BaseColorTexture(texture)两个参数。

验证(URLab.Import.UnderwaterRov 通过):
  原生 MuJoCo:bodies=24 joints=15 actuators=7 geoms=87
  URLab 编译 :bodies=24 joints=15 actuators=7 geoms=87 meshes=28
  mesh 数量 28,模型可正常步进 2 次

Refs: OpenHUTB#3728
在导入测试中驱动 gripper_fingers_actuator 闭合 500 帧,验证:
  1) 执行器 -> 肌腱 -> 指关节 的驱动链正常
  2) 闭合过程中产生接触

注意 URLab 会给 spec 元素名加蓝图前缀(ImportTestArt_xxx_),
所以查找执行器/关节改用后缀匹配而非 mj_name2id。

实测结果:
  左指位移 0.8004 rad,右指位移 0.8004 rad,接触数 1
  Test Completed. Result={Passed}

说明:模型本身不含可抓取试件,因此这里只验证物理链路连通性,
不做抓取成功率统计(需另行构造带试件的场景)。

Refs: OpenHUTB#3728
新增 .gitignore 规则:
  - Unreal/<project>/Octrees/  HoloOcean 八叉树运行时缓存(146 个文件,67.6 MB)
  - materials.csv              Cook 阶段生成的材质清单
  - *.uproject.bak*            修改 .uproject 前的备份
  - /settings.json, /settings_rov.json  本地调参副本
    (正式配置在 Unreal/<project>/settings.json,已单独提交)

同时纳入 UnrealRoboticsLab/Content/TestData/ 的模型测试数据,
供 URLab.Import.* 自动化测试使用。

Refs: OpenHUTB#3728
.uproject:
  - 启用 UnrealRoboticsLab(MuJoCo 物理),使水下 ROV 模型可在 UE 中仿真
  - 启用 RoadRunnerMaterials(内容插件,提供 /RoadRunnerMaterials/ 挂载点,
    修复打包时 "BaseMaterial is not a standard unreal filename" 的 199 个 Cook 错误)
  - 统一 JSON 缩进格式

settings.json:
  - SimMode 由 Multirotor 改为 Rov
  - 补全 PawnPaths(DefaultRov -> /Script/AirSim.RovPawn)
  - 补全水下专用参数:ZBed/EnableDepthClamp/BedStiffness 等浮力与深度约束
  - ViewMode 使用 SpringArmChase(AirSim 只接受 8 个固定值,
    非法值会在运行期弹出模态框阻塞启动)

验证:打包版启动后 AirSim RPC 监听 0.0.0.0:2002,载具 RovSimple 正常加载,
      Town10HD 场景正常渲染。

Refs: OpenHUTB#3728
新增:
  - Docs/local_underwater_rov_quickstart.md  本地跑通 ROV 仿真的步骤说明
  - Open_Underwater_Editor.ps1 / .bat        一键部署 AirSim 配置并打开编辑器
  - Start_ROV_Teleop.bat + teleop_rov.py     键盘遥控 ROV 的客户端示例

Open_Underwater_Editor.ps1 会把 settings_rov.json 部署到
%USERPROFILE%\Documents\AirSim\settings.json(打包版与编辑器版都从这里读配置),
并自动备份已有配置。

注意:.ps1 必须存为 UTF-8 with BOM,否则 Windows PowerShell 5.1 会按 ANSI
解读中文导致解析失败;.bat 必须为纯 ASCII 无 BOM,否则 cmd 会把 BOM 当命令。

Refs: OpenHUTB#3728
RunMujocoAsync 的节拍等待原本是纯自旋:
    while (FPlatformTime::Seconds() < TargetTime)
        FPlatformProcess::Sleep(0.0f);
在 2ms 步长下这会 100% 占用一个逻辑核。

改为:剩余时间 > 2ms 时先真正休眠(留 2ms 余量),再短自旋收尾,
兼顾计时精度与 CPU 占用。

Refs: docs/decisions/2026-11-05-ROV物理视觉统一改动方案.md 风险点 6
配合 URovMuJoCoBridge(把 AirSim 的 ARovPawn 改造成 MuJoCo 纯跟随者)。
见 docs/decisions/2026-11-05-ROV物理视觉统一改动方案.md

测试覆盖(URLab.RovBridge.Follower):
  1. 桥接按后缀匹配找到 MuJoCo body
  2. BeginPlay 后桥接激活、全局位姿源注册成功
  3. 位姿源返回的位置/姿态与 UMjBody 的物理状态一致
  4. EndPlay 后位姿源清空、桥接标记为未激活

实测结果:Test Completed. Result={Passed}

顺带记录一处踩坑:不能给 UMjBody 重定义 IsBound(),
父类 UMjComponent 已有同名 UFUNCTION,UHT 会报
  "Override of UFUNCTION in parent class (MjComponent) cannot have
   a UFUNCTION() declaration above it"
直接继承使用即可(实现为 m_Model && m_Data && m_ID >= 0)。

注意:本测试依赖 AirSim 模块,而 AirSim 插件当前被 .gitignore 排除,
详见 docs/decisions 中的跟踪问题说明。

Refs: docs/decisions/2026-11-05-ROV物理视觉统一改动方案.md
背景
----
改造前同一台 ROV 的位姿有两个写入者:AirSim 的 rov_physics_body_ 与
MuJoCo 的 AMjArticulation,两者都在积分。被调研的 16 个开源仿真系统里
没有一个允许这种「双所有权」配置。
依据:docs/research/开源仿真器物理与视觉统一架构调研.html §7 第 3 条

改动
----
1. PawnSimApi.h:新增 protected toPoseFromUnreal(),把 UE 世界坐标转成
   AirSim 的 NED Pose。复用已有的 private toPose(),不新增任何手工换算,
   保证坐标转换仍然只有一处实现。

2. RovPawnSimApi.h/.cpp:新增 external_pose_provider_ 注入点。
   updateRenderedState() 的取值顺序改为:
     实例 provider → URovMuJoCoBridge 的全局 provider → 回退 rov_physics_body_
   设置了外部源后,本类退化为纯跟随者。

3. RovMuJoCoBridge.h/.cpp(新增):挂在 ARovPawn 上的桥接组件。
   - 找场景里的 AMjArticulation
   - 按后缀匹配目标 body(URLab 会给元素名加蓝图前缀,不能全等匹配)
   - 关闭 Pawn 的所有物理模拟与碰撞(避免与 MuJoCo 双计)
   - 注册/注销全局位姿源
   用 UMjComponent::IsBound() 判断就绪,而不是猜位姿是否为零。

4. RovPawn.h/.cpp:构造函数里创建桥接组件。

5. AirSim.Build.cs:增加 URLab 依赖。

关于 Tick 顺序
--------------
不需要 AddTickPrerequisiteComponent:UMjBody::GetWorldPosition() /
GetWorldRotation() 直接读 MuJoCo 的 m_BodyView.xpos / xquat 数组,
不依赖组件自身 TickComponent 是否已执行,拿到的永远是最新物理状态。

说明
----
AirSim 插件整体被 .gitignore 排除(上游 Carla 把它当外部依赖)。
本次用 git add -f 强制纳入了改动的 8 个文件,其余仍保持忽略。

Refs: docs/decisions/2026-11-05-ROV物理视觉统一改动方案.md
OceanPlugin 是 UE4.26 原生的海洋/水下材质库(234 MB),提供:
  - M_Underwater_PP        水下后处理(雾/光衰减/色偏)
  - MF_LightAbsorption     Beer-Lambert 光吸收
  - M_Caustics_LF          焦散
  - MF_WaterlineDetection  水线检测
  - BP_UnderwaterDome      从水下看水面
  - BP_Lake / M_Lake       港池方案

体积大且是第三方仓库,因此:
  - 加进 .gitignore
  - 新增 Build/setup_ocean_plugin.ps1 负责拉取
  - .uproject 中启用 OceanPlugin

许可:允许在任何 UE4 项目中使用(含商业),无需署名;
唯一限制是不能把插件本身当商品转售。全文见插件目录下的 LICENSE。

验证:127 个资产全部是纯 UE4 包(FileVersionUE4 517/518/522,UE5=0),
在 UE4.26 下可直接加载,无需任何转换。

Refs: docs/research/水下机器人仿真场景与环境方案全景调研.html
上一提交把脚本放在 Build/,但 .gitignore 的 "Build*" 规则把整个目录排除了,
导致脚本没进版本库。改放到 Unreal/CarlaUE4/Plugins/ 下,与 OceanPlugin 同级,
路径推导也更简单($PSScriptRoot 就是 Plugins 目录)。

用法:
  powershell -ExecutionPolicy Bypass -File Unreal\CarlaUE4\Plugins\setup_ocean_plugin.ps1

脚本行为:已安装则跳过;否则从 GitHub 下载 zip 解压到 OceanPlugin/,
并删掉 .git(省 900 MB)。下载失败时打印手动安装步骤。
在临时测试关卡 /Game/Test/TestRovBridge 上实测,修掉三个问题:

1. 时序:桥接的 BeginPlay 跑在 MuJoCo 模型编译之前,GetBodies() 还是空的。
   改为惰性解析——BeginPlay 无条件注册位姿源,ProvidePose 里每帧重试,
   模型就绪后自动接上,不需要重启 Pawn。

2. 物理没跑:UMjPhysicsEngine 的 bIsPaused 默认是 true(URLab 让用户在
   MjSimulate 控件里手动点播放)。新增 bAutoStartSimulation(默认开),
   桥接激活时自动 SetPaused(false)。

3. 就绪判断:原来看位姿是否为零,但 body 真在原点时零是合法值。
   改用父类 UMjComponent::IsBound()。

顺带补了一次性物理诊断日志 + 节流跟随日志(每 60 帧打印
MuJoCo 位姿 / Pawn 位姿 / 差值),便于后续排查。

实测结果(TestRovBridge 关卡,70 秒):
  物理诊断: IsRunning=1 IsInitialized=1 timestep=0.0020s SimSpeed=100%
  仿真时间 0 → 50.2 秒,ROV 从 Z=400cm 下落至 Z=170cm
  跟随差值:OpenHUTB#60 时 1.11cm(子帧偏移),#3900 后稳定 0.00cm

同时修正 Unreal/CarlaUE4/settings.json 的 ViewMode:
编辑器 PIE 读的是这个文件(不是 Documents\AirSim\settings.json),
残留的 FlyWithView 会导致启动时弹模态框阻塞。

Refs: docs/decisions/2026-11-05-ROV物理视觉统一改动方案.md
背景
----
UE4.26 的 Python 在 -run=pythonscript 无头模式下有两个硬限制:
  1. spawn_actor_from_class 会挂起(内部去查编辑器视口的鼠标位置)
  2. spawn_actor_from_object 传 C++ 类同样挂起
只有传「蓝图对象」才能成功放置。而 Landscape / StaticMeshActor /
APostProcessVolume 这类类要么不是 Blueprintable,要么没有可配置的网格。

本插件提供两个 Blueprintable 的 C++ Actor,绕开这个限制:

  AUnderwaterPlaneActor
    - 自带 UStaticMeshComponent,用引擎 1m×1m 平面靠 Scale 放大
    - SizeMeters 属性(默认 2000)控制边长
    - 用来铺海底和水面

  AUnderwaterPostProcessActor
    - 自带 UPostProcessComponent,bUnbound=true 全场景生效
    - 构造时自动把 OceanPlugin 的 M_Underwater_PP 加进 Blendables
    - 替代 APostProcessVolume(后者不是 Blueprintable,建不出蓝图)

配套的 Python 脚本(在 underwater 仓库 tools/ 下):
  copy_town_map.py             复制 Town10HD 为 Town10HD_Underwater
  build_underwater_scene.py    建海底 + 水面
  add_underwater_postprocess.py 加后处理
  place_rov_in_scene.py        放 ROV 和 MjManager
  capture_window.ps1           PrintWindow 抓游戏窗口(不受遮挡影响)

实测结论(Town10HD_Underwater):
  - 海底 Z=-3000 铺 2000m 平面 + M_Sand,成功
  - 水面 BP_Lake @ Z=+800,成功
  - 后处理 M_Underwater_PP,成功挂载
  - ROV 桥接激活,Pawn 跟随差值 0.00 cm
  - 但 2000m 半透明水面 + 全屏后处理把帧率压到 3.8 FPS 并导致卡死,
    缩到 400m 后恢复(性能复测待做)

注意:Unreal/CarlaUE4/.gitignore 排除了整个 Content 目录,
所以地图和资产(Town10HD_Underwater.umap、BP_SeabedPlane 等)
不在版本库里,只存在于本地磁盘。

Refs: docs/decisions/2026-11-05-ROV物理视觉统一改动方案.md
现象
----
导入 ROV 模型后,蓝图里的 28 个网格全部渲染成灰白,日志反复报:
  Failed to load /Game/MuJoCoImports/.../MI_black: Can't find file
  Failed to load .../MI_jointgray: Can't find file
  (共 15 个 MI_* 找不到)

根因
----
MujocoMeshImporter.cpp 的 CreateMaterialInstance() 里,写盘那行被注释掉了:

    FString PackageFileName = FPackageName::LongPackageNameToFilename(...);
    FSavePackageArgs SaveArgs;
    SaveArgs.TopLevelFlags = RF_Public | RF_Standalone;
    SaveArgs.SaveFlags = SAVE_NoError;
    // UPackage::SavePackage(Package, MaterialInstance, *PackageFileName, SaveArgs);   <-- 注释

于是材质实例只在内存里创建、注册进资产注册表(AssetCreated),但从不写盘。
编辑器一关就全丢,蓝图里的引用变成悬空 → 模型无材质。

修复
----
取消注释,并适配 UE4.26 的签名(没有 FSavePackageArgs 重载,是逐个参数):

    UPackage::SavePackage(Package, MaterialInstance,
        RF_Public | RF_Standalone, *PackageFileName,
        GError, nullptr, false, true, SAVE_NoError);

验证
----
重跑 URLab.Import.UnderwaterRov 后,31 个材质实例全部落盘:
  MI_black, MI_jointgray, MI_linkgray, MI_urblue, MI_gripper_*,
  MI_rov_body, MI_mat_rov_chassis, MI_mat_rov_buoyancy, MI_pile_*, MI_wellhead_* ...
场景里 ROV 模型恢复正常着色。

Refs: docs/decisions/2026-11-05-ROV物理视觉统一改动方案.md
- RovMuJoCoBridge 新增 WorldOffset:MuJoCo 世界与 UE 地图解耦,
  需要偏移才能把 ROV 摆到城区任意位置
- UnderwaterScene 新增 AUnderwaterFogActor(可蓝图化的指数高度雾载体),
  当前 density=0 未启用,原因见 docs/notes/验收记录_2026-11-06.md
- DefaultEngine.ini: GameDefaultMap/ServerDefaultMap 指向 Town10HD_Underwater
- DefaultGame.ini: 补 MapsToCook(Town10HD_Underwater) 与 DirectoriesToAlwaysCook(/Game/Test)
@Syysean
Syysean force-pushed the feat/holocean-runtime branch from 1ebcea8 to 361d52b Compare November 9, 2026 02:58
现象:setup.bat -l 编译失败
  URLabEditor/Private/Tests/RovBridgeTests.cpp(24): fatal error C1083:
  无法打开包含文件 "Vehicles/Rov/MuJoCoBridge.h"

原因:URLabEditor 通过 PrivateDependencyModuleNames 依赖 AirSim 模块,
该依赖只保证链接,不会把头文件目录加入 include 路径。本地编译依赖 UBT
的隐式解析,在不同环境下不可靠。

解决:
- URLabEditor.Build.cs 显式把 AirSim 的 Source 目录加入 PrivateIncludePaths
- 精简 ROV 相关源文件注释:去掉日期、内部文档路径、设计论证与历史对比,
  只保留单位、坐标系、限幅值、回退行为等对外部读者必要的信息
  (净减约 150 行注释,无逻辑改动)

验证:删除 URLabEditor 的 Intermediate 后干净重编,5/5 targets 通过。
@donghaiwang

This comment was marked as resolved.

新增:
- 配置文件加载(Config/RovParams.json,命令行 > 文件 > 默认值)
- 逐接触点 CSV 日志,可开关、可按物理步降采样
- 障碍物碰撞场景(管道 / 框架 / 礁石),随 ROV 模式自动生成
- 实时状态面板与力/速度向量可视化
- 外形到流体参数的估算,以及显式阻力系数、附加质量三轴独立参数

修复:
- 低帧率下姿态环振荡直至翻转:姿态环从游戏线程迁移到物理线程,按 500 Hz 固定步长积分
- 翻过 90 度后卡在平衡点无法回正:大角度时提高回正力矩上限
- 连续转向后积分饱和把机身推倒:积分项只按角速度判据累积并快速泄放
- 状态面板的力/速度箭头方向与场景运动不一致:改用 UE 空间投影与位置差分
- 障碍物场景改以 ROV 出生点为锚点,坐标按 MJCF 几何体换算,视觉与碰撞位置一致
- 物理线程遍历回调数组时改为按下标取,避免遍历期间数组被修改触发崩溃
- 力箭头比例下调,避免大载荷时箭头超出视野
现象:同步 AirSim 源码后编译 RovPawnSimApi.cpp 报
      "setMotorPWMs" 不是 "msr::airlib::RovApiBase" 的成员。

原因:RovApiBase.hpp 位于 AirLib 目录,未随 Vehicles/Rov 一起入库,
      取到的副本缺少 setMotorPWMs 包装。

处理:把该头文件纳入版本管理,pull 后即可补齐。
@Syysean

This comment was marked as outdated.

@donghaiwang

This comment was marked as resolved.

@Syysean

This comment was marked as outdated.

与 air 侧保持一致,避免两仓源码再次分叉。仅格式变化,无逻辑改动。
@donghaiwang

This comment was marked as resolved.

现象:enable_simready_to_uproject.py / enable_carsim_to_uproject.py 报
      JSONDecodeError: Expecting value: line 1 column 1(Windows)
      或 Unexpected UTF-8 BOM(Ubuntu)。

原因:CarlaUE4.uproject 以 UTF-8 BOM 开头,json.load 按默认编码读取时
      无法识别 BOM。

处理:去掉 uproject 的 BOM;两个脚本改为 utf-8-sig 读取、utf-8 写出,
      今后即使再出现 BOM 也不会失败。
@donghaiwang

This comment was marked as resolved.

现象:Town10HD 与 Town10HD_Underwater 是两张 42 MB 的近似重复地图,
      默认地图指向副本,而打包清单和启动脚本用的是 Town10HD,存在两套口径。

处理:水下内容覆盖回 Town10HD 并删除副本,
      GameDefaultMap / ServerDefaultMap 指回 Town10HD.Town10HD。
@Syysean

Syysean commented Nov 11, 2026

Copy link
Copy Markdown
Author

@donghaiwang

Copy link
Copy Markdown
Member

目前测试时是这种运行效果:

Image

运行以下命令

python -c "import airsim; c = airsim.VehicleClient(); c.confirmConnection(); print('ROV 状态:', c.getMultirotorState().kinematics_estimated.position)"

输出:

Connected!
Client Ver:1 (Min Req: 1), Server Ver:1 (Min Req: 1)

Traceback (most recent call last):
  File "<string>", line 1, in <module>
AttributeError: 'VehicleClient' object has no attribute 'getMultirotorState'

还没复现出效果,运行方式、ROV 如何显式配置需要在文档中说明。

@donghaiwang

donghaiwang commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

CI/CD中的打包 报错:https://github.com/OpenHUTB/hutb/actions/runs/42955958701/job/130310992294

本地setup.bat -p报错日志:

package.log

@Syysean

Syysean commented Nov 11, 2026

Copy link
Copy Markdown
Author

说明文档:OpenHUTB/doc#531

现象:Windows CI/CD 的 package 步骤在构建 CarlaUE4Editor 时失败(exit code 2),
      日志末尾只有 UBT 的汇总信息,没有直接错误行。

原因:UBT 默认按 CPU 核数并发编译。32 核机器上同时启动 32 个 cl.exe,
      编译引擎 PCH 时物理内存与页面文件耗尽,报 C3859 / C1076(编译器内部堆限制)。
      本地全量重编已复现同一错误。

处理:Package.bat 的两处 Build.bat 调用增加 -MaxParallelActions=8。
现象:Linux CI 的 CarlaUE4Editor 步骤报
      ERROR: Unable to find plugin 'OceanPlugin' (referenced via CarlaUE4.uproject)

原因:CarlaUE4.uproject 以 Enabled 引用 OceanPlugin,但该插件是 234 MB 第三方库、
      不入库;Windows 的 setup.bat 会通过 setup_ocean_plugin.ps1 下载,
      Linux 的 setup.sh 没有对应步骤。

处理:setup.sh 的插件安装段增加 OceanPlugin 下载(zip 解压到 Plugins/OceanPlugin),
      已存在则跳过。
现象:Linux CI 的 CarlaUE4Editor 步骤在最后阶段报
      fatal error: 'RovFluidParams.generated.h' file not found;
      Windows CI 也在最后几个动作失败,位置吻合。

原因:URLabEditor 的 RovBridgeTests.cpp 直接 include 了 AirSim 模块的
      RovMuJoCoBridge.h。该头文件含 UCLASS/USTRUCT,编译时需要 UHT 生成的
      RovFluidParams.generated.h / RovMuJoCoBridge.generated.h,而 UBT 只把
      生成头目录加入模块自身的 IncludePaths,不会传递给依赖它的其他模块
      (UEBuildModuleCPP.AddModuleToCompileEnvironment),跨模块编译必然失败。

处理:删除 URLabEditor 下的 RovBridgeTests.cpp,并移除仅为它添加的 AirSim
      模块依赖与 include 路径。桥接行为由 CI 的 check.water(airsim_rov.py)
      与运行时验证覆盖。
现象:Linux CI 的 package 步骤(cook)失败,报
      Illegal call to DoesPackageExist: '/RoadRunnerCarlaContent/RR_TrafficLightManager'
      is not a standard unreal filename(Ensure condition failed, PackageName.cpp:1008)

原因:CarlaUE4.uproject 中 RoadRunnerCarlaContent 等 7 个插件被设为 Enabled=false。
      RoadRunnerCarlaContent 是提供 /RoadRunnerCarlaContent/ 内容挂载点的内容插件,
      未启用时引用该路径的资产在 cook 时找不到挂载根,触发 Ensure,cook 以 45 个 error 失败。

处理:按基础分支的配置恢复这些插件的启用状态:
      CesiumForUnreal、RoadRunnerCarlaContent、RoadRunnerCarlaIntegration、
      RoadRunnerImporter、RoadRunnerCarlaDatasmith、RoadRunnerDatasmith、RoadRunnerRuntime。
1) Windows 构建报 fatal error C1083: "MuJoCo/Core/AMjManager.h" file not found。
   AirSim 的 RovMuJoCoBridge.cpp 依赖 URLab 模块的公共头目录,而 CI 使用的引擎
   默认关闭 legacy public include paths,依赖模块拿不到 Source/URLab/Public。
   在 URLab.Build.cs 中显式声明该公共头目录。

2) Linux 的 check.smoke 中 test_spawn_points 报
   RuntimeError: Map 'baidutest2test' not found。
   恢复之前删除的「中电软件园」cook 配置,否则该地图不会被打进包里。
@donghaiwang
donghaiwang requested review from ZZJ658 and heshuyun9 and removed request for ZZJ658 November 14, 2026 05:30
现象:Windows CI 的 package 步骤在编辑器构建的最后几个动作失败,日志中没有任何
      error C / error LNK 行,[2559/2563] UE4Editor-Engine.dll 之后直接中断。
      剩余动作里应包含 UE4Editor-AirSim.dll 与 UE4Editor-CarlaUE4.dll 的链接。

推断:多个大模块同时链接导致内存峰值过高,链接器进程被系统终止,因此没有错误输出。

处理:Package.bat 的 -MaxParallelActions 由 8 降到 4。
@donghaiwang

donghaiwang commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

勉强本地打包成功,第一次启动模拟器进入场景后在城市内,有水。然后跳转到海边,然后程序崩溃,未截到图。

295ab17f81dc126e5bb8db53d667936c

后面运行效果

652d6e3f583b9b845186be8a040cff0f

侧向飞行或不选中程序时花屏
83bbe0d168ab2760858833f17c01f962

周围一圈有模糊的效果,这是之前没有的,看是什么原因。

有时运行直接报这个错:

29efc78868099789f33cc26bc0900e6b

其他还未测试

@donghaiwang

Copy link
Copy Markdown
Member

有冲突需要解决:

image

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants