/hz-unity-device-readiness

name: hz-unity-device-readiness
license: Apache-2.0
description: "Audits a Unity project for Meta VR Glasses readiness across input and field of view — finds controller-dependent interactions such as OVRInput usage, recommends hand-tracking and ISDK controller-to-hands migrations, produces a prioritized migration plan, and detects head-locked UI that a narrower FoV would clip."

Device Readiness

Context

This skill prepares a Unity project for Meta VR Glasses device requirements across two dimensions: **input** (hand tracking as the primary input, not a fallback) and **field of view** (a device with a narrower FoV than current Quest headsets). The input workflow is immediately below; the field-of-view workflow is its own section further down.

The target device treats hand tracking as the primary input method, not a fallback. Most existing Quest projects were built controller-first, so the work isn't just "replace button presses with gestures" — it's rethinking interaction design so hands feel natural instead of like a worse controller. A systematic scan matters: find every controller dependency, understand the gameplay intent behind it, and map it to the right ISDK pattern.

When a Meta VR Glasses or Meta Quest device is connected, ground the audit in real device data first — `metavr device list` shows what's attached, and `metavr device info <id>` reports the device's input and display capabilities the audit should target.

Analysis Workflow

Step 1: Scan the Project

Build a complete picture of how the project handles input today. Controller dependencies hide in surprising places — not just obvious `OVRInput.Get()` calls, but also XR Interaction Toolkit components, Unity's legacy Input system, and custom grab systems. Cast a wide net:

# Find controller input usage
grep -r "OVRInput\.\(Get\|GetDown\|GetUp\)" --include="*.cs" .
grep -r "OVRInput\.Button\|OVRInput\.Axis" --include="*.cs" .

# Find XR Interaction Toolkit usage
grep -r "XRGrabInteractable\|XRRayInteractor\|XRDirectInteractor" --include="*.cs" .

# Find legacy Input system usage
grep -r "Input\.GetButton\|Input\.GetAxis\|Input\.GetKey" --include="*.cs" .

# Find interaction patterns
grep -r "Grabbable\|IGrabbable\|OnGrab\|OnRelease" --include="*.cs" .
grep -r "Raycast\|RaycastHit\|Physics\.Raycast" --include="*.cs" .

Step 2: Categorize Findings

For each finding, categorize it:

| Category | What to Look For | Impact | |----------|------------------|--------| | **Controller Input** | `OVRInput.Get()`, button/axis references | Must replace with hand gestures or ISDK components | | **Grab Systems** | Trigger-based grab, distance grab | Convert to `HandGrabInteractable` with pinch detection | | **UI Interaction** | Ray-based UI, pointer clicks | Convert to poke interactions (`PokeInteractable`) | | **Movement** | Thumbstick locomotion, snap turn | Redesign for hand-based or gaze-based navigation | | **Object Manipulation** | Thumbstick rotation, button-based scaling | Use direct hand rotation/scaling with two-hand support |

Step 3: Suggest Adaptations

For each controller-dependent system, suggest a specific ISDK-based replacement. Reference the hand-tracking patterns in `references/hand-tracking-patterns.md` for implementation details.

Step 4: Prioritize

Rank suggestions by impact and effort:

• **High Priority** — core gameplay interactions that use controller APIs and must be replaced (e.g. OVRInput-based grab, trigger-based shooting).
• **Medium Priority** — secondary interactions on controller APIs (e.g. thumbstick scrolling, ray-based UI navigation).
• **Low Priority** — enhancements for code that already uses hand tracking but could be improved (hover feedback, audio cues, two-hand support). Nice-to-haves, not required to be hand-ready.

**Important.** If the project already uses ISDK hand tracking (`HandGrabInteractable`, `PokeInteractable`, etc.) and has no controller-dependent code, report that it is already hand-ready. Surface enhancements only as Low-priority items — don't treat them as required changes. A project that already works with hands should not receive a long list of improvement suggestions.

Output Format

Provide your analysis as a structured report:

1. **Project Summary** — what type of project this is and its core mechanics. 2. **Readiness Score** — rough percentage of interactions that already work with hands. 3. **Required Changes** — prioritized list with:

• what was found (specific files / classes),
• what needs to change,
• which ISDK pattern to use (reference `hand-tracking-patterns.md`),
• estimated complexity (Low / Medium / High).

4. **Quick Wins** — changes that are easy and high-impact. 5. **Migration Risks** — potential issues to watch for.

Key References

For detailed implementation patterns, read:

• `references/hand-tracking-patterns.md` — 7 ISDK interaction patterns with component references.
• `references/migration-guide.md` — step-by-step controller-to-hands migration checklist.

Important Notes

• Always maintain controller support as a fallback during migration.
• Consider accessibility — some users may prefer or need controller input.
• Performance matters — hand tracking adds CPU overhead; suggest efficient implementations.
• Test with both left and right hands; don't assume right-hand dominance.
• Hand tracking works best with interactions within arm's reach.

Field-of-View Readiness (Head-Locked UI)

Run this when preparing the project for a device with a **narrower field of view** than the developer's current target. It finds **head-locked** (HUD) UI that fits a wider FoV but would be clipped at the edges of the narrower device — reticles, health/ammo counters, minimaps, tutorial pins, vignette/letterbox overlays — and reports each with a migration fix. This is a distinct pass from the input workflow above.

What "FoV bleed" means

In VR nothing is permanently off-screen — the user can turn their he