# Physical 6DoF VR Hand Interactions, Throw Windows & Spatial Comfort in Unity 6

> Tactile 6DoF VR interactions in Unity 6 using CCGD.GameXR: articulated hands that wrap what they hold, near-grab + distance-pull cones, 6-sample sliding-window throws, snap holsters, diegetic world panels, and flat+VR parity.

- **Canonical page:** https://gamecrew.ai/techniques/unity/vr-interactions-ergonomics
- **Techniques hub:** https://gamecrew.ai/techniques
- **Engine:** Unity 6
- **Category:** vr
- **Tags:** `vr`, `xr`, `webxr`, `hands`, `fingers`, `hand tracking`, `pinch`, `grab`, `grabbable`, `grip pose`, `throw`, `socket`, `haptics`, `locomotion`, `comfort`
- **Verification:** Compile-verified pattern

## When to Use & Field Best Practices

Browser-playable VR games in Unity 6 use the studio's **`CCGD.GameXR`** kit (`Assets/CCGD/Runtime/XR/`, compiled under `CCGD_VR` — never add `com.unity.xr.*` packages, which have no WebGL build!). Great VR interactions feel physical, effortless, and sickness-free while keeping full flat-screen playability on the same link:
1. **Standing Reach Envelope & Forgiving Distance Pull**: Place interactables in the `0.75 m – 1.55 m` height band (`local-floor`) within `0.6 m` reach, and enable a `1.8 – 2.5 m` distance-pull cone (`pullRange: 2.2f`) so seated players never strain to pick up floor items!
2. **6-Sample Sliding-Window Throw Velocity**: Inside-out headset cameras often stall on the exact millisecond a player opens their grip. `XrHand.Velocity` and `GameXR.Grabbable` sample play-space velocity over a 6-frame window (rotating into world space so snap-turns and teleports never cause 300 m/s phantom spikes) and apply `rb.linearVelocity` cleanly on release.
3. **Comfort-First Horizon**: Never shake, roll, pitch, or animate camera yaw in VR (`if (!GameXR.Active)` around flat camera shake!). Keep standalone headset budgets under `200` draw calls and `300k` triangles with zero full-screen post-processing.
4. **Dual Flat + VR Parity**: Pair every `XrGrabbable` / `XrWorldButton` with a flat `GameInput.InteractPressed` fallback and document the `VR` column in `README.md` (`| Action | Keys | VR |`).
5. **The Kit's Hands Are the Hands**: Every Unity VR game draws an articulated, skinned hand per side (25 joints, five fingers, the wrist fading out, soft skin lighting that holds up in dark and bright scenes). Tracked hands follow the headset's joints; on controllers the hand is blended from captured hand poses by the inputs (open and relaxed at rest, the grip closes the middle, ring and little fingers, the trigger pinches the index to the thumb, gripping off the trigger points, the thumb rests on what it touches), held slanted 30° round the handle as a Touch controller is. Never add hand or controller models of your own; pick the look with `GameXR.HandStyle` (`Skin`, `Glove`, `Ghost`) and `GameXR.HandColor`.
6. **Fingers Close on What They Hold**: An `XrGrabbable` sits in the palm (power), between thumb and index (pinch) or in the cupped palm (sphere), chosen by size and shape (`Grip = XrGripPose.Auto`) or set per object, and each finger curls until it touches the object's colliders. Give held things colliders that match their shape (a capsule for a handle, a sphere for a ball, a thin box for a coin or card), and leave `HoldOffset` / `HoldRotation` at their defaults unless the object has a pose of its own (a gun's grip).

## Mathematical & Algorithmic Core

- **Distance-Pull Cone Score**: For aim origin $\mathbf{o}$, aim forward $\hat{\mathbf{f}}$, and target $\mathbf{p}$ at distance $d = \|\mathbf{p} - \mathbf{o}\| \le R_{\text{pull}}$:
  $$\theta = \arccos(\hat{\mathbf{f}} \cdot \tfrac{\mathbf{p} - \mathbf{o}}{d}) \le \theta_{\max}, \quad S = R_{\text{near}} + 0.25 d + 0.01 \theta^\circ$$
- **Finger Wrap by Contact Search**: Each finger blends joint by joint (parent-relative slerp) from an open pose $A$ to a closed pose $B$ by $b \in [0, 1]$; with $g(\mathbf{x})$ the distance from a point to the held object's surface and $r_j$ each joint's radius, the kit binary-searches the largest $b$ with $g(\mathbf{x}_j(b)) \ge 0.85\,r_j$ for every joint and bone midpoint, so the fingertips rest on the surface.
- **Pinch & Grab Hysteresis**: Tracked pinch strength $s = 1 - \mathrm{clamp}((d_{\text{thumb,index}} - 1.5\,\text{cm}) / 4.5\,\text{cm})$; a pinch (or grab) starts above $0.55$ and ends below $0.35$, so a finger resting at the edge never flickers a button.
- **Play-Space Throw Filtering**: Compute $\mathbf{v}_{\text{local},k} = (\mathbf{x}_k - \mathbf{x}_{k-1}) / \Delta t_k$ in rig-local space, discard a trailing near-zero stall sample when prior samples were moving, blend mean and peak ($\mathrm{lerp}(\bar{\mathbf{v}}, \mathbf{v}_{\text{peak}}, 0.55)$), and rotate into world space via `rig.TransformVector(...)`.

## Engine Implementation

### Tactile Workbench: Grabbable Relic, Pedestal Socket, 3D Button & Diegetic Gauge (`Assets/Game/Runtime/VR/RelicAltar.cs`)

```csharp
using CCGD;
using UnityEngine;

namespace Game.VR
{
    public sealed class RelicAltar : MonoBehaviour
    {
        public GameObject RelicObject;
        public Transform PedestalAnchor;
        public GameObject ConfirmButtonCap;
        public int ActivatedCount { get; private set; }

#if CCGD_VR
        XrGrabbable relicGrab;
        XrSocket pedestalSocket;
        XrPanel statusPanel;
#endif

        void Start()
        {
#if CCGD_VR
            if (RelicObject != null)
            {
                relicGrab = GameXR.Grabbable(RelicObject, radius: 0.16f, pullRange: 2.2f, input: "squeeze");
                relicGrab.Grip = XrGripPose.Sphere;   // the relic is round: fingers spread round it in the cupped palm
                relicGrab.Grabbed += hand => GameAudio.Play("pickup", RelicObject.transform.position);
            }
            if (PedestalAnchor != null)
            {
                pedestalSocket = GameXR.Socket(PedestalAnchor, radius: 0.2f, filter: g => g == relicGrab);
                pedestalSocket.Attached += _ => RefreshReadout("Relic Seated");
                pedestalSocket.Detached += _ => RefreshReadout("Place Relic");
            }
            if (ConfirmButtonCap != null)
            {
                GameXR.Button3D(ConfirmButtonCap, ActivateAltar, radius: 0.09f, depth: 0.02f);
            }
            statusPanel = GameXR.Panel(transform, 0.55f, 0.2f);
            statusPanel.transform.localPosition = new Vector3(0f, 1.35f, 0f);
            RefreshReadout("Place Relic");
#endif
        }

        void Update()
        {
            // Flat-screen parity: E / Gamepad West triggers the same altar interaction when outside VR
#if CCGD_VR
            if (GameXR.Active)
            {
                if (statusPanel != null && GameXR.Head != null)
                {
                    Vector3 look = statusPanel.transform.position - GameXR.Head.position;
                    look.y = 0f;
                    if (look.sqrMagnitude > 1e-4f)
                        statusPanel.transform.rotation = Quaternion.LookRotation(look);
                }
                return;
            }
#endif
            if (GameInput.InteractPressed) ActivateAltar();
        }

        public void ActivateAltar()
        {
            ActivatedCount++;
            GameAudio.Play("confirm", transform.position);
            RefreshReadout($"Charged x{ActivatedCount}");
        }

        void RefreshReadout(string message)
        {
#if CCGD_VR
            if (statusPanel != null) statusPanel.Text(message);
#endif
        }
    }
}
```

## Performance & Comfort Traps

- **Wrap all `GameXR` / `XrGrabbable` / `XrSocket` references in `#if CCGD_VR`**: Non-VR builds omit `CCGD_VR` from `Assets/csc.rsp` so flat games carry zero XR runtime overhead.
- **Unity 6 `Rigidbody.linearVelocity`**: Always read/write `rb.linearVelocity` (never deprecated `rb.velocity`).
- **Readable World Panels**: Keep `GameXR.Panel` text $\ge 40\text{ px}$ at `1.0 – 1.8 m` viewing distance (`900 px/m` density).

## Verification Checklist

1. Drive the hands in tests the way a player does: `GameXR.Sim.Squeeze("right", 1f)` / `Sim.Trigger` (analog), `Sim.Touch("right", "trigger", "stick")`, and `Sim.TrackHand("right", "pinch")` for a tracked hand; assert `hand.Pinching` / `hand.Grabbing` and the grabbable's `HeldWith` grip pose.
2. Write a `GameXR.Sim` PlayMode test (`GameXR.Sim.Enter()`, `GameXR.Sim.Reach("right", relic.transform.position)`, `GameXR.Sim.Press("right-squeeze")`, move to `PedestalAnchor`, `GameXR.Sim.Release("right-squeeze")`) asserting socket snap + haptic `hand.Pulses > 0`.
3. Run `audit_game` to verify `README.md` has a `VR` controls column, interactables sit in `[0.35 m, 1.85 m]` floor-relative height, and camera shake is gated off when `GameXR.Active`.

## Official references

- Valve Half-Life: Alyx Russell Gloves & Distance Pull (GDC 2020)
- Meta Quest Spatial Comfort & Ergonomics Guidelines
- Oculus Hand Velocity Windowing Notes
