Add a Steam Frame flavour of the Android app with Frame controller bindings

The Steam Frame runs Android apps through Lepton with SteamVR's OpenXR
runtime. A third headset flavour, steamFrame, targets it:

- -mcpu=cortex-x4+nosve for the Snapdragon 8 Gen 3 (its firmware does
  not expose SVE, which clang otherwise auto-vectorises with), from one
  flavour-to-CPU map that the kit export now reads instead of guessing
  from the variant name.
- MKW_ANDROID_HEADSET=steam_frame defines MKW_HEADSET_STEAM_FRAME for
  the runtime's own targets, for Frame-specific defaults.
- A manifest without the Horizon OS entries, and FrameEntryActivity as
  the single real MAIN/LAUNCHER activity with the Khronos and Oculus VR
  categories, which Lepton needs to start an app in VR. It opens the
  setup panel and, when the selected game can start, the game on top.
- XR_VALVE_frame_controller_interaction: the Frame controller profile
  with its left D-pad (new dpad_* actions, the Wii Remote's D-pad or the
  gamepad's), View as menu and the left shoulder as the panel button.
  Also requested on Windows for SteamVR streaming to a Frame.
- Build-Quest.ps1, Build-QuestGame.ps1 and Run-Quest.ps1 take
  -Headset frame.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019HBRGKTE1GnN2ah8gcZKr3

android/Build-Quest.ps1

@@ -1,7 +1,10 @@
 # Builds the standalone Meta Quest APK on a Windows host.
 #
 #   powershell -ExecutionPolicy Bypass -File android/Build-Quest.ps1 [-Generated <dir>]
-#                                [-Headset modern|quest1] [-Configuration debug|release] [-Install]
+#                                [-Headset modern|quest1|frame] [-Configuration debug|release] [-Install]
+#
+# -Headset frame builds the Steam Frame flavour (steamFrame), which runs under Lepton, SteamOS's
+# Android layer, with SteamVR's OpenXR runtime (docs/quest-port.md, "Steam Frame").
 #
 # One app offers both games: the APK carries a kit for the base game, and for Retro Rewind too
 # when -Generated holds a translation that includes the mod.
@@ -25,7 +28,7 @@ param(
     [string]$Generated = '',
     [string]$Dependencies = '',
     [string]$CMakeDir = '',
-    [ValidateSet('modern', 'quest1')] [string]$Headset = 'modern',
+    [ValidateSet('modern', 'quest1', 'frame')] [string]$Headset = 'modern',
     [ValidateSet('debug', 'release')] [string]$Configuration = 'debug',
     [switch]$Install,
     [switch]$StockDawn
@@ -80,8 +83,13 @@ if (-not $Dependencies) {
 }
 
 $variant = (Get-Culture).TextInfo.ToTitleCase($Configuration)
-$flavour = if ($Headset -eq 'quest1') { 'Quest1' } else { 'ModernQuest' }
-$expectedCpu = if ($Headset -eq 'quest1') { 'kryo' } else { 'cortex-a77' }
+# The Gradle flavour and the -mcpu target its kit must record (headsetCpus in app/build.gradle.kts).
+$flavourDir, $expectedCpu = switch ($Headset) {
+    'quest1' { 'quest1', 'kryo' }
+    'frame' { 'steamFrame', 'cortex-x4+nosve' }
+    default { 'modernQuest', 'cortex-a77' }
+}
+$flavour = $flavourDir.Substring(0, 1).ToUpperInvariant() + $flavourDir.Substring(1)
 $task = "app:assemble$flavour$variant"
 $gradleArgs = @(
     '--project-dir', $root,
@@ -98,7 +106,6 @@ Write-Host "gradlew $($gradleArgs -join ' ')"
 & (Join-Path $root 'gradlew.bat') @gradleArgs
 if ($LASTEXITCODE -ne 0) { throw "Gradle failed ($LASTEXITCODE)" }
 
-$flavourDir = if ($Headset -eq 'quest1') { 'quest1' } else { 'modernQuest' }
 $apkDir = Join-Path $root "app\build\outputs\apk\$flavourDir\$Configuration"
 $apk = Get-ChildItem -Path $apkDir -Filter '*.apk' | Select-Object -First 1
 if (-not $apk) { throw "No APK under $apkDir" }
@@ -128,6 +135,8 @@ if ($Install) {
     if ($LASTEXITCODE -ne 0) { throw "adb install failed ($LASTEXITCODE)" }
     if ($Headset -eq 'quest1') {
         Write-Host 'Installed. Use WiiCompiled Settings for setup, then launch WiiCompiled VR directly from the library.'
+    } elseif ($Headset -eq 'frame') {
+        Write-Host 'Installed. Build a game on this PC with android/Build-QuestGame.ps1 -Headset frame -Install, then start WiiCompiled VR from the Steam library.'
     } else {
         Write-Host 'Installed. Build a game with Build on this Quest in the launcher, or on this PC with android/Build-QuestGame.ps1 -Install.'
     }

android/Build-QuestGame.ps1

@@ -6,7 +6,7 @@
 # SDK's NDK and ninja:
 #
 #   powershell -ExecutionPolicy Bypass -File android/Build-QuestGame.ps1 [-Generated <dir>] [-Kit <dir>]
-#                                    [-Headset modern|quest1] [-Configuration debug|release]
+#                                    [-Headset modern|quest1|frame] [-Configuration debug|release]
 #                                    [-Data <extracted disc dir>] [-Output <file.wcgame>] [-Install]
 #
 # WiiCompiled Setup's --build-quest runs the copy staged in an installation's BuildWorkspace\android,
@@ -33,7 +33,7 @@ param(
     [string]$Sysroot = '',
     [string]$Ninja = '',
     [string]$BuiltBy = 'android/Build-QuestGame.ps1',
-    [ValidateSet('modern', 'quest1')] [string]$Headset = 'modern',
+    [ValidateSet('modern', 'quest1', 'frame')] [string]$Headset = 'modern',
     [ValidateSet('debug', 'release')] [string]$Configuration = 'debug',
     [ValidateSet('base', 'retro_rewind')] [string]$Product = 'base',
     [string]$Mod = '',
@@ -47,7 +47,7 @@ $root = $PSScriptRoot
 $workspace = (Resolve-Path (Join-Path $root '..')).Path
 if (-not $Generated) { $Generated = Join-Path $workspace '.scratch\vr-build-workspace\BuildWorkspace\generated' }
 if (-not $Manifest) { $Manifest = Join-Path $workspace 'projects\mkwii\recomp.yml' }
-$variant = if ($Headset -eq 'quest1') { 'quest1' } else { 'modernQuest' }
+$variant = switch ($Headset) { 'quest1' { 'quest1' } 'frame' { 'steamFrame' } default { 'modernQuest' } }
 $variant += (Get-Culture).TextInfo.ToTitleCase($Configuration)
 if (-not $BuildDir) { $BuildDir = Join-Path $root "app\build\questGame\$variant\$Product" }
 if (-not $Kit) {

android/Run-Quest.ps1

@@ -3,7 +3,7 @@
 # diagnostics for one session.
 #
 #   powershell -ExecutionPolicy Bypass -File android/Run-Quest.ps1 [-Apk <path>] [-Data <extracted disc dir>]
-#                         [-Headset modern|quest1] [-Configuration debug|release]
+#                         [-Headset modern|quest1|frame] [-Configuration debug|release]
 #                         [-Seconds 60] [-NoLaunch] [-SkipInstall]
 #
 # -Data names the extracted disc partition (the directory holding sys/, files/,
@@ -25,7 +25,7 @@
 param(
     [string]$Apk = '',
     [string]$Data = '',
-    [ValidateSet('modern', 'quest1')] [string]$Headset = 'modern',
+    [ValidateSet('modern', 'quest1', 'frame')] [string]$Headset = 'modern',
     [ValidateSet('debug', 'release')] [string]$Configuration = 'debug',
     [int]$Seconds = 60,
     [switch]$NoLaunch,
@@ -52,7 +52,7 @@ if (-not $devices) { throw 'No device in "device" state; check the Quest is conn
 
 if (-not $SkipInstall) {
     if (-not $Apk) {
-        $flavour = if ($Headset -eq 'quest1') { 'quest1' } else { 'modernQuest' }
+        $flavour = switch ($Headset) { 'quest1' { 'quest1' } 'frame' { 'steamFrame' } default { 'modernQuest' } }
         $apkDir = Join-Path $root "app\build\outputs\apk\$flavour\$Configuration"
         $Apk = Get-ChildItem -Path $apkDir -Filter '*.apk' -ErrorAction SilentlyContinue |
             Select-Object -First 1 | ForEach-Object FullName

android/app/build.gradle.kts

@@ -53,6 +53,19 @@ val hasRetroRewindShards: Boolean = run {
     shards.isFile && shards.readText().contains("set(MKW_HAVE_RETRO_REWIND_SHARDS ON)")
 }
 
+// Each headset flavour's AArch64 -mcpu target. The game kit records it, and the kit export, the APK
+// audit (Build-Quest.ps1), the PC build (QuestGameKit.psm1), the on-headset build and the package
+// import all refuse a game built for another one.
+val headsetCpus = mapOf(
+    // Snapdragon XR2 and newer. Keep this as the default build target.
+    "modernQuest" to "cortex-a77",
+    // Snapdragon 835. cortex-a77 binaries terminate with SIGILL on Quest 1.
+    "quest1" to "kryo",
+    // Snapdragon 8 Gen 3 (Cortex-X4, A720 and A520, all ARMv9.2). Its firmware does not expose SVE,
+    // which clang would otherwise auto-vectorise with for a cortex-x4.
+    "steamFrame" to "cortex-x4+nosve",
+)
+
 // android/nod-jni: nod, the disc image library the PC installer runs as nodtool,
 // cross-compiled with cargo for the launcher's "Select disc image". Needs a Rust
 // toolchain with the aarch64-linux-android target (see docs/quest-port.md).
@@ -152,11 +165,11 @@ android {
             dimension = "headset"
             manifestPlaceholders["mkwQuestSupportedDevices"] = "quest2|quest3|quest3s|questpro"
             buildConfigField("boolean", "QUEST1_DIRECT_LAUNCH", "false")
-            buildConfigField("String", "ANDROID_CPU", "\"cortex-a77\"")
+            buildConfigField("boolean", "STEAM_FRAME", "false")
+            buildConfigField("String", "ANDROID_CPU", "\"${headsetCpus.getValue("modernQuest")}\"")
             externalNativeBuild {
                 cmake {
-                    // Snapdragon XR2 and newer. Keep this as the default build target.
-                    arguments += "-DMKW_ANDROID_CPU=cortex-a77"
+                    arguments += "-DMKW_ANDROID_CPU=${headsetCpus.getValue("modernQuest")}"
                 }
             }
         }
@@ -164,11 +177,30 @@ android {
             dimension = "headset"
             manifestPlaceholders["mkwQuestSupportedDevices"] = "quest|quest2"
             buildConfigField("boolean", "QUEST1_DIRECT_LAUNCH", "true")
-            buildConfigField("String", "ANDROID_CPU", "\"kryo\"")
+            buildConfigField("boolean", "STEAM_FRAME", "false")
+            buildConfigField("String", "ANDROID_CPU", "\"${headsetCpus.getValue("quest1")}\"")
             externalNativeBuild {
                 cmake {
-                    // Snapdragon 835. cortex-a77 binaries terminate with SIGILL on Quest 1.
-                    arguments += "-DMKW_ANDROID_CPU=kryo"
+                    arguments += "-DMKW_ANDROID_CPU=${headsetCpus.getValue("quest1")}"
+                }
+            }
+        }
+        // Valve's Steam Frame, through Lepton (SteamOS's Android layer) and SteamVR's Android
+        // OpenXR runtime. Its manifest (src/steamFrame) drops the Horizon OS entries, and
+        // MKW_ANDROID_HEADSET gives the runtime the Frame's defaults (runtime_config.h).
+        create("steamFrame") {
+            dimension = "headset"
+            // Horizon OS only; src/steamFrame/AndroidManifest.xml removes the entry.
+            manifestPlaceholders["mkwQuestSupportedDevices"] = ""
+            buildConfigField("boolean", "QUEST1_DIRECT_LAUNCH", "false")
+            buildConfigField("boolean", "STEAM_FRAME", "true")
+            buildConfigField("String", "ANDROID_CPU", "\"${headsetCpus.getValue("steamFrame")}\"")
+            externalNativeBuild {
+                cmake {
+                    arguments += listOf(
+                        "-DMKW_ANDROID_CPU=${headsetCpus.getValue("steamFrame")}",
+                        "-DMKW_ANDROID_HEADSET=steam_frame",
+                    )
                 }
             }
         }
@@ -324,7 +356,7 @@ androidComponents {
             dependsOn("merge${capitalized}NativeLibs")
             appDir.set(layout.projectDirectory)
             script.set(rootProject.layout.projectDirectory.file("Export-QuestGameKit.ps1"))
-            androidCpu.set(if (variant.name.startsWith("quest1", ignoreCase = true)) "kryo" else "cortex-a77")
+            androidCpu.set(headsetCpus.getValue(checkNotNull(variant.flavorName) { "${variant.name} has no headset flavour" }))
             outputDir.set(layout.buildDirectory.dir("generated/assets/questGameKit/${variant.name}"))
             llvmStrip.set(sdkComponents.ndkDirectory.map {
                 it.file("toolchains/llvm/prebuilt/$host/bin/llvm-strip" + if (host.startsWith("windows")) ".exe" else "")

android/app/src/steamFrame/AndroidManifest.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <!-- Horizon OS entries the Steam Frame has no use for: SteamVR's runtime needs no permission for
+         XR_EXT_hand_tracking, offers no XR_FB_passthrough, and reads none of the com.oculus metadata. -->
+    <uses-permission android:name="horizonos.permission.HAND_TRACKING" tools:node="remove" />
+    <uses-permission android:name="com.oculus.permission.HAND_TRACKING" tools:node="remove" />
+    <uses-feature android:name="com.oculus.feature.PASSTHROUGH" tools:node="remove" />
+    <uses-feature android:name="oculus.software.handtracking" tools:node="remove" />
+
+    <application>
+        <meta-data android:name="com.oculus.supportedDevices" tools:node="remove" />
+        <meta-data android:name="com.oculus.vr.focusaware" tools:node="remove" />
+        <meta-data android:name="com.oculus.trade_cpu_for_gpu_amount" tools:node="remove" />
+
+        <!-- Lepton, SteamOS's Android layer, starts the one real activity that is MAIN and
+             LAUNCHER (it ignores activity-aliases) and runs the app in VR when that activity
+             carries a VR category. This one only routes: to the game when it is ready, with the
+             setup panel underneath (FrameEntryActivity.kt). -->
+        <activity
+            android:name=".FrameEntryActivity"
+            android:excludeFromRecents="true"
+            android:exported="true"
+            android:noHistory="true"
+            android:theme="@android:style/Theme.NoDisplay">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+                <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
+                <category android:name="com.oculus.intent.category.VR" />
+            </intent-filter>
+        </activity>
+
+        <activity android:name=".QuestActivity">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
+                <category android:name="com.oculus.intent.category.VR" />
+                <category android:name="android.intent.category.DEFAULT" />
+            </intent-filter>
+        </activity>
+    </application>
+</manifest>

android/app/src/steamFrame/java/org/wiicompiled/quest/FrameEntryActivity.kt

@@ -0,0 +1,52 @@
+package org.wiicompiled.quest
+
+import android.app.Activity
+import android.content.Intent
+import android.os.Bundle
+import android.util.Log
+import org.wiicompiled.quest.launcher.LauncherActivity
+import org.wiicompiled.quest.launcher.ModLibrary
+
+/**
+ * The Steam Frame's library entry. Lepton starts the one real activity that is both MAIN and
+ * LAUNCHER, in VR when it carries a VR category, and ignores activity-aliases, so neither of the
+ * Quest flavours' entries works there. This one shows nothing: the setup panel (LauncherActivity)
+ * always opens, and when the selected game can start as it is, the game opens on top of it, so the
+ * headset goes straight into VR and quitting the game comes back to the panel.
+ */
+class FrameEntryActivity : Activity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val launcher = Intent(this, LauncherActivity::class.java)
+        if (readyToPlay()) {
+            Log.i(TAG, "Starting the game over the setup panel")
+            startActivities(arrayOf(launcher, Intent(this, QuestActivity::class.java)))
+        } else {
+            Log.i(TAG, "The game is not ready to start; opening the setup panel")
+            startActivity(launcher)
+        }
+        finish()
+    }
+
+    /**
+     * What Home's Play needs (LauncherActivity), short of the steps only the panel performs: the
+     * game files and the selected game built for this app, Retro Rewind's pack, and no enabled mods
+     * to copy into the pack's Patches folder first.
+     */
+    private fun readyToPlay(): Boolean = runCatching {
+        val profile = GameProfile.selected(this)
+        GameStorage.discStatus(this) == GameStorage.DiscStatus.Ready &&
+            GameLibrary.status(this, profile) == GameLibrary.Status.Ready &&
+            GameStorage.modContentReady(this, profile) &&
+            (!profile.modPack || ModLibrary.load(GameStorage.modsDirectory(this)).none { it.enabled })
+    }.getOrElse {
+        Log.w(TAG, "Could not check the installed game", it)
+        false
+    }
+
+    private companion object {
+        // The launcher's tag, so the usual `adb logcat -s WiiCompiledLauncher` shows the routing.
+        const val TAG = "WiiCompiledLauncher"
+    }
+}