Unity 如何接入 TUIO 协议？TouchScript 多触摸集成的完整教程

【免费下载链接】TouchScriptComplete multi-touch solution for Unity: iOS, Android, Windows, TUIO.项目地址: https://gitcode.com/gh_mirrors/to/TouchScript

TouchScript 是一套面向 Unity 的多点触摸完整解决方案，覆盖 iOS、Android、Windows 与 TUIO 协议，而TUIO 协议集成正是让互动桌、触摸屏、投影墙等外部设备与 Unity 场景"对话"的关键一环。本文不堆砌理论，改用五个问题串联整个接入流程，带你快速完成环境准备、输入源添加、事件响应与坐标适配，少走弯路。

做过展馆互动装置的人大概都经历过这样的时刻：屏幕亮着、Unity 也跑起来了，可当手指按上触摸桌面，场景里的物体却纹丝不动。问题通常不在你的场景代码，而在于——触摸数据压根没进到 Unity 里。红外触摸框、投影互动桌、电容大屏这类设备，绝大多数通过 TUIO 协议对外广播触摸信息，而 Unity 默认"听不懂"这套协议。这正是 TouchScript 的用武之地。

TUIO 协议是什么？为什么 Unity 项目需要它？

TUIO（Tangible User Interface Objects）是专为 tangible 界面与多点触摸表面设计的开放协议。它的分工很清晰：

• 设备端负责采集：手指、手掌甚至带标记的实体物件被设备捕捉后，通过 UDP 报文广播出去；
• 应用端负责解析：Unity 这边收到报文，还原成一个个触摸事件。

TouchScript 的自带组件TuioInput把整套 UDP 监听与解析过程封装好了，你完全不需要关心底层报文长什么样。理解它只需记住三点：

1. 单向广播：数据只从设备流向应用；
2. 归一化坐标：报文里给的是 0~1 范围内的相对位置，像素换算交给应用端；
3. 三类消息：cursor（触点）、blob（形状区域）、object（带标记的 fiducial 物体）。

接入前准备：三步完成 TUIO 环境配置

动手前先确认三件事，能省掉后面大半的排查时间：

第一步，拿到项目源码。把仓库克隆到本地：

git clone https://gitcode.com/gh_mirrors/to/TouchScript

第二步，打开 TUIO 编译开关。TUIO 模块的代码被TOUCHSCRIPT_TUIO宏保护着，没有定义就不会编译进程序。两种开启方式任选其一：在Edit > Project Settings > Player的 Scripting Define Symbols 里手动加上TOUCHSCRIPT_TUIO，或者打开Window > TouchScript > Settings直接勾选启用。

第三步，确认依赖库就位。TUIO 支持依赖 TUIOsharp 与 OSCsharp 两个库，它们随模块存放在Source/Assets/TouchScript/Modules/TUIO/Libraries/目录下，随项目一起导入即可，无需额外下载。

在 Unity 场景中快速添加 TUIO 输入源

环境就绪后，接入本身只要两步操作：

1. 在场景里新建一个空 GameObject，命名随意（比如 TUIOInput）；
2. 给它挂上TuioInput组件（菜单路径：Component > TouchScript > Input Sources > TUIO Input）。

Inspector 面板上有两个关键配置项：

• Tuio Port：监听端口，默认 3333，必须和触摸设备发送端设置的端口保持一致；
• Input Types：勾选需要接收的消息类型，对应源码中的InputType枚举：

[Flags] public enum InputType { Cursors = 1 << 0, // 标准触点：手指、笔尖 Blobs = 1 << 1, // 形状区域：手掌、物体轮廓 Objects = 1 << 2 // 标记物体：fiducial markers }

默认三项全开。如果项目只需要手指触控，只勾 Cursors 就够，少开一路输入还能省一点解析开销。

触摸事件怎么处理？一套手势 API 通吃所有输入

TuioInput本质上是个"翻译官"：把 TUIO 报文翻译成 TouchScript 统一格式的 Pointer 事件。这带来一个很爽的结果——无论输入来自 TUIO、鼠标还是原生触摸，你的交互代码写法完全一致。给物体挂上对应的手势组件，订阅事件即可：

using TouchScript.Gestures; // 物体上预先挂好手势组件，启用时订阅事件 GetComponent<PressGesture>().Pressed += onPress; GetComponent<TransformGesture>().Transformed += onTransform; // onTransform 里直接拿到位移、旋转、缩放增量

多指平移、旋转、缩放这类变换，TransformGesture会统一派发Transformed事件，不需要你自己做差值计算。下面的示例图展示了用TransformGesture实现"单指拖动相机、捏合缩放、多指旋转"的典型玩法。

端口与坐标系：TUIO 接入的细节调优

端口热切换。TuioPort属性允许在运行时修改端口，setter 内部会自动断连并重连，设备换端口后无需重启程序。

坐标系换算。TUIO 报文里的坐标是 0~1 归一化的，TuioInput内部会把它换算成屏幕像素：横坐标乘以屏幕宽度，纵坐标则先做一次1 - Y的翻转再乘高度。为什么翻转？因为 TUIO 的坐标原点在左上角，而 Unity 屏幕坐标原点在左下角，不翻转的话触点会上下镜像。

多屏与异形投影。如果默认换算满足不了需求（比如多投影拼接、异形表面），TouchScript 预留了ICoordinatesRemapper接口，可以继承它实现完全自定义的坐标映射逻辑。

常见坑位与解决方案：连不上、偏了、噪点多

坑位一：设备明明在发数据，Unity 毫无反应。按这个顺序排查：防火墙是否放行了 UDP 3333 端口 → 触摸设备是否把数据发到了运行 Unity 那台机器的 IP →TOUCHSCRIPT_TUIO宏是否真的已启用 → Console 窗口有没有连接报错。

坑位二：触点位置偏移或上下镜像。先确认游戏窗口分辨率与触摸设备输出分辨率一致；若出现镜像，多半是坐标系翻转没对齐，检查一下显示设备的原点设置。

坑位三：只想响应手指，却收到一堆 blob/object 噪声。回到 Input Types，只保留 Cursors 即可，把不需要的输入类型关掉。

结语与延伸资源

TUIO 只是 TouchScript 众多输入源之一，但它背后那套统一的手势体系同样服务于 iOS、Android 和 Windows 原生触摸——意味着你今天为 TUIO 写的交互代码，明天可以直接复用到移动端项目，投入产出比相当可观。若想深入：

• TUIO 模块源码：Source/Assets/TouchScript/Modules/TUIO/
• 官方示例场景：Source/Assets/TouchScript/Examples/
• 输入源与坐标映射接口：Source/Assets/TouchScript/Scripts/InputSources/

从克隆仓库到第一个能响应的触摸事件，整个流程用不了半天。把环境配好、组件挂上、事件接住，你的互动应用就能真正"接住"用户的每一次触摸了。

【免费下载链接】TouchScriptComplete multi-touch solution for Unity: iOS, Android, Windows, TUIO.项目地址: https://gitcode.com/gh_mirrors/to/TouchScript