当前位置：首页 > news >正文

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

news 2026/8/14 19:41:20

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 监听与解析过程封装好了，你完全不需要关心底层报文长什么样。理解它只需记住三点：

单向广播：数据只从设备流向应用；
归一化坐标：报文里给的是 0~1 范围内的相对位置，像素换算交给应用端；
三类消息：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 输入源

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

在场景里新建一个空 GameObject，命名随意（比如 TUIOInput）；
给它挂上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实现"单指拖动相机、捏合缩放、多指旋转"的典型玩法。