// Build, install, and launch the erhe editor APK on a Meta Quest 3 attached over adb. Enforces the headset-prompt protocol (install before asking the user to put the headset on, never launch without acknowledged readiness) and walks through the canonical script invocations.
| name | erhe-quest-launch |
| description | Build, install, and launch the erhe editor APK on a Meta Quest 3 attached over adb. Enforces the headset-prompt protocol (install before asking the user to put the headset on, never launch without acknowledged readiness) and walks through the canonical script invocations. |
Build the editor APK, install it on a connected Meta Quest 3, then launch it into immersive VR. The Quest runtime's RequiresControllersLaunchInterceptor blocks the immersive app behind a "Controllers Required" dialog if the headset is off the user's head when the launch intent fires, so the order of operations matters.
Build the APK -- no headset interaction needed:
scripts\build_android.bat quest
APK lands at android-project\app\build\outputs\apk\quest\debug\app-quest-debug.apk.
Install the APK -- still no headset interaction needed. Force-stop first so the install isn't deferred while a previous instance holds the package:
$LOCALAPPDATA/Android/Sdk/platform-tools/adb.exe shell am force-stop org.libsdl.app.quest
scripts\install_android.bat quest
Verify by reading lastUpdateTime from adb shell dumpsys package org.libsdl.app.quest; it should advance with each install.
Prompt the user to put on the headset and pick up the controllers, then wait for explicit acknowledgement. Do not skip this. Pure builds and installs (no am start) do not need the prompt; only the launch step does.
Launch only after the user acknowledges:
$LOCALAPPDATA/Android/Sdk/platform-tools/adb.exe logcat -c
$LOCALAPPDATA/Android/Sdk/platform-tools/adb.exe shell am start -n org.libsdl.app.quest/org.libsdl.app.SDLActivity
Clearing logcat first makes post-launch diagnosis cleaner.
One-shot build + install + launch via Gradle's installQuestDebug:
scripts\run_android.bat quest
Same headset-prompt rule applies before invoking it (run_android.bat ends with am start -W -a android.intent.action.MAIN -c android.intent.category.LAUNCHER -c com.oculus.intent.category.VR ... so the Horizon shell enters immersive composition).
Force a fresh on-device SPIR-V cache (e.g. after a glslang patch) by uninstalling first instead of force-stop + install:
$LOCALAPPDATA/Android/Sdk/platform-tools/adb.exe uninstall org.libsdl.app.quest
scripts\install_android.bat quest
Uninstall wipes /data/data/org.libsdl.app.quest/files/spirv_cache/ so the next launch re-compiles every shader.
Pass-through gradle properties: build_android.bat forwards extra args verbatim, but its bat-arg parser strips =. Pass bare flags like -Pvulkan_validation_skip rather than -Pvulkan_validation_skip=1. For values with =, invoke gradlew.bat directly with JAVA_HOME and ANDROID_HOME set.
The wrapper scripts probe in this order:
ANDROID_HOME env var, falling back to %LOCALAPPDATA%\Android\Sdk. Adb is <ANDROID_HOME>\platform-tools\adb.exe.JAVA_HOME env var (only needed for direct gradle calls), falling back to C:\Program Files\Android\Android Studio\jbr (Android Studio's bundled JDK 21; Gradle 8.12 + AGP do not support JDK 25).In bash on Windows, the canonical adb path is "$LOCALAPPDATA/Android/Sdk/platform-tools/adb.exe".
The editor logs under tag erhe. To pull what just happened:
$LOCALAPPDATA/Android/Sdk/platform-tools/adb.exe logcat -d -v time | grep -E "erhe|FATAL|Abort message|Creating shader module|VALIDATION ERROR|Headset_view: multiview"
When chasing a hang, watch for Headset_view: multiview render path enabled (init reached the headset path) and the absence/presence of frame-period am start-following logs to decide whether the editor is actually rendering.
Triage erhe editor aborts on Quest where vkCreateShaderModule fails with spirv-val (VUID-VkShaderModuleCreateInfo-pCode-08737), or any Shader_stages compile/link error. Identifies which shader / stage failed by reading the immediately-preceding "Creating shader module" log line, then maps known VUIDs to known fixes. Use when the editor aborts on Quest at startup with a SPIR-V or shader-link validation message.
Enable VK_LAYER_KHRONOS_validation on the erhe Quest APK so silent GPU hangs become loud aborts. Covers the bundle (default on), the runtime config knob, the on-device SPIR-V cache wipe via uninstall, and the device-error abort hook in editor.cpp. Use when a Quest build runs but renders nothing in VR, hangs at the Horizon launch panel, or otherwise misbehaves silently.
Collapse many WIP / fix-to-fix commits on a feature branch into a small set of topic-focused commits. Reads the original commit messages first so intent is preserved, soft-resets to origin/main so intermediate / overwritten changes drop out automatically, then re-commits the accumulated diff one logical topic at a time. Use before opening a PR or merging when `git log origin/main..HEAD` looks noisy.