简介Unity LeapMotion投篮Demo是一份面向Unity开发者和体感交互初学者的实操案例包重点展示如何利用LeapMotion手势识别技术在虚拟场景中实现自然、直观的投篮操作。压缩包大小约35.43MB可直接下载后导入Unity运行学习。目前已有463人学习/下载适合希望掌握手势交互与物理模拟结合方法的读者。Demo完整演示了从手部骨骼数据解析、托球与投掷手势判定到篮球抛物线飞行与得分判定的整个交互流程涉及LeapMotion SDK集成、C#控制脚本编写、Unity物理引擎调参、以及音效与UI反馈设计等核心环节。通过研读工程结构和关键脚本可学会如何平滑映射手部运动、设置投篮力度阈值、利用刚体组件模拟篮球轨迹同时了解优化手势识别性能与多环境调试的常见策略为后续开发更复杂的体感游戏打下基础。1. Unity与LeapMotion投篮Demo手势识别投篮这件事值得认真拆一遍拿到这个Unity与LeapMotion投篮Demo的第一反应是这不就是个把识别到的手部动作映射到球上的示例吗。但真正跑起来之后你会发现手部识别和投篮手感是两个完全不同的问题识别只要做到知道手在动而投篮要做到知道手在什么时刻用多大力度往哪个方向甩出去。这个Demo把这两层分开处理用LeapMotion的手部骨骼数据做速度判定用Unity的物理引擎处理抛射轨迹中间还卡着坐标系对齐、脱手时机、篮筐碰撞几个坑。对想搞手势交互、体感游戏或虚拟现实操作模拟的开发者来说这套拆解比单个投篮效果本身更有价值值得照着复现一遍。2. 环境与数据接入把LeapMotion骨骼数据变成Unity能用的输入2.1 版本匹配与SDK初始化先聊第一个高频翻车点SDK的版本和Unity版本匹配问题。LeapMotion的SDK在Unity里有对应的核心资源包导入之后会自动挂上LeapProvider、LeapServiceProvider这类组件。我一般建议先确认两件事一是Unity本身用的是哪个渲染管线和输入系统二是Package Manager里已经装过的XR或Input System版本。LeapMotion的例程大多是老式Input Manager写法如果你项目同时开了新版Input System又没做兼容就会出现手部数据一直为零的情况——第一帧就没有Hand后面所有逻辑全是空转。这个状态不报错只能靠打印帧数才能发现。等版本匹配没问题再看场景搭建。常见做法是场景里挂一个LeapServiceProvider把Tracking Mode设成Desktop或HeadMounted。桌面模式适合摄像头平放头戴模式适合头盔上安装。这个Demo是桌面投射场景摄像头放在屏幕下方或侧前方朝上倾斜一个角度让手在抬手投篮的整个轨迹里都不出视野。接下来初始化代码using Leap; using Leap.Unity; using UnityEngine; public class HandInputReader : MonoBehaviour { private LeapProvider provider; private void Start() { // 场景里必须存在 LeapProvider 或 LeapServiceProvider provider FindObjectOfTypeLeapProvider(); if (provider null) { Debug.LogError(未找到 LeapProvider请确认 SDK 组件已挂载); } } private void Update() { // CurrentFrame 拿到的是一整帧的手部追踪数据 Frame frame provider.CurrentFrame; if (frame null || frame.Hands.Count 1) { return; // 没有手直接跳过 } Hand hand frame.Hands[0]; Debug.Log($掌心位置: {hand.PalmPosition}); } }这段代码的逻辑很简单每帧从provider拿一次FrameFrame里包含手、手指、骨骼等信息。PalmPosition是Leap坐标系下的掌心位置单位是毫米。注意这里提到毫米是因为后续如果直接把这个数值塞给Unity的Transform会出现位置放大了1000倍的怪异现象需要做一个毫米到米的换算也就是除以1000或者记作Vector3.Scale之类的处理。参数方面LeapProvider在Inspector面板里有个Tracking Mode选项Desktop模式下的识别距离一般在25毫米到600毫米之间超过这个范围会出现骨骼抖动这个边界在搭场景时就要考虑进去。2.2 手部骨骼数据读取与映射LeapMotion的手部模型由掌心加五根手指组成。每根手指有四个骨节指掌骨、近节指骨、中节指骨、远节指骨。在Unity里对应的是Finger.Bone(BoneType)这个方法能拿到每一节的长度、方向和旋转矩阵。做投篮Demo时最常用的是指尖与掌心的相对位置以及手指弯曲程度。读取手指骨节的代码可以这样写// 以食指为例读取近节指骨与远节指骨方向 using Leap; using UnityEngine; public class FingerBendReader : MonoBehaviour { public void ReadBend(Hand hand) { Finger finger hand.Fingers[(int)Finger.FingerType.TYPE_INDEX]; Bone proximal finger.Bone(Bone.BoneType.TYPE_PROXIMAL); Bone distal finger.Bone(Bone.BoneType.TYPE_DISTAL); // 两个骨节方向向量的夹角就是弯曲程度 Vector3 proximalDir proximal.Direction.ToVector3(); Vector3 distalDir distal.Direction.ToVector3(); float bendAngle Vector3.Angle(proximalDir, distalDir); Debug.Log($食指弯曲角: {bendAngle}); } }逻辑很直接骨节的Direction是该骨节在Leap坐标系下的朝向向量两个向量夹角越大说明手指弯曲越厉害。BendAngle到50度以上基本就属于握拳状态投篮时手指一般是半屈的大约30到50度。这里有个容易忽略的点Leap坐标系是右手坐标系X轴向右Y轴向上Z轴朝向使用者。Unity是左手坐标系X轴向右Y轴向上Z轴朝向屏幕内。两者不能直接互换。一般情况下把Leap的旋转量和位置量直接丢给Unity会出现轴向反转现象。我习惯用一张对照表来对齐Leap轴向Unity轴向说明XX左右一致YY上下一致Z-Z朝向相反需要取反位置坐标同理Leap的Z值取负之后再赋给Unity的Z轴。方向向量也一样处理尤其是PalmNormal和PalmVelocity这两个字段不取反的话球会飞向你身后。2.3 掌心朝向、手速与手型关键帧手型识别是做投篮判定前的最后一步。很多开发者会把握住球理解成握拳实际不是。投篮前的手型应该是五指自然张开、掌心朝前手指微微弯曲。LeapMotion提供的PalmNormal是掌心平面的法线也就是掌面朝向PalmVelocity是手掌移动速度。判断手型是否满足投篮准备我用的是三个关键帧条件// 判断当前手势是否符合持球准备状态 private bool IsHoldingPose(Hand hand) { // 掌心向上倾斜配合一个合理阈值 Vector3 palmNormal hand.PalmNormal.ToVector3(); float upFactor Vector3.Dot(palmNormal, Vector3.up); bool facingUp upFactor 0.3f; // 检查拇指、食指、中指的弯曲程度 float bend 0f; for (int i 0; i 3; i) { Finger f hand.Fingers[i]; Bone b1 f.Bone(Bone.BoneType.TYPE_PROXIMAL); Bone b2 f.Bone(Bone.BoneType.TYPE_MEDIAL); bend Vector3.Angle(b1.Direction.ToVector3(), b2.Direction.ToVector3()); } bend / 3f; // 弯曲角在 30~60 之间算半屈满足持球手型 return facingUp bend 30f bend 60f; }这段代码把掌心朝向和手指弯曲一起判断避免把手背朝上或握拳状态误判为投篮准备。向量点积结果在-1到1之间upFactor大于0.3意味着掌心基本朝上或斜上方。实际调试的时候我会在场景里把IsHoldingPose的结果画在屏幕上写成布尔量。这样自己抬手晃一晃能看到状态切换点在哪里。LeapMotion的帧率在60到120帧手型切换的瞬间会有三四帧的过渡期不要在这个区间做释放判定否则会把抓球和投篮混在一起。3. 投篮判定核心脱手时机、投掷力度与球体物理3.1 脱手判定速度峰值与时间窗口投篮手感最关键的就是出手时机。LeapMotion给的是PalmVelocity单位是米每秒但直接看速度很容易被瞬时抖动干扰。我采用的脱手判定算法是这样的先记录手在持球准备状态下的每一帧速度设定一个释放阈值当速度连续几帧高于阈值并且已经越过峰值开始减速时才判定为出手。public class ShootDetector : MonoBehaviour { [SerializeField] private float releaseThreshold 1.5f; [SerializeField] private float peakWindow 0.15f; private float peakSpeed 0f; private bool isArmed false; private float windowTimer 0f; private HandInputReader input; private void Update() { Hand hand input.GetPrimaryHand(); if (hand null) { isArmed false; return; } float speed hand.PalmVelocity.ToVector3().magnitude; // 速度超过阈值进入待释放状态 if (!isArmed speed releaseThreshold) { isArmed true; peakSpeed speed; windowTimer peakWindow; } if (!isArmed) return; // 记录峰值 if (speed peakSpeed) { peakSpeed speed; windowTimer peakWindow; } // 时间窗耗尽判定为有效出手 windowTimer - Time.deltaTime; if (windowTimer 0f) { OnShoot(hand); isArmed false; } } }这个逻辑的核心是一个峰值窗口概念。投篮动作从启动到结束大约在0.2到0.3秒之间真正脱手的一瞬间是速度达到峰值之后自然回落的那一刻。窗口太长会把缓慢抬手也判定成出手窗口太短又会在速度还没有完全降下来时提前触发。0.15秒是我在多个动作下试出来的比较稳定的值如果你的项目里手臂动作幅度更大可以适当放到0.2秒。触发投篮后回调里要拿到的是脱手时的速度和方向。这里有个细节PalmVelocity在脱手瞬间已经比峰值低了一些直接用当前帧的速度会导致球的初速度偏小。我的做法是把peakSpeed和当前速度做一个加权大约七三开让球的初速度更接近真实出手力量。3.2 投掷方向与力度计算投掷方向不应该用某一帧的瞬时速度而应该用出手前一小段位移的平均方向。这里有一个普遍容易踩的坑手掌最后的朝向不等于球的飞行方向投出去的那一刻掌心会有一个向前甩的鞭打动作瞬时速度方向可能偏上但整体轨迹方向相对稳定。计算投掷方向与力度// 记录出手前 0.1 秒内的手部位置计算平均位移 public Vector3 CalculateReleaseVelocity(Hand hand, float historyWindow 0.1f) { ListVector3 positions handPositions.GetRecent(historyWindow); if (positions.Count 2) return Vector3.zero; Vector3 start positions[0]; Vector3 end positions[positions.Count - 1]; // 位移除以时间得到平均速度向量 Vector3 velocity (end - start) / historyWindow; // 力度上限防止快速挥手时初速度爆表 float magnitude Mathf.Clamp(velocity.magnitude, 3f, 20f); Vector3 direction velocity.normalized; return direction * magnitude; }代码里用了一段历史位置缓存来计算平均速度而不是用LeapMotion的PalmVelocity字段。因为PalmVelocity在帧数据丢失或手部短暂遮挡的时候偶尔会蹦出一个异常大值而用历史位移滑动平均能得到更平滑的结果。这里的handPositions是一个环形缓存队列我通常保留12帧左右的数据按帧率60fps算正好覆盖0.1秒到0.2秒的轨迹。力度范围3到20米每秒是篮球投射的合理区间。太低了球根本到不了篮筐太高了物理引擎会出问题。物理模拟时每秒20米相当于一个很重的暴扣现实当中人类的甩手速度上限大约在每秒十几米这个上限设得再高也没意义反而会让球的轨迹失真。3.3 球体刚体与碰撞体参数设置投篮Demo里的篮球是一个SphereCollider加Rigidbody。刚体参数看起来简单但影响手感的主要有三个碰撞检测模式、插值方式和阻力系数。private void SetupBasketball(Rigidbody rb) { // 快速运动的球必须用连续碰撞检测 rb.collisionDetectionMode CollisionDetectionMode.ContinuousDynamic; rb.interpolation RigidbodyInterpolation.Interpolate; rb.mass 0.6f; rb.drag 0.05f; rb.angularDrag 0.1f; }逐项解释一下。碰撞检测模式设成ContinuousDynamic是因为球在出手瞬间速度可以到每秒十几米以60帧计算每帧移动距离超过0.2米而篮筐边框的厚度可能只有0.05米离散碰撞检测会直接穿过去。ContinuousDynamic会做射线扫描避免高速穿透。Interpolate是让刚体位置在渲染帧之间平滑插值否则看到的球会有轻微顿挫感。质量0.6公斤在现实里偏轻但在游戏手感里能让球被篮筐弹开时更跟手。阻力值不要设到0保留一点点空气阻力能让长距离投篮的轨迹末端稍微下垂更接近真实手感。篮筐的碰撞体建议用MeshCollider不要用BoxCollider叠加。MeshCollider贴合篮筐边缘和篮网的形状球弹到筐边会有一个自然的反弹效果。但MeshCollider不能和普通的Rigidbody球做快速碰撞时开Concave模式否则又会出现穿透。物理参数调优的时候我习惯开一个独立测试场景屏蔽所有输入逻辑只用一个初始速度向量把球投出去。这样能先排除识别层的干扰单独验证物理层是否合理。物理层稳定了再接回LeapMotion数据问题定位会清晰很多。4. 常见问题排查误投、抖动与篮筐穿透五个实战案例4.1 手部抖动导致误投现象手没有明显投篮动作球偶尔自己飞出去。尤其是站在电脑前正常晃动鼠标时球会突然脱手。原因LeapMotion在快速变速时会输出瞬时速度尖峰。即使手掌只是快速从画面一侧划到另一侧速度也可能突破1.5米每秒的阈值。根因是阈值判定只用了当前帧速度没考虑前后连续性和手型条件。解决把脱手条件改成三要素同时满足手型处于持球准备状态、速度超过阈值、时间窗口内有明显的加速上升段而不是一个孤立的峰值。另外将速度阈值从1.5提高到2.0排除大部分正常移动。提示排查的时候可以把当前速度值实时打印在屏幕上观察正常操作下的速度范围按这个范围加个20%余量作为阈值。4.2 脱手判定总是晚半拍现象动作已经做完了球才慢悠悠地飞出来感觉像是延迟了100到200毫秒。原因出手判定放在减速段结束的窗口末点。一旦手在触发投篮后立刻停住窗口计时还没走完球就不能及时释放。再加上我前面提到的加权初速度只在回调里算了一次错过峰值之后速度已经掉了很多。解决把出手时机改到速度峰值之后的第一帧也就是isArmed状态维持到窗口前半段时检测到速度开始下降就直接trigger等窗口是为了兜底不是必须等满。具体做法是当currentSpeed peakSpeed * 0.7时提前结束窗口。4.3 篮球穿透篮筐现象正常投篮后球从篮筐中心飞过没有弹筐也没有得分直接从筐下面穿出去了。原因球体碰撞检测模式是Discrete。当球速超过每帧移动距离大于篮筐边框厚度时物理引擎会认为球在上一帧和下一帧之间直接跳过了碰撞体于是穿透。解决见3.3节把球体Rigidbody的CollisionDetectionMode改成ContinuousDynamic同时确保篮筐MeshCollider不是Convex。如果依然穿透把球体SphereCollider的Radius加大10%用半径补偿边框的物理厚度。4.4 坐标系轴向错位导致投篮方向混乱现象在画面右侧抬手投篮球往左前方飞或者屏幕上方的动作被识别成左右方向。原因LeapMotion是右手坐标系Unity是左手坐标系没有做Z轴取反和轴向映射。PalmPosition、PalmVelocity、PalmNormal三个字段都必须映射只映射其中一个会出现混合错乱。解决写一个统一的坐标转换函数// Leap 右手坐标转 Unity 左手坐标 public Vector3 LeapToUnity(Vector3 leapVec) { return new Vector3(leapVec.x, leapVec.y, -leapVec.z); }所有从Leap拿出来的向量包括位置、速度、方向都过这一层校准。最后再乘一个毫米转米的系数确保位置量级正确。4.5 不同摆动弧线投出去的球轨迹不稳定现象相同手势力度有时球投得高有时投得平落点分散很大。原因出手判定点固定在速度峰值帧但峰值帧的瞬时速度方向受手臂末端动作影响很大。挥手抛物线和前推动作在峰值时的方向差异达到30度以上直接用峰值做方向和力度计算轨迹自然不稳定。解决用出手前0.1秒的位置平均向量代替瞬时速度向量也就是3.2节的CalculateReleaseVelocity方法。把峰值帧只当作触发信号方向和力度从历史轨迹里提取这样能把落点分散度明显收窄。5. 投篮精度调优轨迹可视化、辅助瞄准与手感参数化5.1 轨迹预测用物理积分画出一条预测线调试投篮手感最大的问题是你永远不知道当前这个力度的球会不会进筐。与其一遍遍实投看结果不如先在场景里画出预测轨迹。用简单的物理积分就能做不需要每帧调用Physics.Simulate。using UnityEngine; public class TrajectoryPreview : MonoBehaviour { public LineRenderer line; [SerializeField] private int steps 30; [SerializeField] private float stepInterval 0.02f; public void Draw(Vector3 startPos, Vector3 initialVelocity) { Vector3[] points new Vector3[steps]; Vector3 pos startPos; Vector3 vel initialVelocity; for (int i 0; i steps; i) { // 每步叠加一个重力增量 vel Physics.gravity * stepInterval; pos vel * stepInterval; points[i] pos; } line.positionCount steps; line.SetPositions(points); } }这段代码把每一帧的位置采样点连成一条线。逻辑可以看出是简化的向前欧拉法误差比真实物理稍大但作为调试辅助足够。步骤30步步长0.02秒正好覆盖0.6秒飞行时间。篮球从出手到进筐大约需要0.4到0.6秒。当你让这条线实时跟着手的速度变化时调试就从凭感觉扔变成了看轨迹曲线调整。我一般会在场景里用不同颜色区分预测线与实际球的运动轨迹两者偏差大就说明物理参数不一致偏差小就说明识别层的出手方向计算是对的。5.2 辅助瞄准线与投篮点提示辅助瞄准线可以分为两级。第一级是直接显示从球指向篮筐的虚线帮助你确认出手方向第二级是检测预测轨迹是否穿过篮筐平面。穿过篮筐平面的判定逻辑是对预测点做循环如果某一段起点在篮筐平面以上、终点在平面以下就判定这一帧球会穿过篮筐。// 判断预测轨迹是否经过篮筐平面 public bool IsPassingThroughHoop(Vector3[] points, Vector3 hoopCenter, Vector3 hoopNormal) { for (int i 0; i points.Length - 1; i) { float dotA Vector3.Dot(points[i] - hoopCenter, hoopNormal); float dotB Vector3.Dot(points[i 1] - hoopCenter, hoopNormal); // 符号变化说明轨迹穿过了篮筐所在平面 if (dotA * dotB 0f) { return true; } } return false; }逻辑说明把篮筐看作一个无限平面平面法线指向篮筐正上方。判断球轨迹的相邻两个点是否分别位于平面两侧如果是说明球在这一段会穿过篮筐平面。这个判定比碰撞检测更高速可以提前把辅助精度显示出来提示玩家瞄准线已经到位。辅助瞄准线不要一直显示否则玩家会一直盯着线而不是做动作。我习惯只在持球准备状态下、手部速度超过70%阈值时才显示速度降下来后自动隐藏。这样不会干扰正常视觉。5.3 数据记录每次投篮的参数化存档与回放投篮手感不好调还有一个原因是每次出手的轨迹都难以复现。要把手感做成可调参数就得分批记录每次投篮的关键数据。我在Demo里加了一个简单的CSV记录器每次触发投篮时把这一帧的速度、方向、位置、偏移量、时间记录下来。using System.IO; using UnityEngine; public class ShotDataRecorder : MonoBehaviour { private string filePath; private void Start() { // 持久化路径下的日志文件 filePath Path.Combine(Application.persistentDataPath, shot_log.csv); File.AppendAllText(filePath, time,speed,direction_x,direction_y,direction_z\n); } public void RecordShot(Vector3 velocity, float speed) { string line ${Time.time},{speed},{velocity.x},{velocity.y},{velocity.z}; File.AppendAllText(filePath, line \n); } }这个记录逻辑的价值在于把每一条投篮动作变成一个可比较的样本。连续采集四五十条数据后用表格按速度排序你就能看出哪个速度区间命中率高哪个速度区间总是偏左偏右。这个文件也方便后续用外部工具做统计分析。回放功能我做的比较简单读取CSV把每条数据生成一个初始速度向量复用5.1节的轨迹绘制接口在场景里同时画出几十条预测线。一串线叠在一起落点分布一目了然比一次一次扔球直观得多。从这个角度讲数据记录不算临时工具而是调试手感的正式基础设施。6. 收尾技巧用强制可视化流程把“手感”变成可调参数投篮Demo做到后期最让我头疼的问题已经不是代码逻辑了而是手感两个字。同一套代码我给同事演示时能连进三球自己上手就各种打铁。差异就在抬手习惯上有人手腕动作多有人整条手臂都在发力。这时候如果只看最终进没进球根本定位不了问题在哪。从那以后我每次调这类手势交互项目都强制自己先过一遍可视化流程而不是急着改参数。流程固定为四步第一步在场景里把手的每秒速度、加速度、脱手标志全部用Debug.DrawLine画出来第二步把预测轨迹线和实际球的飞行轨迹同时显示看偏差出现在出手前还是飞行中第三步开CSV记录器连续投三组每组投三十次导出数据对比落点分布第四步再改任何一个阈值、阻力、方向权重改完重复前三步。这套流程最大的好处是手感不再是一个不可言说的东西而是一堆具体数值。比如我改成出手前用0.12秒的历史位置算平均速度落点从原来的左右偏差40厘米缩小到15厘米。数值上的变化是可比较的手感变化只是它的副产品。工具层面上预测线从原有的淡蓝色改成了绿色和红色双状态绿色表示预测轨迹穿过篮筐平面红色表示不会穿过。玩家不需要看数值只要在绿色状态下投篮命中率就会自然提升这对演示场景特别重要。如果你拿这个Demo去做体感教学、VR模拟训练或者投篮数据采集我建议先保留第5章的数据记录功能别删。很多游戏在发布时为了性能把调试工具都裁掉但这个记录器只占很小开销却能让你在用户反馈手感不对时多一个排查入口。视觉反馈我用的最后一招是把篮球刚体的线速度实时映射到篮球材质的发光强度上。高速时球体微微发光低速时恢复原样。这样玩家能从余光感知自己的出手力道不需要低头看数值面板。把出手动作设计成一个完整的信息闭环手型准备、速度预警、脱手确认、轨迹预测每一步都有视觉反馈手感问题自然就少了。希望这个LeapMotion投篮Demo的拆解能帮到你至少下次遇到投篮脱手和球穿筐的时候你知道先查哪几个参数。本文还有配套的精品资源点击获取
