概述
XML（可扩展标记语言）是一种用于描述数据的标记语言，它类似HTML，但是其中的标记是可以自己定义的。由于这种灵活性和可扩展性，常常被作为程序的配置文件。XML文件的格式类似html也是由各种标签组合而成，每个标签由两对<>符号围起来<***></***>，在标签内部存放着字符串、数字或其他标签。 RflySim3D 所支持的三维模型均通过 Unreal Engine 打包导出。每个模型由三类资源构成：网格体（Mesh）、材质（Material）和物理资产（Physics Asset）。这三类资源之间的索引与绑定关系需在 UE 编辑器中预先设定（例如在蓝图或静态/骨骼网格体资源中指定材质与物理资产）。
模型的运动结构还需满足特定的层级规范。例如，在多旋翼载具中，通常由一个机身（body）和若干旋翼（actuator）组成，旋翼作为子组件依附于主机体节点构成基本的运动层次。合理的资源层级有助于在 RflySim3D 中正确映射执行器位置与旋转轴。
为确保 RflySim3D 能够正确识别并加载 UE 导出的三维模型，需要为每个模型编写配套的 XML 配置文件，描述其结构层次、组件映射及功能参数等关键信息。
必填参数（最小配置）
典型的 XML 配置文件以如下声明开头：
在 XML 中最关键的内容包括：样式索引顺序（由 ClassID 与 DisplayOrder 组成）以及 body 主标签下的机体构成定义。ClassID 标识模型所属大类（如多旋翼、固定翼、地面车等），DisplayOrder 决定该类别内的展示与优先级，数值越小排序越靠前。
在 body 部分，三项关键标签是：ModelType（网格体类型）、MeshPath（三维模型路径）与 ActuatorList（执行器组件列表）。
- 对于静态网格体拼接方式（ModelType=0），模型的运动层次通常未在 UE 中预定义，需在 XML 的 ActuatorList 中列出每个旋翼或舵面的 MeshPath、RelativePosToBodyCm 与 RelativeAngEulerToBodyDeg，以在运行时通过这些信息驱动执行器运动。
- 对于蓝图模型（ModelType=2），组件层级与运动逻辑通常已在蓝图内部定义，XML 中只需将 MeshPath 指向对应的蓝图资源路径，并将 ModelType 设为 2，无须在 XML 中手动编写完整的 ActuatorList（蓝图会封装执行器的位置与控制逻辑）。
当模型层次复杂（例如倾转旋翼、垂直起降复合翼等）时，手动维护 XML 的 ActuatorList 会变得冗长且易错，因此建议优先采用蓝图来封装复杂的层级和运动逻辑，减少 XML 配置工作量并提高可维护性。
下面列出使模型能被RflySim3D正确识别与显示的最少必须填写的 XML 标签。若只填写这些字段，通常可以将模型导入并在场景中显示；高级功能（执行器、摄像头、蓝图接口等）需要额外字段。
- 根标签：<vehicle>...</vehicle> —— 必须存在，包裹整个配置。
- ClassID（必须）—— 模型所属大类ID，决定外观类别与大样式（例如 3 = 四旋翼）。
- DisplayOrder（必须）—— 同类模型内的显示/加载顺序，数值越小优先显示。
- 注意：ClassID 与 DisplayOrder 共同组成模型的唯一样式索引 Unique3DClassID。 计算公式为：Unique3DClassID = DisplayOrder * 100000 + ClassID。 例如：ClassID=3, DisplayOrder=1015 时，Unique3DClassID = 1015 * 100000 + 3 = 101500003。
- Name（建议）—— 在 UE 编辑器中显示的名称，便于资源管理与查找。
- body（必须）应至少包含：
- ModelType（必须）—— 指定模型类型：0/1/2/3/4/5，决定资源加载与控制方式（静态网格/骨骼/蓝图等）。
示例：最小可工作的 XML 配置片段
<?xml version="1.0"?>
<vehicle>
<ClassID>3</ClassID>
<DisplayOrder>1000</DisplayOrder>
<Name>MyMinimalModel</Name>
<body>
<ModelType>0</ModelType>
<MeshPath>/Rfly3DSimPlugin/copter/MyBody</MeshPath>
</body>
</vehicle>
扩展说明：
- 若使用静态网格体方式导入模型（ModelType=0），且模型包含可控作动器（螺旋桨、舵面等），需添加 <ActuatorList>，每个 <Actuator> 最少填写 MeshPath 与 RelativePosToBodyCm（用于定位），若模型包含多个执行器（如多旋翼载具），需添加多个 <Actuator> 标签
- 若使用蓝图方式导入模型（ModelType=2/3/4/5），需要在MeshPath 指向的蓝图中实现并绑定 ActuatorInputs/ActuatorInputsExt 接口，以此来控制作动器。
模型加载方式与 Unique3DClassID
RflySim3D 场景中的所有模型三维样式由基于 XML 文件计算出的唯一索引 Unique3DClassID 控制。要创建或加载三维载具模型，常用三种方式：
- CopterSim 加载（由 CopterSim 控制样式加载）；
- 键盘/鼠标快捷键加载（交互式在场景中生成）；
- 外部程序通过结构体调用接口加载（例如 Python/Simulink 发送结构体）。
已完成配置的三维模型在 RflySim3D 中具有唯一的样式索引 Unique3DClassID，该索引可通过按下 F2 键生成的模型样式索引表 ModelData.csv 获取。当 RflySim3D 与 CopterSim 仿真器联合使用时，载具样式的加载由 CopterSim 控制；此时用户既可通过 BAT 脚本自动加载，也可在 CopterSim 的图形界面中手动指定载具样式。
通过 BAT 脚本指定载具样式时，RflySim3D 支持设置参数 CLASS_3D_ID 来指定模型类型。默认情况下 CLASS_3D_ID=-1，表示载具的外观由 DLL 模型控制（具体原理详见本书第 4 章）；若将 CLASS_3D_ID 修改为 2，则 RflySim3D 将加载与 Unique3DClassID=2 对应的模型样式。
通过快捷键方式加载物体时，可以按下 O+数字* 组合键（例如 O+2），在鼠标双击的位置生成 Unique3DClassID=* 的物体。最新版RflySim3D支持直接从RflySim3D的场景元素UI中加载模型。 使用外部程序通过结构体方式加载模型时（例如调用 Python 接口 sendUE4PosNew、sendUE4Pos2Ground 等向 RflySim3D 发送结构体 SOut2Simulator 或 SOut2SimulatorSimple），RflySim3D 将根据结构体中的场景对象 ID 做判断：
- 若该 ID 尚未对应任何模型，则在场景中自动创建新物体（并按结构体内的样式或默认样式设置外观）；
- 若该 ID 已存在对应物体，则更新其状态（位置、朝向、缩放等）。
以上三种方式覆盖了从离线批量加载到交互式创建再到程序化控制的常见需求，用户可根据工作流选择合适的加载方式。
模型导入方式
1. 静态网格体拼接模型（ModelType=0）
适用场景： 模型不需要复杂动画，只需要简单的旋转/偏转执行器
步骤：
- 将需要控制的执行器和无需控制的机身一同导入UE进行组装和材质替换
- 导入时勾选"Combine Mesh"选项
- 烘焙完成后，将内容与对应的XML文件拷贝至RflySim3D目录
注意事项：
- 导入UE的模型应为FBX、OBJ等通用三维格式
- 导入前应在三维处理软件中分割出需要控制的执行器
2. 自带动画模型（ModelType=1）
适用场景： 带有骨骼动画的模型（如人物模型）
步骤：
- 将模型的骨骼网格体和动画序列一同导入UE
- 烘焙完成后，将内容与对应的XML文件拷贝至RflySim3D目录
注意事项：
- 这里的模型主要用作一些移动障碍
- 可以直接在虚幻商城搜索需要的模型
3. 蓝图导入（ModelType=2,3,4）⭐⭐⭐
该功能仅限个人高级版以上
3.1 普通蓝图（ModelType=2）
步骤：
- 导入模型的骨骼网格体和动画序列
- 创建动画蓝图定义各执行器动画播放效果
- 创建蓝图类，在事件图表中控制执行器触发条件及数据接口
- 烘焙后拷贝至RflySim3D目录
蓝图接口：
- ActuatorInputs - 基础8维执行器输入（pwm1~pwm8）
- ActuatorInputsExt - 扩展16维执行器输入（pwm9~pwm24）
注意事项：
- 需要启用模型蓝图类的碰撞响应
- 骨骼网格体组件的碰撞预设选择BlockAll
3.2 载具蓝图（ModelType=3）
步骤：
- 创建UE项目时使用载具模板
- 其余步骤与普通蓝图相同
注意事项：
- 若使用载具模板自带的模型，需要在载具蓝图类中启用自动控制AI
- 包括UE4的WheeledVehicle类和UE5的Chaos载具系统
3.3 蓝图飞机（ModelType=4）
说明： 需要RflySim内置的CopterNav插件，暂不支持自定义
3.4 机器狗（ModelType=5）
RflySim3D 内置了机器狗（四足机器人）相关的蓝图模板，用于演示与测试四足运动、姿态转换与若干动画状态（例如站立、行走、奔跑、坐下等）。此类模型被归类为 ModelType=5，其行为主要由蓝图内部的动画蓝图和状态机驱动。
蓝图控制规则
ActuatorInputs接口
三维场景中的无人机对象可以通过蓝图函数接口进行控制。RflySim3D提供了两个主要接口：
1. ActuatorInputs（基础接口）
功能： 传输8维数据（pwm1~pwm8）
调用方式：
- Python命令：sendUE4Pos系列
- 控制台命令：RflySetActuatorPWMs
- Simulink模块：UE4DataEncoder
2. ActuatorInputsExt（扩展接口）
功能： 传输16维数据（pwm9~pwm24）
调用方式：
- Python命令：sendUE4ExtAct
- 控制台命令：RflySetActuatorPWMsExt
- Simulink模块：Ue4ExtMsgEncoder
参考资源
XML模板位置：
\PX4PSP\RflySim3D\RflySim3D\Plugins\Rfly3DSimPlugin\Content\XML
相关例程位置： 静态网格体拼接导入载具模型
3.RflySim3DUE/1.BasicExps/e1_CusLoadDroneyeeX680/Readme.pdf
静态网格体导入障碍物模型
3.RflySim3DUE/1.BasicExps/e4_CusLoadObj/3.loadMeshXML/Readme.pdf
蓝图模型导入
3.RflySim3DUE/2.AdvExps/e2_BlueprintModel/3.CusLoadBP/Readme.pdf
XML标签详解
以下是一个完整的F450_Default.xml配置示例，导入方式为静态网格体拼接模型：
<?xml version="1.0"?>
<vehicle>
<ClassID>3</ClassID>
<DisplayOrder>1000</DisplayOrder>
<Name>F450_Default</Name>
<MeshClass>四旋翼</MeshClass>
<MeshId>100042</MeshId>
<Scale>
<x>1</x>
<y>1</y>
<z>1</z>
</Scale>
<AngEulerDeg>
<roll>0</roll>
<pitch>0</pitch>
<yaw>0</yaw>
</AngEulerDeg>
<body>
<ModelType>0</ModelType>
<MeshPath>/Rfly3DSimPlugin/copter/F450Body</MeshPath>
<MaterialPath></MaterialPath>
<AnimationPath></AnimationPath>
<CenterHeightAboveGroundCm>16.3</CenterHeightAboveGroundCm>
<NumberHeigthAboveCenterCm>20</NumberHeigthAboveCenterCm>
</body>
<ActuatorList>
<Actuator>
<MeshPath>/Rfly3DSimPlugin/copter/PropellersCCW</MeshPath>
<MaterialPath></MaterialPath>
<RelativePosToBodyCm>
<x>15.798</x>
<y>16.167</y>
<z>4.5</z>
</RelativePosToBodyCm>
<RelativeAngEulerToBodyDeg>
<roll>0</roll>
<pitch>0</pitch>
<yaw>0</yaw>
</RelativeAngEulerToBodyDeg>
<RotationAxisVectorToBody>
<x>0</x>
<y>0</y>
<z>1</z>
</RotationAxisVectorToBody>
<RotationModeSpinOrDefect>0</RotationModeSpinOrDefect>
</Actuator>
</ActuatorList>
<OnboardCameras>
<camera>
<name>Chase_Camera</name>
<RelativePosToBodyCm>
<x>-70</x>
<y>0</y>
<z>5</z>
</RelativePosToBodyCm>
<RelativeAngEulerToBodyDeg>
<roll>0</roll>
<pitch>0</pitch>
<yaw>0</yaw>
</RelativeAngEulerToBodyDeg>
</camera>
</OnboardCameras>
</vehicle>
1. 载具基本属性
1.1 ClassID（模型类别ID）⭐
作用： 表示飞机构型（大样式）
内置模型模型类别ID主要包括：
- 3 - 四旋翼
- 30 - 人物
- 40 - 标定板
- 100 - 固定翼飞机
- 5、6 - 六旋翼
- 60 - 发光体
- 151 - 方形环
- 150 - 圆形环
- 152 - 球形
- 50 - 小车
- 962、963 - 场景内元素 可以通过在RflySim3D按F2键查看完整的模型样式索引表 示例：
1.2 DisplayOrder（同类模型的显示顺序）⭐
作用： 表示同一构型（如四旋翼）可选模型列表中的排列优先级（小样式）
规则：
- 数值越小，排列越靠前
- 内置机型从1000开始标号
- 小于1000会取代内置飞机，优先展示最新导入机型
示例：
<DisplayOrder>1015</DisplayOrder>
重要说明： 飞机的显示样式由大样式和小样式共同决定。在ue.sendUE4Pos命令中直接发送vehicleType来指定样式（可以直接用Unique3DClassID）：
1.3 Name（模型显示名称）
作用： 在UE中显示的飞机名字
示例：
<Name>F450_Default</Name>
1.4 MeshClass 与 MeshId（资源分类与索引）
**MeshClass（可选）**：用于在 RflySim3D 的模型资源库或场景元素 UI 中对模型进行分类显示（例如“四旋翼”、“建筑”、“障碍物”等）。该字段便于在编辑器/运行时的资源列表中按类别筛选和展示。
**MeshId（可选，暂不支持自定义）**：用于定义模型在资源库中的名称。
示例：
<MeshClass>四旋翼</MeshClass>
<MeshId>100042</MeshId>
注意： MeshClass 与 MeshId 并非必须项，但在使用场景元素 UI、资源库浏览或制作样式索引表（如 ModelData.csv）时非常有用。若需在外部脚本或 BAT 自动化流程中按类别/ID 加载模型，建议填写这两个字段。
2. 模型显示参数
2.1 Scale（模型显示三维尺寸）
作用： 整机三维缩放的尺寸
示例：
<Scale>
<x>1</x>
<y>1</y>
<z>1</z>
</Scale>
2.2 AngEulerDeg（模型初始显示姿态）
作用： 飞机显示偏转一定角度（单位：度）
示例：
<AngEulerDeg>
<roll>0</roll>
<pitch>0</pitch>
<yaw>180</yaw>
</AngEulerDeg>
3. Body（模型机体构成）⭐⭐⭐
机体主标签，定义模型的基本构成。
3.1 ModelType（模型类型）⭐⭐⭐
作用： 定义模型的类型和功能
可选值：
| 值 | 类型 | 支持ActuatorInputs | 说明 |
| 0 | StaticMesh（静态网格） | ❌ | 纯静态网格，不支持蓝图接口 |
| 1 | SkeletalMesh（骨骼网格） | ✅ | 支持蓝图接口 |
| 2 | 普通Blueprint（蓝图） | ✅ | 支持蓝图接口，需要额外的驱动逻辑 |
| 3 | Chaos车轮Blueprint | ✅ | 带轮子物理，使用ChaosWheel相关接口 |
| 4 | CopterNav插件Blueprint | ✅ | 带自主导航功能，使用CopterNavFunc |
示例：
3.2 MeshPath（模型三维文件路径）⭐
作用： 机体的三维文件所在目录
规则：
- /Game/ 表示RflySim3D内容目录
- 路径格式：/Game/文件夹名/模型名
示例：
<MeshPath>/Rfly3DSimPlugin/copter/F450Body</MeshPath>
详解与注意事项：
- 支持两种资产根路径风格（按优先级解析）：
- /Rfly3DSimPlugin/...：解析为插件内容目录，映射为类似 C:\PX4PSP\RflySim3D\RflySim3D\Plugins\Rfly3DSimPlugin\Content\... 下的资源。
- /Game/...：解析为项目 Content 目录，映射为类似 C:\PX4PSP\RflySim3D\RflySim3D\Content\... 下的资源。
- 路径须使用 Unreal Engine 的资产路径风格：以斜杠 / 开头、目录分隔为 /、且不包含文件扩展名（例如 .uasset、<tt>.fbx
等）。
- 常见错误（请避免）：
- 在路径末尾加上扩展名（例如 /Game/mesh/MyMesh.uasset）— 不要加扩展名。
- 末尾多加斜杠（例如 /Game/mesh/MyMesh/）— 不要以斜杠结尾。
- 路径大小写不一致（UE 中资源引用对大小写敏感，应与 Content 中一致）。
- 目标资源未拷贝/烘焙到 RflySim3D 的 Content 或 Plugin Content 下。
**示例映射（参考）**：
<MeshPath>/Rfly3DSimPlugin/copter/F450Body</MeshPath>
<MeshPath>/Game/smith/NewBlueprint</MeshPath>
3.3 MaterialPath（材质路径）
作用： 材质的路径
说明： 如果UE里面已经设置过材质这里可以不填，UE会自动使用模型自带材质
示例：
<MaterialPath></MaterialPath>
3.4 AnimationPath（动画路径）
作用： 指定模型的动画序列路径，与材质路径类似
示例：
<AnimationPath></AnimationPath>
3.5 CenterHeightAboveGroundCm（模型质心离地高度）
作用： 质心离地面高度（单位：厘米）
示例：
<CenterHeightAboveGroundCm>16.3</CenterHeightAboveGroundCm>
3.6 isMoveBodyCenterAxisCm（模型轴心位置）
作用： 调整模型三维轴心位置向量
格式： 逗号分隔的三维向量
示例：
<isMoveBodyCenterAxisCm>0,0,0</isMoveBodyCenterAxisCm>
3.7 NumberHeigthAboveCenterCm（模型显示标签离地高度）
作用： 载具模型上的数字标号（CopterID）显示的高度（单位：厘米）
示例：
<NumberHeigthAboveCenterCm>20</NumberHeigthAboveCenterCm>
4. ActuatorList（执行器显示参数列表）⭐⭐⭐
作动器（螺旋桨、舵机、轮胎、软管刚体、转台）等外部活动组件的列表。
4.1 Actuator（某执行器）
每个<Actuator>标签定义一个作动器的具体参数。
4.1.1 MeshPath（网格体路径）
三维模型路径，同body标签定义
示例：
<MeshPath>/Rfly3DSimPlugin/copter/PropellersCCW</MeshPath>
4.1.2 MaterialPath（材质路径）
材质路径，同body标签定义
示例：
<MaterialPath></MaterialPath>
4.1.3 RelativePosToBodyCm（相对机体中心位置）⭐
作用： 该作动器相对机体中心的位置（单位：厘米）
示例：
<RelativePosToBodyCm>
<x>15.798</x>
<y>16.167</y>
<z>4.5</z>
</RelativePosToBodyCm>
4.1.4 RelativeAngEulerToBodyDeg（安装角度）
作用： 作动器的安装角度（单位：度）
说明： 通常给0即可，表示和导入UE时的姿态相同，不需要再旋转
示例：
<RelativeAngEulerToBodyDeg>
<roll>0</roll>
<pitch>0</pitch>
<yaw>0</yaw>
</RelativeAngEulerToBodyDeg>
4.1.5 RotationModeSpinOrDefect（运动模式）⭐⭐
作用： 作动器运动模式
可选值：
- 0 - 旋转（输入为转动速度，单位：转/分）
- 1 - 偏转（输入为转动角度，单位：度）
- 2 - 静止物体
- 3 - 平移（单位：厘米）
示例：
<RotationModeSpinOrDefect>0</RotationModeSpinOrDefect>
4.1.6 RotationAxisVectorToBody（旋转轴）⭐
作用： 定义旋转轴方向
常用配置：
- 多旋翼螺旋桨：绕Z轴旋转 (0, 0, 1)
- 车辆轮胎：绕Y轴旋转 (0, 1, 0)
- 固定翼螺旋桨：绕X轴旋转 (1, 0, 0)
示例：
<RotationAxisVectorToBody>
<x>0</x>
<y>0</y>
<z>1</z>
</RotationAxisVectorToBody>
4.1.7 AttatchToOtherActuator（执行器附加功能）
作用： 将当前执行器附加到另一个执行器上
说明： "附加"后执行器会随着父执行器进行移动与旋转，但它也可以单独旋转
示例：
<AttatchToOtherActuator>2</AttatchToOtherActuator>
5. OnboardCameras（观察视角，默认会被RflySim3D覆盖，暂不支持自定义）
定义机载摄像头的位置和姿态配置。
说明：
- 第1个摄像头是跟随观察视角，不会跟随飞机俯仰滚转，但会跟随飞机偏航
- 从第2个摄像头开始，都是固连在机体上的，填写摄像头的安装角度和位置即可定义
5.1 camera（某摄像头）
每个<camera>标签定义一个摄像头。
5.1.1 name（摄像头名称）
示例：
<name>Chase_Camera</name>
常用摄像头名称：
- Chase_Camera - 追踪摄像头
- Front_Camera - 前置摄像头
- Back_Camera - 后置摄像头
- Left_Camera - 左侧摄像头
- Right_Camera - 右侧摄像头
- Down_Camera - 下视摄像头
- Up_Camera - 上视摄像头
5.1.2 RelativePosToBodyCm（相对机体位置）
作用： 摄像头相对机体的位置（单位：厘米）
示例：
<RelativePosToBodyCm>
<x>-70</x>
<y>0</y>
<z>5</z>
</RelativePosToBodyCm>
5.1.3 RelativeAngEulerToBodyDeg（相对机体姿态）
作用： 摄像头相对机体的角度（单位：度）
示例：
<RelativeAngEulerToBodyDeg>
<roll>0</roll>
<pitch>-90</pitch>
<yaw>0</yaw>
</RelativeAngEulerToBodyDeg>
常用角度配置：
- 前视：pitch=0, yaw=0
- 后视：pitch=0, yaw=180
- 左视：pitch=0, yaw=-90
- 右视：pitch=0, yaw=90
- 下视：pitch=-90, yaw=0
- 上视：pitch=90, yaw=0
1.15.0