Skip to content

Support the headsets in the headset plan - #6

Merged
aaf2tbz merged 5 commits into
mainfrom
docs/headset-plan
Nov 17, 2026
Merged

aaf2tbz merged 5 commits into
mainfrom
docs/headset-plan

Conversation

@aaf2tbz

@aaf2tbz aaf2tbz commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Adds the headset plan (docs/HEADSETS.md) and its implementation, phases A to J.

Headsets

  • Quest 1, 2, 3, 3S and Pro (ALVR): the model from the client's name, battery, play area, wired mode through adb, hand tracking (XR_EXT_hand_tracking and SteamVR skeletons), and ALVR's foveated encoding.
  • Steam Frame (ALVR): its model and controller profile, plus patches/alvr/0003. The patch makes ALVR's client run under Valve's runtime, which lacks XR_KHR_convert_timespec_time, and makes it report the headset as "Steam Frame". scripts/build-alvr-client.sh builds the client as an APK.
  • Valve Index, HTC Vive, Vive Pro and Pro 2 (--driver lighthouse): the headset's firmware configuration, lens models, IMU, Watchman controllers with haptics, base-station positions through libsurvive (scripts/build-libsurvive.sh), and camera passthrough.
  • Rift S (--driver rift): power-on, IMU, the portrait panel, Touch controllers, and the head's position from its cameras. The position comes from Basalt (scripts/build-basalt.sh), loaded at run time through Monado's VIT interface.
  • PlayStation VR2 (--driver psvr2), through Sony's PC adapter: the headset over IOUSBHost, with its IMU, proximity sensor, IPD dial, lens calibration, and the head's position from the headset's own tracking. Monado's PS VR2 lens model runs in the shader. Sense controllers over Bluetooth provide buttons, stick, trigger, touches, battery, rotation and vibration, and games see them as Touch.

Docs

  • The README is minimal: status, a table of headsets, building, and links.
  • Each headset has a setup guide in docs/headsets/: what you need, setting up and playing, what is checked in code and by which test, what is built but untested, and what is unknown until it meets the headset.

Checks

  • scripts/test-all.sh: all 40 suites pass, including the new ones:
    • headset_protocol_check: report, configuration and calibration parsers, including the PS VR2 and Sense controllers;
    • the panel checks for seven models;
    • native-psvr2-sense: a simulated PS VR2 as OpenXR sees it;
    • the libsurvive simulation;
    • the ALVR model mapping;
    • rift_s_tracking_check: a synthetic Rift S, rendered through its five cameras, tracked to 0.2 cm RMS over a 5 m path.
  • The Rift CV1 was rechecked on real hardware after the shared driver changed for the PS VR2.

Not tested: nothing has run on the new headsets themselves:

  • the Steam Frame APK on a Frame;
  • the Rift S cameras through macOS;
  • the PS VR2 through its PC adapter on a Mac;
  • the Lighthouse and Rift S displays through adapters.

Phases A to I: Quest 1, 2, 3 and 3S, Steam Frame, Valve Index, HTC Vive,
Vive Pro and Pro 2, and Rift S. Each phase gives the headset's specs, how
MetalVR recognizes it, the work by file, what can be tested without the
headset, and the risks; shared work is listed once, in the phase that
first needs it.
Phases A to I of the headset plan, built on the existing CV1, ALVR and
simulated-headset paths:

- Quest 1/2/3/3S/Pro over ALVR: the model from the client's name,
  battery, play area, wired mode through adb, hand tracking
  (XR_EXT_hand_tracking and SteamVR skeletons), and ALVR's foveated
  encoding.
- Steam Frame: its model and controller profile, and an ALVR client
  patch (patches/alvr/0003) that runs under Valve's runtime and names
  the headset; scripts/build-alvr-client.sh builds it as an APK.
- Valve Index, HTC Vive, Vive Pro and Pro 2 through a direct-display
  Lighthouse backend: firmware configuration, lens models, IMU,
  Watchman controllers with haptics, base-station positions through
  libsurvive (scripts/build-libsurvive.sh), and camera passthrough.
- Rift S through the direct-display driver: power-on, IMU, portrait
  panel, Touch controllers, and the head's position from its cameras
  through Basalt (scripts/build-basalt.sh), loaded at run time through
  Monado's VIT interface.

Checked by tests/headset_protocol_check, tests/rift_s_tracking_check
(a synthetic Rift S tracked to 0.2 cm RMS), the panel checks, the
libsurvive simulation, and scripts/test-all.sh (38 suites). Nothing
has run on the new headsets themselves.
A new direct-display backend for the PS VR2 through Sony's PC adapter,
ported from Monado's psvr2 and pssense drivers (BSL-1.0):

- The headset over IOUSBHost: firmware and serial, lens calibration,
  the 2 kHz IMU, proximity sensor and IPD dial, and the head's position
  and heading from the headset's own tracking (its SLAM records). The
  cameras and other streams run and are drained as Monado does.
- Monado's PS VR2 lens model, with its 1024-entry colour table, as lens
  model 3 in the driver's shader.
- Sense controllers over Bluetooth: buttons, stick, trigger, touches,
  battery, calibrated IMU rotation, and vibration. Games see Touch.
- metalvrd --driver psvr2, metalvr psvr2, and metalvr-psvr2 (the
  metalvr-rift script under another name). macOS ships no override that
  hides Sony displays, so no display step is needed.

Checked by headset_protocol_check (159 checks), --panel-check psvr2,
native-psvr2-sense, the driver waiting and stopping without a headset,
the Rift CV1 on real hardware, and scripts/test-all.sh (40 suites).
Nothing has run on a PS VR2.
The README is now what MetalVR is, its status, a table of headsets with
their guides, how to build, and where the rest is documented.

Each headset has a guide in docs/headsets/ (Rift CV1, moved there; Rift
S; the Quests; Steam Frame; Valve Index; the HTC Vives; PlayStation
VR2): what you need, setting up and playing, what is checked in code
and by which test, what is built but not covered by a test, what stays
unknown until it meets the headset, what is not supported, and what to
do when it doesn't work.

HEADSETS.md stays the research behind them, with its stale risks fixed
(the Steam Frame's client, libsurvive on macOS) and its "What is built"
table replaced by a pointer to the guides. ARCHITECTURE.md takes the
README's feature list and lists every driver; RIFT.md is introduced as
the direct-display driver's page; BUILDING.md, STEAMVR.md, CONTRIBUTING.md,
the bug template, metalvrd --help and the release packaging follow.
The home's logo was MetalSharp's. It is now the MetalVR wordmark,
cropped to its lettering (990x266) on black, which the home draws as
see-through.
@aaf2tbz
aaf2tbz merged commit c94362b into main Nov 17, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant