XR 控制器与输入设备

手柄不可替代的三个理由：
  1. 触觉反馈 —— 只有物理按键与振动能给出「按下去了」的确认感
  2. 精确输入 —— 摇杆能连续控制，手势做不到细粒度连续量
  3. 低疲劳 —— 手自然下垂握持，可长时间使用

1. 由内向外（Inside-out，头显摄像头追踪手柄）
   头显上的摄像头看到手柄上的红外 LED 阵列
   原理：已知 LED 在手柄上的三维布局，从图像反解位姿（PnP）
   优点：无需外部基站，一体机标配
   缺点：手柄出画即丢失，需 IMU 补盲

2. 由外向内（Outside-in，基站追踪）
   外部基站发射激光扫过手柄上的光敏传感器
   原理：按激光到达时刻计算角度，三角定位
   优点：精度极高、延迟低
   缺点：需要基站、安装麻烦、范围受限

3. 纯 IMU 递推
   陀螺仪 + 加速度计积分
   优点：永不丢追踪（短期内）
   缺点：漂移严重，必须靠视觉校正

由内向外追踪的完整链路：
  红外 LED 阵列（手柄上，通常 20~30 颗）
    → 头显摄像头（通常 4 颗）拍摄
    → 检测 LED 光点
    → 与已知的 LED 三维布局做匹配
    → PnP 求解位姿
    → 与 IMU 数据融合（EKF）
    → 输出 60~120 Hz 的位姿

关键：视觉频率低（30~60 Hz），IMU 频率高（1000 Hz），
      两者融合才能输出平滑高频的位姿。

追踪失效的典型场景：
  □ 手柄离开摄像头视野（手放下、举到身后）
  □ 强红外干扰（阳光、其他设备的红外）
  □ 手柄被遮挡（被身体或其他物体挡住）
  □ LED 脏污或损坏

失效时多数设备切到「仅 IMU」模式，短时间可用但会漂移，
超过一定时间未恢复则标记为「未追踪」，应用必须处理。

典型 6DoF 手柄的输入通道：
  □ 摇杆 ×2（左右手，带按下 Click）
  □ Trigger ×2（模拟量，0~1）
  □ Grip ×2（模拟量或开关）
  □ A/B 按钮（右手）
  □ X/Y 按钮（左手）
  □ Menu / System 按钮
  □ 电容触摸（拇指是否放在按键上）

模拟量与开关的差异：Trigger 可做「轻按/重按」的力度区分，
A/B 开关量只有按下与松开。

// Unity XR Input 的读取（示意，旧版 InputDevice API）
var rightHand = InputDevices.GetDeviceAtXRNode(XRNode.RightHand);

// 模拟量：Trigger
if (rightHand.TryGetFeatureValue(CommonUsages.trigger, out float trigger))
    _triggerValue = trigger;   // 0.0 ~ 1.0

// 开关量：Primary Button（边沿触发）
if (rightHand.TryGetFeatureValue(CommonUsages.primaryButton, out bool pressed))
    if (pressed && !_wasPressed) OnPrimaryPressed();
_wasPressed = pressed;

手感调优的关键参数：
  1. 死区（Dead Zone）
     摇杆漂移或轻触会误触发，需死区；过大则小幅度操作无效
     经验值：内死区 0.1~0.15，外死区留 0.05 余量

  2. 响应曲线（Response Curve）
     线性曲线在精细操作时不够灵敏，常用「先慢后快」的 S 曲线
     对瞄准类操作，S 曲线能兼顾精度与速度

  3. 触发阈值（Threshold）
     Trigger 判定为「按下」的阈值不宜取 1.0，常用 0.7~0.8

  4. 消抖（Debounce）
     机械按键有抖动，边沿触发要加消抖（约 20~50 ms）

// 摇杆死区与响应曲线
Vector2 ApplyDeadZone(Vector2 input, float inner = 0.12f, float outer = 0.95f) {
    float mag = input.magnitude;
    if (mag < inner) return Vector2.zero;
    float t = Mathf.InverseLerp(inner, outer, mag);
    return input.normalized * (t * t);   // 平方曲线：小幅度更精细
}

切换的触发条件：
  1. 手柄放下（未被追踪）→ 切到手部追踪
  2. 手柄被拿起（恢复追踪）→ 切回手柄
  3. 用户显式设置（只用手柄 / 只用手势）

切换的三个工程问题：
  □ 抖振：手柄追踪在边缘时反复丢失/恢复，导致频繁切换
    → 加滞回（Hysteresis）：丢失超过 500 ms 才切换
  □ 状态迁移：切换时交互状态如何保持
    → 正在抓取的物体应随切换平滑转移，而不是掉落
  □ 视觉表现：手模型与手柄模型的过渡
    → 做淡入淡出，避免突然出现/消失

// 带滞回的手势/手柄切换
enum InputMode { Controller, Hands }

InputMode UpdateMode(InputMode current, bool controllerTracked, float dt) {
    if (controllerTracked) { _lostTime = 0f; return InputMode.Controller; }
    _lostTime += dt;
    // 只有丢失超过 0.5 秒才切到手势，避免抖振
    if (current == InputMode.Controller && _lostTime > 0.5f)
        return InputMode.Hands;
    return current;
}

抽象的三个层次：
  第 1 层：原始输入（Raw Input）
    Trigger 值、摇杆向量、按键状态

  第 2 层：动作（Action）
    「选择」「抓取」「返回」「菜单」—— 语义化动作

  第 3 层：意图（Intent）
    「选中了物体 A」「把物体放到位置 B」—— 带上下文的意图

多数项目做到第 2 层就够，复杂的交互系统需要第 3 层。

// 基于 Action 的输入抽象（示意）
public enum XRAction { Select, Grab, Back, Menu, Teleport, Rotate }

public interface IInputProvider {
    bool GetButtonDown(XRAction action);       // 本帧按下
    bool GetButton(XRAction action);           // 持续按住
    float GetAxis(XRAction action);            // 模拟量
    Vector2 GetThumbstick();                   // 摇杆
}

// 手柄实现：Select 绑到右手 Trigger
// 手势实现：Select 绑到捏合开始
// 交互逻辑只依赖 IInputProvider，不感知具体设备

映射的工程做法：
  □ 维护一张「动作 → 各平台按键」的映射表（配置文件）
  □ 运行时探测平台，加载对应映射
  □ 提供「按键提示」的图标资源，随映射切换
  □ 允许用户自定义映射（无障碍需求）

按键提示（Button Prompt）的细节：
  画面提示「按 A 键」在不同平台要变成对应的按键图标，
  这是最容易被忽略但最影响体验的跨平台细节。

# 跨平台输入映射表（示意）
platforms:
  quest:
    Select: right.trigger
    Back: left.primary
    Menu: left.menu
  index:
    Select: right.trigger
    Back: right.secondary
    Menu: system
  visionos:
    Select: hand.pinch
    Back: hand.wristFlick

触觉设备的能力：
  1. 振动马达（LRA / ERM）
     只能表达「强度 + 时长 + 频率」的粗略振动
     可做：按键反馈、碰撞、抓取确认、枪械后坐

  2. 力反馈（Haptics with force）
     能给出「阻力」「卡顿」等力学感受
     需要专用硬件（如带张力机构的手套）

  3. 自适应扳机（Adaptive Trigger）
     扳机的阻力可编程（PSVR2 的亮点）
     可做：拉弓的阻力、扣扳机的两段式手感

// 振动反馈（Unity，示意）
void HapticPulse(float amplitude, float duration, float frequency) {
    var device = InputDevices.GetDeviceAtXRNode(XRNode.RightHand);
    if (device.TryGetHapticCapabilities(out var caps) && caps.supportsImpulse) {
        // amplitude 0~1，frequency 0 表示用默认频率
        device.SendHapticImpulse(0, amplitude, duration);
    }
}

// 用法：抓取成功给一个短促的确认脉冲
void OnGrabSuccess() => HapticPulse(0.4f, 0.05f, 0f);

触觉设计的原则：
  1. 短促而克制：长时间振动让人烦躁，确认类反馈 30~80 ms 足够
  2. 与视觉/听觉同步：误差超过 50 ms 就「不同步」
  3. 用强度表达程度：轻碰用 0.2，重击用 0.8
  4. 不要滥用：每个交互都振 = 用户很快关闭振动

延迟链路拆解：
  物理动作（按下按键）
    → 设备采样（5~15 ms）→ 无线传输（5~20 ms）
    → 应用轮询（90 Hz 即 11 ms 一帧）→ 逻辑处理（1~5 ms）
    → 渲染（5~10 ms）→ 显示输出（2~5 ms）
  合计约 20~60 ms

体感阈值：< 20 ms 几乎无感；20~50 ms 可察觉但可接受；
> 50 ms 明显迟滞，影响操作精度。

降低延迟的手段：
  1. 提高输入采样与轮询频率（不要等每帧才读一次）
  2. 输入预测：对连续输入（如摇杆、手部位姿）做外推
  3. 输入缓冲（Input Buffering）：
     允许「在动作窗口前一小段时间内的输入」被接受，
     提升手感（详见游戏手感专题）
  4. 避免主线程阻塞：输入处理要独立于重逻辑

// 输入缓冲：在动作可执行前 150ms 内的输入也被记住
void Update() {
    if (GetButtonDown(XRAction.Select)) _bufferTime = 0.15f;
    _bufferTime -= Time.deltaTime;
}
bool TryConsumeSelect() {
    if (_bufferTime > 0f && CanActNow()) { _bufferTime = 0f; return true; }
    return false;
}

需要覆盖的能力差异：
  1. 单手用户
     所有操作应能用单手完成，不做双手强制手势
     提供「单手模式」，把双手操作映射到单手

  2. 运动能力受限
     减少精细操作要求，加大按键容错
     提供不依赖精确手部动作的路径（语音、注视停留、头部指向）

  3. 听力障碍
     音效反馈必须有视觉替代

  4. 色觉障碍
     交互反馈不能只靠颜色，要加形状与音效

  5. 坐姿用户
     不强制站立或转身，提供坐姿模式

工程做法：
  □ 键位重映射（Remapping）—— 允许自定义所有按键
  □ 灵敏度与死区可调 —— 适配不同运动能力
  □ 多种输入通道并存 —— 手柄/手势/语音/眼动都可用
  □ 单键模式 —— 用一个按键完成主要操作

调试工具：
  □ 输入可视化：实时显示按键状态、摇杆位置、Trigger 值
  □ 输入回放：录制一段输入序列，可重复播放
  □ 延迟测量：用高速相机拍摄「按下 → 画面响应」的帧差

测试要点：
  □ 每个平台、每种输入设备都要单独测
  □ 边界情况：追踪丢失、手柄没电、同时按多键
  □ 长时间使用：手柄漂移、按键磨损
  □ 无障碍路径：单手、坐姿、语音是否可用

追踪：
  □ 处理追踪丢失（IMU 兜底 + 明确未追踪状态）
  □ 视觉与 IMU 融合，输出高频平滑位姿

按键与手感：
  □ 摇杆设死区与响应曲线
  □ 模拟量（Trigger）用阈值而非等 1.0
  □ 边沿触发加消抖
  □ 输入缓冲 100~150 ms

抽象与跨平台：
  □ 交互逻辑绑定「动作」而非具体按键
  □ 映射表配置化，按键提示随映射切换
  □ 提供键位重映射

触觉与无障碍：
  □ 触觉短促克制，与视听觉同步（误差 < 50 ms）
  □ 单手可完成全部操作，灵敏度与死区可调