Developer Documentation

JJM Seat SDK

Unity Android 座椅控制开发套件，支持姿态控制与多感官特效联动

Unity Android Namespace: SeatControl Version 1.0.0 Updated 2026-02-25

核心类

公开接口

特效类型

UDP

通信协议

🚀 快速上手

添加到场景

在 Unity 场景中创建一个空 GameObject，挂载 SeatControlManager 组件。

配置参数

在 Inspector 中配置 SeatConfig，填写座椅的 UDP IP 地址和端口。

调用接口

通过单例 SeatControlManager.Instance 在任意脚本中调用控制接口。

C# 基础使用示例

using SeatControl;

public class MyGameScript : MonoBehaviour
{
    void Start()
    {
        // 获取单例并发送姿态指令
        SeatControlManager.Instance.SendSeatPosture(
            new Vector3(10f, 0f, 5f),  // Pitch=10°, Yaw=0°, Roll=5°
            0.7f                             // 高度 70%
        );

        // 设置风速为中等
        SeatControlManager.Instance.SetWindSpeed(2);

        // 开启加热
        SeatControlManager.Instance.SetHeater(true);
    }
}

🏗️ 架构说明

你的游戏脚本

↓ 调用

SeatControlManager
单例 MonoBehaviour · 主控API层

↓ 桥接

SeatControlBridge
Unity ↔ Android JNI 桥接层

SeatControlUI
可选 · UI 控制组件

↓ JNI

com.jjm.seatcontrolsdk.SeatController
Android 原生 SDK · UDP 通信

💡

编辑器模式下 SeatControlBridge 会自动切换为模拟实现，所有调用仅输出日志，不影响实际设备。

📦 数据结构

Serializable Class

SeatConfig

座椅全局配置数据类，在 Inspector 中可视化配置。

字段	类型	默认值	说明
`type`	int	`0`	座椅类型，支持 0 / 1 / 2 三种型号
`udpIp`	string	`"192.168.15.202"`	座椅 UDP 目标 IP 地址
`udpPort`	int	`7408`	UDP 通信端口
`movementParams`	MovementParams	默认实例	运动参数配置对象
`effectsConfig`	EffectsConfig?	`null`	特效配置（为 null 时禁用所有特效）

Serializable Class

MovementParams

座椅运动参数，控制各轴的缩放比例、最大角度与灵敏度。

字段	类型	默认值	说明
`upDownScale`	float	`0.3`	上下运动缩放比例
`pitchScale`	float	`0.7`	俯仰运动缩放比例
`rollScale`	float	`0.7`	翻滚运动缩放比例
`seatMaxAngle`	float	`15°`	座椅最大角度（全局）
`seatPitchMaxAngle`	float	`15°`	俯仰方向最大角度
`seatRollMaxAngle`	float	`15°`	翻滚方向最大角度
`upDownSensitivity`	float	`0.8`	上下方向灵敏度
`pitchSensitivity`	float	`1.2`	俯仰方向灵敏度
`rollSensitivity`	float	`1.3`	翻滚方向灵敏度

Serializable Class

EffectsConfig

特效设备配置（可选）。在 SeatConfig.effectsConfig 中配置以启用特效功能。

字段	类型	默认值	说明
`relayIp`	string	—	继电器控制器 IP 地址（控制水雾/香薰/加热）
`relayPort`	int	`8234`	继电器通信端口
`relaySlaveAddress`	byte	`1`	继电器 Modbus 从站地址
`speedIp`	string	—	风速控制器 IP 地址
`speedPort`	int	`8234`	风速控制器通信端口
`speedSlaveAddress`	byte	`1`	风速控制器 Modbus 从站地址
`speedRegisterAddress`	int	`3`	风速写入的寄存器地址

🎮 SeatControlManager

主控制类，以 单例 MonoBehaviour 形式运行于场景中，封装了所有座椅控制 API。推荐通过此类与 SDK 交互。

Namespace: SeatControl 继承: MonoBehaviour 单例访问: SeatControlManager.Instance

Inspector 配置项

属性	类型	默认	说明
`config`	SeatConfig	默认实例	座椅完整配置
`persistAcrossScenes`	bool	`true`	是否跨场景保持（DontDestroyOnLoad）
`showDebugInfo`	bool	`true`	是否输出调试日志

属性

staticproperty

Instance

public static SeatControlManager Instance { get; }

全局单例访问器。若场景中不存在 SeatControlManager 将输出错误日志。

SeatControlManager.Instance.SendSeatPosture(...)

propertyreadonly

IsInitialized

public bool IsInitialized { get; }

返回 SDK 是否已成功初始化。在调用控制接口前建议检查此值。

返回值 bool — true 表示已初始化，false 表示未初始化或初始化失败

propertyreadonly

IsEffectsEnabled

public bool IsEffectsEnabled { get; }

返回特效功能是否已启用（即 SeatConfig.effectsConfig 是否不为 null）。

返回值 bool — true 表示特效可用

初始化

methodpublic

Initialize()

public void Initialize()

初始化座椅控制。在 Start() 中自动调用，一般无需手动调用。若已初始化则直接返回。成功后将 IsInitialized 置为 true。

ℹ️

此方法在 MonoBehaviour.Start() 中自动触发，通常不需要手动调用。

methodpublic

UpdateConfiguration()

public void UpdateConfiguration(SeatConfig newConfig)

运行时更新座椅配置并重新初始化。用于动态切换连接目标或运动参数。

参数	类型	说明
`newConfig`	SeatConfig	新的座椅配置对象

var config = new SeatConfig { udpIp = "192.168.1.100", udpPort = 7408 };
SeatControlManager.Instance.UpdateConfiguration(config);

姿态控制 API

methodpublic推荐

SendSeatPosture()

public void SendSeatPosture(Vector3 rotation, float height)

发送座椅姿态控制指令。这是推荐使用的主要姿态控制接口。

参数	类型	范围	说明
`rotation`	Vector3	—	旋转角度向量：X = Pitch（俯仰）, Y = Yaw（偏航）, Z = Roll（翻滚）
`height`	float	0.0 ~ 1.0	座椅高度，0 = 最低，1 = 最高

// 前倾 10°，右倾 5°，高度 70%
SeatControlManager.Instance.SendSeatPosture(
    new Vector3(10f, 0f, 5f),
    0.7f
);

method已废弃

SendCommand()

[Obsolete] public void SendCommand(float x, float y, float z, float angle)

旧版姿态控制接口，保留用于向后兼容。请使用 SendSeatPosture() 替代。

参数	类型	范围	说明
`x`	float	0 ~ 1	X 轴位置
`y`	float	0 ~ 1	Y 轴位置
`z`	float	0 ~ 1	Z 轴位置
`angle`	float	-180 ~ 180	旋转角度

methodpublic

ResetPosture()

public void ResetPosture()

将座椅重置到默认中立姿态（rotation=0, height=0.5）。

SeatControlManager.Instance.ResetPosture();

特效控制 API

⚠️

以下特效 API 需要在 SeatConfig.effectsConfig 不为 null 时才能调用，否则调用会被忽略并输出警告日志。

method特效

SetWindSpeed()

public void SetWindSpeed(int level)

设置座位风速等级。

参数	类型	说明
`level`	int	`0`=关闭 \| `1`=低 \| `2`=中 \| `3`=高

method特效

SetWaterMist()

public void SetWaterMist(int type)

设置水雾喷射类型。

参数	类型	说明
`type`	int	`0`=关闭 \| `1`=薄雾 \| `2`=小水珠 \| `3`=大水珠

method特效

SetScent()

public void SetScent(int type)

设置香薰类型。

参数	类型	说明
`type`	int	`0`=关闭 \| `1`=香薰1 \| `2`=香薰2

method特效

SetHeater()

public void SetHeater(bool isOn)

开启或关闭座椅加热功能。

参数	类型	说明
`isOn`	bool	`true`=开启加热 \| `false`=关闭加热

method特效

TurnOffAllEffects()

public void TurnOffAllEffects()

一次性关闭所有特效（风速、水雾、香薰、加热）。场景结束时会自动调用。

method特效

SetEffectsCombination()

public void SetEffectsCombination(int wind, int mist, int scent, bool heater)

一次性设置所有特效参数组合，等同于依次调用四个特效方法。适合场景切换时的批量触发。

参数	类型	说明
`wind`	int	风速等级 (0-3)
`mist`	int	水雾类型 (0-3)
`scent`	int	香薰类型 (0-2)
`heater`	bool	加热开关

// 海边场景：中风 + 薄雾 + 无香薰 + 不加热
SeatControlManager.Instance.SetEffectsCombination(2, 1, 0, false);

查询 API

methodpublic

GetVersion()

public string GetVersion()

获取 Android SDK 版本号字符串。未初始化时返回 "未初始化"。

返回值 string — 版本号，如 "1.0.0"

methodpublic

GetConfig()

public SeatConfig GetConfig()

获取当前生效的座椅配置对象。

返回值 SeatConfig — 当前配置实例

🔌 SeatControlBridge

底层桥接类，负责 Unity C# 与 Android JNI 之间的通信。通常不需要直接调用此类，建议通过 SeatControlManager 操作。

🖥️

在 Unity 编辑器中（非 Android 平台），所有方法均为模拟实现，仅输出日志，不做实际控制。

methodbridge

SetConfiguration()

public bool SetConfiguration(SeatConfig config)

将 C# 配置对象转换为 Android 原生 Java 对象并传入 SDK。

参数	类型	说明
`config`	SeatConfig	C# 座椅配置对象

返回值 bool — true 表示配置成功

methodbridge

SendSeatPosture()

public void SendSeatPosture(Vector3 rotation, float height)

直接向 Android SDK 发送姿态指令。

参数	类型	说明
`rotation`	Vector3	X=Pitch, Y=Yaw, Z=Roll
`height`	float	高度 0~1

methodbridge

SendPostureCommand()

public void SendPostureCommand(float x, float y, float z, float angle)

旧版协议兼容接口，调用 Android 的 sendPostureCommand。

参数	类型	说明
`x`	float	X轴 0~1
`y`	float	Y轴 0~1
`z`	float	Z轴 0~1
`angle`	float	角度 -180~180

methodbridge

ResetPosition()

public void ResetPosition()

调用 Android SDK 的 resetPosition，将座椅复位。

methodbridge

SetWindSpeed()

public void SetWindSpeed(int level)

向 Android SDK 发送风速控制指令。level: 0=Off, 1=Low, 2=Mid, 3=High。

参数	类型	说明
`level`	int	0-3

methodbridge

SetWaterMist()

public void SetWaterMist(int type)

向 Android SDK 发送水雾控制指令。type: 0=Off, 1=Fog, 2=SmallWater, 3=BigWater。

参数	类型	说明
`type`	int	0-3

methodbridge

SetScent()

public void SetScent(int type)

向 Android SDK 发送香薰控制指令。type: 0=Off, 1=Scent1, 2=Scent2。

参数	类型	说明
`type`	int	0-2

methodbridge

SetHeater()

public void SetHeater(bool isOn)

向 Android SDK 发送加热控制指令。

参数	类型	说明
`isOn`	bool	true=开, false=关

methodbridge

TurnOffAllEffects()

public void TurnOffAllEffects()

调用 Android SDK 的 turnOffAllEffects，一次性关闭所有特效。

methodbridge

GetVersion()

public string GetVersion()

获取 Android SDK 版本字符串。即 SeatController.getVersion()。

返回值 string — 版本号

methodbridge

Release()

public void Release()

释放 Android SDK 资源。在 SeatControlManager 销毁时自动调用。

🖼️ SeatControlUI

可选的 UI 控制组件，提供完整的姿态与特效可视化控制界面。直接挂载到 Canvas 下的 GameObject 上使用，无需额外编码。

UI 组件

姿态控制 UI

在 Inspector 中配置以下 UI 组件引用：

字段	UI 组件	范围	说明
`pitchSlider`	Slider	-15 ~ 15	俯仰控制（X 轴旋转）
`rollSlider`	Slider	-15 ~ 15	翻滚控制（Z 轴旋转）
`yawSlider`	Slider	0 ~ 360	偏航控制（Y 轴旋转）
`heightSlider`	Slider	0 ~ 1	高度控制
`resetButton`	Button	—	重置所有滑块并发送中立位置指令
`statusText`	TextMeshProUGUI	—	实时显示当前姿态和特效状态
`seatConfig`	SeatConfig	—	配置对象（Inspector 直接设置）

UI 组件可选

特效控制 UI

若 effectsConfig 为 null，特效 UI 组件将自动隐藏。

字段	UI 组件	选项	说明
`windDropdown`	TMP_Dropdown	Off / Low / Mid / High	风速选择下拉框
`mistDropdown`	TMP_Dropdown	Off / Fog / Small / Big	水雾类型下拉框
`scentDropdown`	TMP_Dropdown	Off / 香薰1 / 香薰2	香薰类型下拉框
`heaterToggle`	Toggle	On / Off	加热开关
`effectsOffButton`	Button	—	关闭所有特效并重置 UI