# Target host platform — Steam Frame

Researched 2026-06-23; **corrected 2026-09-18 against the shipped hardware and Lepton's
published source.** Answers "can the dumped APK run on Steam Frame, and do we need Android
given SteamOS is Linux?"

> **Correction (2026-09-18):** the 2026-06 research assumed the OpenXR runtime inside Lepton
> would be **Monado**. It is **SteamVR**. Lepton ships
> `vendor/etc/openxr/1/active_runtime.json` naming runtime `steamvr`
> (`VALVE_runtime_is_steamvr: true`) and pointing at a host-mounted
> `/data/steamvr/runtime/bin/androidarm64/vrclient.so`. Sections below are updated; treat any
> remaining "Monado" reference in older docs as superseded.

## Do we need the Android side? YES.
The game is an **Android binary**, not a Linux one — ARM64==ARM64 does NOT bridge:
- `libUE4.so` links **bionic** libc (ABI-incompatible with SteamOS glibc).
- Depends on Android system libs: liblog, libandroid (ANativeActivity,
  AAssetManager, input), libOpenSLES; boots via a Java/JNI NativeActivity.
- Reads OBB assets via Android AssetManager/storage paths.
=> Cannot run the .so bare on SteamOS. Must run inside an Android runtime.
   Only Android-free path = full native source recompile (no source -> not viable).

## The host pieces all exist (and are open)
- **Lepton** = Valve's official Android-on-Linux layer; a **Waydroid/AOSP fork
  built specifically to run Quest APKs on Steam Frame**, with sideloading. APKs
  run **native ARM64, no emulation** (the "Waydroid needs x86" caveat is about
  Waydroid on x86 PCs; Frame is ARM so it doesn't apply). Walkabout Mini Golf
  (Quest title) already cited running on it.
- **SteamVR** is the OpenXR runtime apps see inside Lepton, bind-mounted in from the host
  (not Monado — see the correction above). It advertises the `XR_FB_foveation` family,
  `XR_FB_swapchain_update_state`, `XR_META_foveation_eye_tracked` and
  `XR_EXT_eye_gaze_interaction`, and it presents Frame controllers as **emulating Oculus
  Touch** by default (falling back Frame profile -> generic -> Touch). Both facts are
  favourable: our Touch bindings and our FB-foveation path should work unchanged.
- Lepton also mounts the host's graphics stack into the container (mesa/turnip/zink, gralloc
  `minigbm_msm`) plus host Vulkan layers including a foveated-rendering injector and a
  renderpass optimizer.

## Architecture
```
Steam Frame (SteamOS / Arch Linux, ARM64)
└─ Lepton (AOSP/Waydroid container, native ARM64)
    └─ RE4 VR APK (unmodified bionic Android binary)
        ├─ libUE4.so → [SHIM libOVRPlugin] → OpenXR → SteamVR (vrclient.so) → Frame compositor
        └─ ovr_* Platform SDK → out of scope (no entitlement code ships in this repo —
           a valid entitlement is the user's responsibility; see README "Legal / scope")
```

## Why the shim IS the project
Meta ended VrApi support 2022-08-31; OpenXR is the only supported Quest API and
Valve's whole stack is OpenXR (SteamVR on Frame). So:
- OpenXR Quest games  -> Lepton+SteamVR likely run them with little/no work.
- VrApi games (RE4 VR) -> won't: Lepton/AOSP will never ship Meta's proprietary
  libvrapi.so, so the unmodified game finds no VR runtime. The OVRPlugin->OpenXR
  shim is exactly what bridges a dead-API VrApi game to Frame's OpenXR stack.

## Status of the old unknowns (resolved 2026-09-18)

Steam Frame shipped **2026-09-14** and Lepton is open source (MIT for the tool), so the three
2026-06 unknowns are answered:

1. **Does Lepton expose an OpenXR runtime to apps inside the container?** Yes — SteamVR, via
   the bind-mounted `active_runtime.json` and `vrclient.so` described above.
2. **Can a sideloaded app reach the runtime + compositor?** Yes. Lepton documents adb
   sideloading (`lepton install_app`, or `adb install` against the container), and its own
   installer pushes an adjacent `obb/` directory into the app's data — which matters for us,
   since RE4 VR ships its assets as OBBs.
3. **Vulkan swapchain sharing across the container GPU boundary** — a non-issue by design:
   Lepton mounts the host graphics drivers into the container rather than proxying them.

### New items to check before a first boot attempt

- **Page alignment (check this first).** Our shim's ELF LOAD segments align at 4 KB and
  `repack.sh` runs `zipalign -p 4`. Valve's Unreal docs reference a 16 KB page-alignment
  requirement on this platform. If the Frame kernel uses 16 KB pages, the library will not
  load, and it would present as an unexplained launch failure. Fix is
  `-Wl,-z,max-page-size=16384` at link time plus `zipalign -P 16`.
- **The Build spoof in `packaging/steamframe_patches.sh` is confirmed necessary.** Lepton sets
  `ro.product.manufacturer=Valve` and `ro.product.model=Lepton`, so UE's Oculus-HMD gate is
  false without it and our shim is never called.
- **Swapchain usage flags.** `setup_layer` requests only COLOR_ATTACHMENT and SAMPLED. Meta
  over-provisions; a spec-following runtime does not.
- **Refresh rate.** 72 Hz is hardcoded in two places; Frame runs 72/90/120/144.
- **`UECommandLine.txt`.** Lepton's installer pushes one into `/data/steam_app`, which may be
  a route for the UE streaming CVars that the baked-commandline dead end blocked on Quest.
  Unverified, but cheap to try.
- **App SDK level.** RE4 VR is `minSdkVersion 25` / `targetSdkVersion 29`, arm64-v8a only.
  Lepton rejects APKs whose SDK level is *higher* than the container's, so a low target should
  be fine — but it is untested.