| name | vr-device-loop |
| description | Build, install, launch, live-reload, inspect, capture, troubleshoot, and benchmark Functor on an adb-attached Meta Quest. Use for Oculus/OpenXR runtime changes, `functor run vr`, headset rendering verification, stereo captures, device performance measurements, or recovery when the APK remains at Meta Home, the XR session dozes, or adb forwarding disappears. |
VR device loop
Use the Quest as the acceptance environment while keeping Functor's desktop and
VR debug APIs isomorphic. Read runtime/functor-runtime-oculus/README.md and
docs/vr.md before changing the pipeline.
Preserve the contract
- Keep the Functor Lang program and
Frame contract target-independent. Put
headset pose, stereo views, controllers, and compositor behavior in the shell.
- Keep the canonical debug routes and wire types in
functor-runtime-common; desktop reports main, Quest reports left and
right through the same views field.
- Treat source and assets as separate coordinated operations.
/load-project//reload-project transfer .fun/.funi; changed
texture/model/audio bytes use /reload-asset, and /sync-assets finalizes
the current manifest and removes deleted uploads. functor run vr
orchestrates both streams.
- Use release APKs for performance claims. Verify Android does not report the
installed package as
DEBUGGABLE.
Build and install
Resolve the one attached device first and pass -s when more than one exists:
adb devices -l
npm run build:oculus:apk
adb -s SERIAL install -r target-android/debug/apk/functor_runtime_oculus.apk
Use npm run build:oculus for a cross-compile check without packaging. For a
benchmark, build cargo apk --release with a locally configured signing key,
install target-android/release/apk/functor_runtime_oculus.apk, and never commit
keystore paths or passwords.
After any runtime Rust change, rebuild and reinstall; functor run vr only
pushes game source.
Establish a rendering session
ADB reconnects clear forwarding rules. Recreate the forward before every
verification phase:
adb -s SERIAL forward tcp:8123 tcp:8123
adb -s SERIAL shell am broadcast -a com.oculus.vrpowermanager.prox_close
adb -s SERIAL shell am start -S -n dev.functor.runner/android.app.NativeActivity
adb -s SERIAL logcat -s functor
Expect READY -> SYNCHRONIZED -> VISIBLE -> FOCUSED. am start and GET /
becoming ready do not prove XR is rendering. Poll /state twice until frame
advances. If Meta Home remains visible, send Back, repeat prox_close, and
restart with -S. Check that NativeActivity is top-resumed with dumpsys activity activities.
Avoid concurrent broad adb logcat -d consumers: a device/daemon reconnect can
drop both the session and the forward.
Push and inspect
Prefer the integrated loop:
./target/debug/functor -d examples/primitives run vr
It launches, forwards port 8123, pushes the whole project, watches .fun/.funi
and asset files, and streams logs. For individual operations:
adb -s SERIAL forward tcp:8123 tcp:8123
curl --fail-with-body http://127.0.0.1:8123/state | jq
curl --fail-with-body http://127.0.0.1:8123/scene | jq
curl --fail-with-body http://127.0.0.1:8123/trace | jq
Use the TypeScript SDK for scripted /input, /time, reload, rewind, and
multi-client assertions. Validate clock behavior by observing a stable frame
after set, exactly one increment after advance, and progression after
resume.
For controller work, inspect /state.input.xr only after two advancing frame
samples. Require a near-identity rig-local head pose after centering; wake each
controller and verify active, independently valid grip/aim poses, analog
range/motion, and button transitions. Never accept a retained pose after a
controller becomes inactive or tracking validity is lost.
Capture both raw eyes
POST /capture reads the two rendered swapchain framebuffers before compositor
warping and returns a left-then-right 3360x1760 PNG on Quest 3. A dozing session
honestly returns HTTP 503. Retry it and make curl fail on HTTP errors so text is
never mistaken for a PNG:
curl --fail --show-error --retry 30 --retry-delay 1 \
--retry-connrefused --retry-all-errors -X POST \
http://127.0.0.1:8123/capture -o /tmp/quest-stereo.png
file /tmp/quest-stereo.png
Inspect the PNG. Require two complete eye panels, expected horizontal disparity,
no systematic vertical disparity, correct framing/depth, and no fallback assets
before treating it as visual evidence. An adb compositor screenshot is useful
for presentation, but the runtime capture is the renderer diagnostic.
Benchmark on the headset
Push the exact workload first; the benchmark never installs or pushes. Then:
npm run bench:quest -- --label primitives --warmup 10 --seconds 30
Record device/model, view resolution, FPS mean/p5/min, stale/torn frames, App and
Timewarp time, CPU/GPU load, and memory. Run a representative scene and a stress
scene. State explicitly when missing asset sync means a source-heavy workload
is representative of CPU/geometry cost but not final texture behavior.
Also run the host frame_bench base-vs-change when the patch touches a per-frame
path, following CLAUDE.md.
Finish cleanly
Restore proximity automation when unattended testing is complete:
adb -s SERIAL shell am broadcast \
-a com.oculus.vrpowermanager.automation_disable
For visual PRs, use the pr-visuals skill and include Quest media when the claim
depends on headset behavior. Report the exact APK type, device, pushed workload,
capture dimensions, and benchmark interval.
