Unreal Engine 5.x / XR / PC 引擎层开发者指南

JJM Seat SDK 虚幻引擎开发指南

面向 Unreal Engine 5.x 的高性能 4D 动感座椅控制套件。开箱即用，支持跨平台姿态同步与风水气热多感官特效一体化联动。

UE 5.0 ~ 5.8+ 全兼容 Windows x64 动态加载 Android (XR 一体机 / 移动端) 小白 & 通感 双座椅支持 Subsystem: USeatDeviceManager
2 款
原生支持硬件型号
3-DOF + Yaw
自由度姿态控制
4 大类
4D 环境特效 (风/水/香/热)
100%
纯蓝图免编调用

💺 双座椅型号特性与配置

SDK 专为两种核心物理硬件进行了动力学建模与参数固化。开发者只需在连接节点选择对应型号，底层自动完成所有行程动力学与归零适配。

轻量紧凑型

小白座椅 (XiaoBai)

ESeatModelType::XiaoBai = 0

针对便携式、紧凑型体验台研发。冲程比大，响应极快，非常适合家庭体验、轻量商业展台及短平快互动娱乐。

零位归零特性机构最低点 (-1.0，高度归一化 0.0)
4D 特效支持无特效硬件 (自动安全禁用)
旋转减速比168.0 : 1
建议初始高度0.50 (中位)
典型应用场景蛋椅、家庭体验台、短平快展台
重载仿真型

通感座椅 (TongGan)

ESeatModelType::TongGan = 1

高保真专业级沉浸式动感座椅。动力输出强劲平顺，出厂即校准在水平中立位，专为飞行模拟、赛车漂移与高端影院定制。

零位归零特性水平中立位 (0.0，高度归一化 0.5)
4D 特效支持风速 + 水雾 + 香薰 + 加热
旋转减速比168.0 : 1
建议初始高度0.50 (平衡位)
典型应用场景飞行模拟、赛车漂移、XR 动感影院

🚀 极简快速上手

三步将动感控制集成到您的场景中，无需编写任何 C++ 代码与底层网络通信逻辑。

1

放入项目 Plugins 目录

将预编译完成的 SeatControlSDK 文件夹直接复制到项目的 Plugins/ 目录下，启动引擎即可自动加载。

2

蓝图右键添加 Get SeatDeviceManager

在任意蓝图（关卡蓝图、Pawn、UMG UI）中右键搜索 Seat Device Manager，获取全局子系统单例。

3

连接并下发姿态

在 BeginPlay 调用 RegisterSeatWithParameters，随后在 50Hz 定时器中调用 SendRotation 驱动运动。

🎮 蓝图核心操作节点：设备连接管理 (Registration)

负责初始化本地 UDP 姿态通信与 Modbus TCP 特效回路，管理设备生命周期。

Registration 蓝图全操作节点
图 1：Registration 蓝图操作节点集合全景
METHOD 小白一键连接

Register Xiao Bai Seat

bool RegisterXiaoBaiSeat(FString UdpIp = "192.168.15.211", int32 UdpPort = 7408);

小白型号座椅的一键快捷直连接口。由于小白座椅硬件仅具备姿态动感机构，不带风水香热外设，该节点会自动配置姿态 UDP 通信，并强制安全禁用所有特效逻辑。

参数类型默认值说明
TargetSeat Device ManagerSelf全局设备管理器单例
Udp IpString"192.168.15.211"小白座椅控制器的 IPv4 地址
Udp Portint327408座椅控制器姿态监听端口

返回：true 表示本地 UDP 套接字初始化成功；false 表示参数非法或创建失败。

METHOD 通感/小白全参数配置

Register Seat with Parameters

bool RegisterSeatWithParameters(FSeatConnectParams ConnectParams);

完整参数化连接接口，推荐在节点引脚上右键选择 “拆分结构体引脚 (Split Struct Pin)” 展开配置。支持小白与通感全型号，支持自定义网络端点。

参数类型默认值说明
Connect Params Seat TypeESeatModelType小白座椅型号：小白 (XiaoBai) 或 通感 (TongGan)
Connect Params Udp IpString"192.168.15.211"姿态控制器 IPv4 地址
Connect Params Udp Portint327408姿态控制器监听端口（1~65535）
Connect Params Enable Effectsbooltrue是否启用特效回路（仅通感有效；小白自动禁用）
Connect Params Relay IpString"192.168.15.7"继电器控制器 IPv4（水雾/香薰/加热）
Connect Params Relay Portint328234继电器 Modbus TCP 端口
Connect Params Speed IpString"192.168.15.8"风速控制器 IPv4（风机控制）
Connect Params Speed Portint328234风速控制器 Modbus 端口

内部固定：继电器从站地址 1、风速从站地址 1、风速寄存器 3 由 SDK 内部固定优化，不开放也不占用节点引脚。

METHOD

Unregister Seat

void UnregisterSeat();

断开并注销当前座椅。内部自动执行关闭全部特效、下发一次硬件复位归位，并释放底层的通信资源与后台工作线程。

PURE

Is Seat Ready

bool IsSeatReady();

检查当前 SDK 是否已成功完成初始化与配置绑定。返回 true 表示设备管理器已就绪，可正常下发控制。

PURE

Get Active Config

USeatDeviceConfig* GetActiveConfig();

获取当前正在生效的配置资产对象（USeatDeviceConfig），用于 UI 界面反显当前的 IP、端口与连接模式。

🕹️ 蓝图核心操作节点：姿态运动控制 (Action)

驱动三轴动感机构与水平偏航转台，支持四轴标量与 UE 原生 FRotator 便捷输入。

Action 与 State 蓝图全操作节点
图 2：Action 姿态控制与 State/Info 状态反显节点集合
METHOD 主力四轴姿态接口

Send Posture

void SendPosture(float Pitch, float Roll, float Yaw, float Height = 0.5f);

核心动感控制接口。输入物理控制量，SDK 内部进行三轴混控算法解算后，以 UDP 报文向控制器发送电机控制脉冲。建议以 50Hz (20ms) 频率循环下发。

参数类型建议范围说明
Pitchfloat-15.0 ~ +15.0俯仰角（度）：正值前倾（俯冲/下坡），负值后仰（仰头/爬坡）
Rollfloat-15.0 ~ +15.0横滚角（度）：正值向右侧倾，负值向左侧倾
Yawfloat-180.0 ~ +180.0偏航角（度）：底盘水平转向，0 度为中立朝向。脉冲倍率内部已自处理
Heightfloat0.0 ~ 1.0基础高度：三轴混控前的支撑高度，中间平衡位置为 0.5
ℹ️
俯仰与横滚超出 ±15° 时，底层会自动平滑限幅截断；多轴大角度叠加或高度接近两端时，输出位移会达到机械行程饱和，属正常物理保护现象。
METHOD FRotator 便捷映射

Send Rotation

void SendRotation(FRotator Rotation, float Height = 0.5f, float PitchSign = 1.0f, float RollSign = 1.0f, float YawSign = 1.0f);

便捷旋转下发节点，专为直接对接虚幻引擎载具、飞船或摄像机旋转设计。内部自动将 FRotator 规范化至 [-180, 180] 并乘以符号系数后调用 Send Posture。

参数类型默认值说明
RotationFRotator(0, 0, 0)虚幻引擎原生旋转体（Pitch, Yaw, Roll）
Heightfloat0.5基础高度（归一化 0.0 ~ 1.0）
Pitch Signfloat1.0俯仰符号校准系数（前后方向相反时填 -1.0）
Roll Signfloat1.0横滚符号校准系数（左右侧倾相反时填 -1.0）
Yaw Signfloat1.0偏航旋转校准系数（旋转转向相反时填 -1.0）
METHOD 硬件归位

Reset Position

void ResetPosition();

向动感底盘提交型号特定的 Home 归位指令。通感型号归位到归一化高度 0.5 且旋转归零；小白型号归位到归一化高度 0.0 且旋转归零。

⚠️
调用归位前必须先暂停连续姿态下发（如暂停 Tick 或清除 50Hz 姿态定时器），否则紧随其后的姿态数据会瞬间覆盖归位指令。

💨 蓝图核心操作节点：4D 环境特效 (Effects)

控制风速、水雾、香薰和加热外设。仅通感座椅有效，小白型号调用时自动被底层安全屏蔽。

Effects 与 Endpoints 蓝图全操作节点
图 3：Effects 环境特效控制与 Endpoints 运行时切换节点集合
METHOD Modbus RTU over TCP

Set Wind Speed

void SetWindSpeed(ESeatWindLevel Level);

通过 Modbus RTU over TCP 协议向变频风控器下发指定档位指令。

枚举选项底层转速写入效果体验
关 (Off)0% (停止)风机完全停止
1档 - 低 (Low)50% 转速微风拂面、徐徐微风
2档 - 中 (Medium)70% 转速行驶中速风感
3档 - 高 (High)100% (全速)极速狂飙、高空下坠大风
METHOD Modbus TCP

Set Water Mist

void SetWaterMist(ESeatWaterMistLevel Level);

通过标准 Modbus TCP 控制高压微雾泵与电磁阀门。

枚举选项物理效果说明
关 (Off)关闭水泵与阀门
雾 (Mist)微雾颗粒，模拟清晨雾气、经过瀑布效果
小水 (SmallWater)小雨滴喷溅效果
大水 (BigWater)浪花扑面、暴雨喷射效果
METHOD Modbus TCP

Set Scent

void SetScent(ESeatScentLevel Level);

通过继电器开启指定香型的气泵回路。选项包括：关 (Off)、香薰通道 1 (Scent1)（如青草清香）、香薰通道 2 (Scent2)（如海洋花香）。

METHOD Modbus TCP

Set Heater

void SetHeater(bool bOn);

控制加热继电器的通断状态。true 开启加热，false 关闭加热。建议业务层限制单次连续开启不超过 120 秒。

METHOD 一键关停

Turn Off All Effects

void TurnOffAllEffects();

安全一键关闭指令。异步提交风速=0、水雾=关、香薰=关、加热=关，并将内部状态快照复位。常用于剧情中断、换关或受控停机。

🔄 运行时端点热切换 (Hot-Switching)

支持在游戏运行中无感更换姿态目标或修正特效控制器地址，无需重启引擎或重新配置全套网络。

METHOD 运行时切换

Set Udp Endpoint

bool SetUdpEndpoint(FString UdpIp = "192.168.15.251", int32 UdpPort = 7408);

轻量切换当前座椅的姿态 UDP 目标。只更新目标 IP 和端口，不会重建风/水/香/热特效连接，本地绑定端口（8410）保持不变。

SetUdpEndpoint 运行时切换接口说明
图 4：SetUdpEndpoint 运行时切换规范与行为详情
参数类型默认值说明
Udp IpString"192.168.15.251"新的座椅控制器 IPv4 地址
Udp Portint327408新的控制器监听端口（1~65535）

返回：成功返回 true；IP/端口非法或 SDK 未初始化返回 false 并保留原目标。切换时会自动清空旧目标尚未发出的积压姿态报文。

METHOD 4D 特效 原子切换

Set Effects Endpoints

bool SetEffectsEndpoints(FString RelayIp = "192.168.15.7", int32 RelayPort = 8234, FString SpeedIp = "192.168.15.8", int32 SpeedPort = 8234);

原子切换继电器与风速控制器的 IP 和端口。两路新连接都成功后才替换旧连接；任一路失败则完整保留旧连接，绝不出现半切换。姿态 UDP 目标不受任何影响。

SetEffectsEndpoints 原子切换接口说明
图 5：SetEffectsEndpoints 原子切换规范与安全行为详情
参数类型默认值说明
Relay IpString"192.168.15.7"继电器 IPv4 地址（水雾/香薰/加热）
Relay Portint328234继电器 Modbus TCP 端口
Speed IpString"192.168.15.8"风速控制器 IPv4 地址
Speed Portint328234风速控制器 Modbus 端口

安全行为：切换前会自动尽力关闭旧设备的特效；新设备连接成功后默认保持全关，不会自动恢复切换前的档位。该接口属于配置重连操作，切忌在 Tick 中每帧调用。

📊 状态反显与驱动信息 (State & Info)

用于 UI 界面仪表盘反显当前姿态与档位，查询底层驱动版本。

PURE 状态快照

Get Current State

const FSeatCurrentState& GetCurrentState();

获取当前最近下发给硬件的姿态角、高度与特效档位状态快照，用于 UI 界面仪表盘反显。

字段名数据类型说明
Current Pitchfloat最近下发的俯仰角（度）
Current Rollfloat最近下发的横滚角（度）
Current Yawfloat最近下发的偏航角（度）
Current Heightfloat最近下发的基础高度（0.0 ~ 1.0）
Wind Levelint32当前风速档位（0=关，1=低，2=中，3=高）
Water Mist Typeint32当前水雾模式（0=关，1=雾，2=小水，3=大水）
Scent Typeint32当前香薰通道（0=关，1=通道1，2=通道2）
bHeater Onbool当前加热继电器状态
PURE

Get SDKVersion

FString GetSDKVersion();

获取底层动态链接库或 AAR 的版本字符串（例如 "SeatControlSDK-PC v0.6.0"）。

⚙️ 通信规范与硬件运行参数

动感座椅与环境外设的网络底层通讯物理协议规范。

通信通道协议类型默认端口约束与规范说明
姿态控制网络 UDP 客户端单向发送 7408 本地源端口固定绑定为 8410。硬件仅接收源端口为 8410 的控制包；同一台 PC 同一时间只允许运行一个使用该 SDK 的进程
继电器控制器 Modbus TCP (标准 MBAP) 8234 控制水雾、香薰、加热。从站地址 SDK 内部固定为 1
风速控制器 Modbus RTU over TCP 8234 裸 RTU 帧带 CRC16 校验经 TCP 透传。从站地址固定为 1，寄存器地址固定为 3
机械姿态限幅 俯仰: ±15° / 横滚: ±15° - 超出范围会被内部混控算法自动平滑限幅截断
旋转偏航倍率 偏航: ±180° - SDK 内部已集成旋转减速比脉冲换算，上层调用无需手动乘 2
下发频率建议 推荐 50Hz (20ms) 定时器 - 姿态建议使用定时器稳定输出；特效仅在档位变化时单次触发，切忌在 Tick 中每帧重复提交

❓ 常见问题排查 (FAQ)

常见硬件调试疑问与快速定位指南。

Q1: 调用 Reset Position 归位后，座椅动了一下又偏向原来的角度？
排查原因：您的高频姿态发送定时器（Tick 或 50Hz 定时器）仍在后台持续下发 Send Posture 或 Send Rotation。归位指令刚发出，下一毫秒的姿态数据瞬间覆盖了归位目标。
解决方法：点击归位前，务必先清除或暂停姿态发送定时器。
Q2: 为什么风速、水雾、香薰控制硬件完全没有响应？
排查步骤：
  1. 检查连接时 Seat Type 是否误选为了 小白。小白型号在底层强制禁用了所有特效逻辑，必须选择 通感；
  2. 检查连接参数中 Enable Effects 是否勾选；
  3. 检查继电器 IP 与风速控制器 IP 是否与现场实际设备匹配（通常为 192.168.15.7:8234 与 192.168.15.8:8234）。若填错，可直接在运行时调用 Set Effects Endpoints 纠错。
Q3: 为什么注册节点返回了 true，但座椅完全不动？
排查步骤：
  1. true 仅代表本地套接字创建成功（UDP 为无连接协议，无握手确认）；
  2. 确认本机与座椅控制器处于同一局域网网段（如 192.168.15.xxx），并在命令行中 ping 控制器 IP 测试网络连通性；
  3. 检查本机防火墙是否阻断了出站 UDP 报文；
  4. 检查是否有其他调试软件（如串口调试工具、Unity 测试程序）占用了本地的 8410 源端口。
Q4: 载具在游戏里向左侧倾，实际座椅却向右侧倾？
解决方法：在 Send Rotation 节点上，将对应轴向的校准系数（如 Roll Sign）由 1.0 修改为 -1.0 即可一键反向纠正。