开发者 / Godot / 触觉设置

Godot 触觉设置

先用现成的节点让物体可被感知，再通过 GDScript 实现。

触觉的工作原理

每只被追踪的手都带有六个位于物理层 20 的 HapticFingerTrigger 区域：五个指尖和手掌。HEXR 的节点都是监视该层的 Area3D：当手指触发器进入时，节点就能知道是哪只手、哪根手指，并通过这只手的 PressureTrackerMain 发送到对应的手套。共有六个通道（Thumb 到 Palm），每个通道都可以施压（约 15–50 kPa）、振动（0.1–40 Hz）或脉冲。

无需代码

节点	用途	设置
HexRGrabbable	作为 `RigidBody3D` 的子节点：用捏合或手掌将物体拿起；每根接触它的手指都会受压	`type_of_grab` pinch / palm，`haptic_strength` 10–60
HexRPhysicalButton	由指尖按下的按钮；按下期间，手指能感受到它	按压它的手指（`thumb` … `palm`）、`press_pressure`、`cap` 和 `travel`；信号 `pressed` 和 `released`
SpecialHaptics	一个区域，对其中的任何物体施加效果	`type_of_haptics`：custom vibrations、custom haptics、fountain、rain drop、heart beat、hand squeeze
HexRInteractableHaptics	作为 Godot XR Tools 可拾取物体（pickable）的子节点：被握住时施加压力，压力随手握紧的程度变化	`strength`、`follow_grip`，以及作用的手指
HexRUsable	当所选手指在其周围弯曲和伸展时发出信号	需要弯曲的手指（`thumb` … `little_finger`）、`use_threshold`
ProximityCheck	当有手位于其中时，开启手部靠近检测（见下文）	`clear_delay`；在 Inspector 中点击 Auto Set Up 会添加其碰撞形状

节点名和属性名沿用 Unity 插件包，采用 Godot 的 snake_case 写法。将每个节点的碰撞形状调整为手指应能感受到触觉的空间大小。区域会跳过手部靠近检测：手位于区域内部本身就说明了一切。

通过代码

单根手指

gdscript

var hand := HexR.controller(HaptGloveHandler.HandType.RIGHT)   # the hand's PressureTrackerMain

# Pressure: finger, on/off, intensity 0.1-1, ramp speed 0.1-1, skip the hand-near check
hand.custom_single_haptics(Haptics.Finger.INDEX, true, 0.5, 1.0, false)

# Vibration: finger, on/off, intensity 0.1-1, frequency 0.1-40 Hz, skip the hand-near check
hand.custom_single_vibrations(Haptics.Finger.PALM, true, 0.7, 12.0, false)

# The components' 10-60 strength scale, as the 0.1-1 intensity above
var intensity := PressureTrackerMain.strength_to_intensity(30.0)

多根手指

gdscript

# One entry per channel: Thumb, Index, Middle, Ring, Pinky, Palm
var grip := [true, true, true, false, false, false]

hand.trigger_custom_haptics_increase(grip, 0.6, 1.0)   # pressure 0.1-1, speed 0.1-1
hand.trigger_custom_vibrations(grip, 0.7, 12.0)        # intensity 0.1-1, frequency 0.1-40 Hz
hand.trigger_all_haptics_increase(0.5)                 # every channel
hand.trigger_pinch_pressure(0.6)                       # thumb and index together

原始命令

gdscript

# Build the bytes yourself and send them: byte-for-byte what the Unity package sends.
var glove := HexR.right_hand   # the HaptGloveHandler; Unity: HexRManager.Instance.rightHand
glove.bt_send(glove.haptics.hexr_pressure(Haptics.Finger.INDEX, true, 0.8, 1.0))
glove.bt_send(glove.haptics.hexr_vibration(Haptics.Finger.PALM, true, 18.0, 0.7))
glove.bt_send(glove.haptics.hexr_pulse(Haptics.Finger.THUMB, true, 3.0, 0.6, 5))

按压接触的手指

gdscript

extends Area3D
## Presses exactly the finger or palm that touches this area, and lets go when it leaves.
## Its collision mask must include layer 20 (hexr_touch).

@export_range(0.1, 1.0) var intensity := 0.5

func _ready() -> void:
    area_entered.connect(_on_area_entered)
    area_exited.connect(_on_area_exited)

func _on_area_entered(area: Area3D) -> void:
    if area is HapticFingerTrigger:
        area.trigger_fix_pressure(intensity)   # 0.1-1, skips the hand-near check

func _on_area_exited(area: Area3D) -> void:
    if area is HapticFingerTrigger:
        area.remove_haptics()

松开

gdscript

hand.remove_index_haptics()      # one finger: remove_thumb_haptics() ... remove_palm_haptics()
hand.remove_all_haptics()        # every channel's pressure on this hand
hand.remove_all_vibrations()     # every channel's vibration on this hand
HexR.right_hand.release_all_channels()   # everything on the glove, both paths, in one write

手部靠近检测

PressureTrackerMain 中受检测限制的调用（single_*、trigger_* 和捏合调用）只在手靠近某个物体时才会生效：正在抓取、正在戳按悬停，或位于 ProximityCheck 内部。这样可以防止误发的调用对空手施压。向自定义调用传入 bypass_hand_check = true 即可跳过此检测；remove_* 调用始终不受此限制。

手套会保持最后的压力

手套本身不会自动释放压力。插件会在断开连接、暂停和退出时释放压力，但如果应用崩溃或连接中断，手套会持续施压：此时请关闭手臂模块。