Add OpenXR bring-up: render the game as a floating quad in an immersive Quest session

- New android/app/src/main/cpp/xr_session.c (+.h): owns the OpenXR
  instance/session/local-space/swapchain and the per-frame
  xrWaitFrame/xrBeginFrame/xrEndFrame loop, submitting the game's
  existing flat render as a single head-tracked XrCompositionLayerQuad.
  No stereo rendering or controller input yet - that's steps B/C/D of
  the plan.
- 11-android-openxr-cmake.patch: links the OpenXR loader as a build
  dependency, staged into jniLibs the same way as gl4es/SDL2.
  build-image/Dockerfile and prepare-android-project.sh build and stage
  it.
- 12-android-openxr-present.patch: redirects OpenGL.cc's final present
  step (opengl_swap_and_restore / SDLDraw's software path) into the XR
  swapchain FBO instead of the window, on Android only. Two real gl4es
  bugs had to be worked around to get pixels on screen at all:
    - gl4es's own glBindFramebuffer errors on an FBO id it didn't create
      itself, even though the real driver-level bind succeeds - fixed by
      creating the swapchain FBO container via gl4es's own
      glGenFramebuffers/glBindFramebuffer, and only using the real
      (dlsym'd) driver call for attaching OpenXR's foreign swapchain
      texture, which gl4es's own attach can't handle.
    - gl4es's glBegin/glVertexAttrib/glVertex3f immediate-mode emulation
      only captures a fresh per-vertex value for attribute 0 (position,
      driven directly by glVertex3f) - custom attributes like this
      shader's texcoords/light are GLES2's *constant*-attribute API and
      applied once for the whole draw, not per vertex, silently
      collapsing the UI-overlay quad to a single sampled texel. Fixed by
      switching that one draw call to real vertex arrays
      (glVertexAttribPointer/glDrawArrays).
  Also flips the V texcoord to match SDL's top-down row order against
  GL's texture convention, and reuses a persistent texture object
  instead of a fresh gen/upload/delete every frame.
- AndroidManifest.xml: declares the immersive-HMD intent category and
  focus-aware metadata, drops the 2D-panel layout hint.
- README: documents the new OpenXR immersive mode.

.gitea/workflows/build.yml

@@ -55,8 +55,8 @@ jobs:
         # instance's artifact storage doesn't support (GHESNotSupportedError) - v3 works.
         uses: actions/upload-artifact@v3
         with:
-          name: questshock
-          path: dist/questshock-*-linux-*.tar.gz
+          name: shockolate
+          path: dist/shockolate-*-linux-*.tar.gz
 
       - name: Build Quest APK
         # QUESTSHOCK_BUILD_IMAGE is already set (see Preflight above), so
@@ -71,7 +71,7 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: questshock-quest-apk
-          path: dist/questshock-debug.apk
+          path: dist/questshock-*-android-*.apk
 
       - name: Publish to dl.ladkau.de
         # Uploads the tarball and APK over SFTP instead of using
@@ -80,7 +80,8 @@ jobs:
         if: gitea.event_name == 'push'
         run: |
           set -euo pipefail
-          TARBALL="$(ls dist/questshock-*-linux-*.tar.gz)"
+          TARBALL="$(ls dist/shockolate-*-linux-*.tar.gz)"
+          APK="$(ls dist/questshock-*-android-*.apk)"
           mkdir -p ~/.ssh
           echo "${{ secrets.DL_SFTP_KEY }}" > ~/.ssh/dl_sftp_key
           chmod 600 ~/.ssh/dl_sftp_key
@@ -89,5 +90,5 @@ jobs:
             uploader@dl.ladkau.de <<EOF
           -mkdir files/questshock
           put $TARBALL files/questshock/$(basename "$TARBALL")
-          put dist/questshock-debug.apk files/questshock/questshock-debug.apk
+          put $APK files/questshock/$(basename "$APK")
           EOF

.gitignore

@@ -1,3 +1,6 @@
+# Android studio project files
+/android/.idea
+
 # Game assets are not included in the repo
 /res/assets/setup_system_shock_enhanced*
 /res/assets/ss_ee/

Makefile

@@ -65,7 +65,7 @@ dist: engine assets
 	@echo "== Done - run $(DIST_DIR)/run.sh to play =="
 
 # Builds a versioned, redistributable Linux release tarball at
-# dist/questshock-<version>-linux-<arch>.tar.gz - everything needed to
+# dist/shockolate-<version>-linux-<arch>.tar.gz - everything needed to
 # run except the proprietary game assets (res/GET_ASSETS.txt explains how
 # to get those instead of shipping res/data/, res/sound/). Version
 # defaults to the current git tag (vX.Y.Z, tag prefix stripped) - push a
@@ -74,20 +74,8 @@ dist: engine assets
 # placeholder version, with a warning).
 package: engine
 	@git config --global --add safe.directory "$$(pwd)" 2>/dev/null || true
-	@V="$(VERSION)"; \
-	if [ -z "$$V" ]; then \
-		if TAG=$$(git describe --tags --exact-match --match 'v[0-9]*.[0-9]*.[0-9]*' 2>/dev/null); then \
-			V=$${TAG#v}; \
-		else \
-			V="0.0.0-dev+$$(git rev-parse --short HEAD)"; \
-			echo "WARNING: HEAD is not on a vX.Y.Z tag - building placeholder version $$V (push a tag to drive a real release version)" >&2; \
-		fi; \
-	fi; \
-	case "$$V" in \
-		[0-9]*.[0-9]*.[0-9]*) ;; \
-		*) echo "PREFLIGHT FAIL: VERSION '$$V' is not a semantic version (expected X.Y.Z, optionally with a -pre+meta suffix)" >&2; exit 1;; \
-	esac; \
-	PKG_NAME="questshock-$$V-linux-$(ARCH)"; \
+	@V="$$(VERSION="$(VERSION)" ./build-image/version.sh)"; \
+	PKG_NAME="shockolate-$$V-linux-$(ARCH)"; \
 	PKG_STAGE="$(BUILD_DIR)/package/$$PKG_NAME"; \
 	echo "Packaging $$PKG_NAME"; \
 	rm -rf "$$PKG_STAGE"; \

README.md

@@ -6,6 +6,16 @@ An open source project to play the classic 1994 System Shock on a VR
 headset, built on top of [Shockolate](https://github.com/Interrupt/systemshock),
 a cross-platform port of the original game.
 
+## Design principles
+
+- **Standalone-headset-only.** The game must run entirely on the headset
+  itself - no PC required, whether tethered or streamed (not PCVR). Any
+  feature or dependency that assumes a host PC is out of scope.
+- **OpenXR-first.** Favor OpenXR-standard APIs over vendor-specific ones
+  (e.g. Meta's Oculus Mobile SDK) wherever there's a choice, so the port
+  isn't locked to Meta Quest and can work across other standalone,
+  Android-based OpenXR headsets (e.g. Pico) too.
+
 ## Layout
 
 - `engine/` - a vendored snapshot of the Shockolate engine source. Built
@@ -22,9 +32,9 @@ a cross-platform port of the original game.
 - `res/run.sh` - the launcher script, copied into `dist/` on build.
 - `Makefile` - assembles `dist/`, a self-contained runnable copy of the
   game, out of the compiled engine and the extracted assets. Also builds
-  `dist/questshock-<version>-linux-<arch>.tar.gz`, a redistributable
+  `dist/shockolate-<version>-linux-<arch>.tar.gz`, a redistributable
   package that omits the proprietary game assets (`make package`), and
-  `dist/questshock-debug.apk` for the Quest (`make apk`).
+  `dist/questshock-<version>-android-arm64.apk` for the Quest (`make apk`).
 - `android/` - the Quest app (Java `SDLActivity` glue, Gradle project).
   `android/engine-patches/` holds the one small patch needed to build
   `engine/` as an Android shared library instead of a desktop executable
@@ -64,14 +74,22 @@ game data lives inside it in a zip-format `sshock.kpf`) into
 they aren't installed locally it falls back to running the extraction in
 a throwaway Docker container instead.
 
+If you already have the game installed instead (on Windows, or via
+Wine/Proton on Linux), you don't need the installer or the script at
+all - just copy its `res/data/` and `res/sound/` folders directly into
+`res/assets/ss_ee/data/` and `res/assets/ss_ee/sound/`. That's exactly
+the same layout `extract_assets.sh` produces, so `make dist`/`make
+package`/`make apk` pick it up the same way either way.
+
 ## Packaging
 
-`make package` builds `dist/questshock-<version>-linux-<arch>.tar.gz`: the
+`make package` builds `dist/shockolate-<version>-linux-<arch>.tar.gz`: the
 compiled binary, its runtime libraries, shaders, a default MIDI
 soundfont, license information, and `res/GET_ASSETS.txt` in place of the
 actual game data (which the tarball never includes). Version comes from
 the current git tag (push a `vX.Y.Z` tag to drive a release); without one
-it builds an untagged `0.0.0-dev+<sha>` placeholder.
+it builds an untagged `0.0.0-dev+<sha>` placeholder. `make apk` (below)
+is versioned identically, via the same `build-image/version.sh`.
 
 A Gitea Actions workflow (`.gitea/workflows/build.yml`) builds this
 package on every push, using the build-image as its container (so no
@@ -80,11 +98,14 @@ resulting tarball to dl.ladkau.de.
 
 ## Playing on Meta Quest
 
-`make apk` builds `dist/questshock-debug.apk` - a plain (non-VR) Android
-app that runs as a flat, floating panel in the Quest's Home environment,
-same as any other sideloaded Android app. It's not a head-tracked 6DoF VR
-port (that's a much larger, separate undertaking); play with a Bluetooth
-mouse/keyboard connected to the headset.
+`make apk` builds `dist/questshock-<version>-android-arm64.apk` - an
+immersive OpenXR app (see `android/app/src/main/cpp/xr_session.c`): the
+game's own rendering is unchanged (still a flat, 2D render, no stereo 3D
+scene), but instead of running as a Home-hosted 2D panel it's now shown as
+a single head-tracked quad floating in front of the viewer in an otherwise
+empty space. There's no controller-driven interaction yet (that's ongoing
+work - a laser-pointer-driven menu and on-screen keyboard); for now, play
+with a Bluetooth mouse/keyboard connected to the headset same as before.
 
 1. Install the APK with [SideQuest](https://sidequestvr.com/) (or `adb
    install`).
@@ -99,6 +120,34 @@ mouse/keyboard connected to the headset.
    `/sdcard/questshock/res/`.
 4. Launch it again.
 
+### Building natively in Android Studio
+
+`make apk` always compiles the engine and links the APK inside the
+Docker build-image - convenient for CI/CLI builds, but Android Studio
+can't attach a debugger to (or get IDE code-intelligence for) a build
+that happens inside a container it isn't running.
+
+To have Android Studio compile and deploy `android/` itself instead:
+
+```sh
+./run-image.sh bash build-image/prepare-android-project.sh --host-paths
+```
+
+This stages everything `make apk` normally stages (a scratch, patched
+copy of `engine/`; the Android SDL2/SDL2_mixer/fluidsynth-lite/gl4es/openxr
+prebuilts; bundled assets) - the same as `build-apk.sh`'s own prep step -
+except it writes `android/engine.properties` with paths that resolve on
+your host filesystem, and additionally exports the prebuilt libraries
+(otherwise only present inside the image, at `/opt/prebuilt/android`) to
+`build/android-prebuilt/` so they're visible outside the container too.
+Re-run it whenever `engine/`, `android/engine-patches/`, or the
+prebuilt-library versions in `build-image/Dockerfile` change.
+
+Then open `android/` as a project in Android Studio (JDK 17, NDK
+`26.1.10909125`, and SDK Platform/Build-Tools 34 installed, matching
+`build-image/Dockerfile` and `android/app/build.gradle`) and build/run
+normally - no Docker involved for this part.
+
 ## License
 
 The original tooling in this repository (the Docker build image, build
@@ -115,6 +164,10 @@ The Quest build also bundles [GL4ES](https://github.com/ptitSeb/gl4es)
 image), which translates the engine's desktop-style OpenGL calls into
 GLES/EGL and is MIT-licensed.
 
+It also bundles the Khronos Group's own [OpenXR-SDK loader](
+https://github.com/KhronosGroup/OpenXR-SDK) (`lib/arm64-v8a/libopenxr_loader.so`,
+prebuilt unmodified into the build image), which is Apache 2.0-licensed.
+
 The vendored engine snapshot in `engine/` is
 [Shockolate](https://github.com/Interrupt/systemshock), which is licensed
 under the **GNU GPLv3** (see `engine/LICENSE`) - it is included unchanged

android/app/build.gradle

@@ -1,14 +1,73 @@
 apply plugin: 'com.android.application'
 
-// Path to the (patched, at build time - see build-apk.sh and
-// ../engine-patches/) scratch copy of engine/, written by build-apk.sh
-// since it's only known at build time, not something a checked-in
-// build.gradle can hardcode.
+// Paths written by build-image/prepare-android-project.sh (called by
+// build-apk.sh, or standalone with --host-paths to prep for a native
+// build in Android Studio - see README) since they're only known at
+// prep/build time, not something a checked-in build.gradle can hardcode.
+// engineDir is the scratch, patched copy of engine/; prebuiltDir is the
+// Android SDL2/SDL2_mixer/fluidsynth-lite/gl4es prebuilts - both point
+// into this container's own paths for build-apk.sh's own gradlew call,
+// or host-resolvable paths (plus a host-side export of prebuiltDir, since
+// /opt/prebuilt/android only exists in the image) when prepared with
+// --host-paths for Android Studio.
 def engineProps = new Properties()
 file("${projectDir}/../engine.properties").withInputStream { engineProps.load(it) }
 def engineDir = engineProps.getProperty('engineDir')
 if (engineDir == null) {
-    throw new GradleException("android/engine.properties is missing 'engineDir' - run via build-apk.sh, not gradlew directly")
+    throw new GradleException("android/engine.properties is missing 'engineDir' - run via build-apk.sh or prepare-android-project.sh, not gradlew directly")
+}
+def prebuiltDir = engineProps.getProperty('prebuiltDir')
+if (prebuiltDir == null) {
+    throw new GradleException("android/engine.properties is missing 'prebuiltDir' - run via build-apk.sh or prepare-android-project.sh, not gradlew directly")
+}
+
+// Set by build-apk.sh (see build-image/version.sh, shared with the
+// desktop tarball's versioning) via -PquestshockVersionName/Code. Default
+// here only covers a direct, unsupported `gradlew` invocation.
+def questshockVersionName = project.hasProperty('questshockVersionName') ? project.property('questshockVersionName') : '0.0.0-dev'
+def questshockVersionCode = project.hasProperty('questshockVersionCode') ? project.property('questshockVersionCode').toInteger() : 1
+
+// Auto-refreshes the staged, patched engine/ copy and prebuilt libraries
+// (see build-image/prepare-android-project.sh --host-paths, and the
+// engineDir/prebuiltDir properties read above) so a plain Android Studio
+// build/run can never silently compile against a stale scratch copy after
+// engine/ or android/engine-patches/ change - previously a manual, easy to
+// forget re-run. inputs/outputs are declared so Gradle skips the (Docker-
+// invoking, not free) step entirely when nothing relevant actually changed,
+// keeping pure-Java edit/run cycles fast.
+def repoRoot = file("${projectDir}/../..")
+def stageEngineTask = tasks.register("stageEngine", Exec) {
+    group = "build setup"
+    description = "Refreshes the patched engine/ scratch copy and prebuilt libraries for a native Android Studio build (build-image/prepare-android-project.sh --host-paths)."
+    workingDir repoRoot
+    commandLine "./run-image.sh", "bash", "build-image/prepare-android-project.sh", "--host-paths"
+
+    // /opt/prebuilt/android only ever exists inside the build-image
+    // container itself (baked in at image-build time, never on the host -
+    // see build-image/Dockerfile). Its presence means this build is
+    // build-apk.sh's own gradlew call, running INSIDE that container, which
+    // already staged everything itself in container mode before invoking
+    // gradlew - re-running this task there would try to `docker run` from
+    // inside a container with no docker socket, breaking make apk/CI. Only
+    // a genuine host-side Android Studio build (where this path is absent)
+    // needs this task.
+    onlyIf { !file('/opt/prebuilt/android').isDirectory() }
+
+    inputs.dir("${repoRoot}/engine")
+    inputs.dir("${projectDir}/../engine-patches")
+    inputs.file("${repoRoot}/build-image/Dockerfile")
+    outputs.dir("${repoRoot}/build/android-engine")
+    outputs.dir("${repoRoot}/build/android-prebuilt")
+    outputs.file("${projectDir}/../engine.properties")
+}
+
+// preBuild is what every variant's compile/native-build tasks already
+// transitively depend on, regardless of AGP version's exact CMake task
+// naming - the simplest reliable hook to run before any of them.
+afterEvaluate {
+    tasks.named("preBuild").configure {
+        dependsOn stageEngineTask
+    }
 }
 
 android {
@@ -31,8 +90,8 @@ android {
         // targets - not just whatever's the current API level today.
         minSdkVersion 24
         targetSdkVersion 29
-        versionCode 1
-        versionName "1.0"
+        versionCode questshockVersionCode
+        versionName questshockVersionName
 
         externalNativeBuild {
             cmake {
@@ -42,21 +101,37 @@ android {
                 // config, unlike the desktop build's older bundled copy);
                 // SDL2_mixer and FluidSynth via the same build_ext/ BUNDLED
                 // convention the desktop build already uses (populated in the
-                // scratch engine copy by build-apk.sh from
-                // /opt/prebuilt/android/*).
+                // scratch engine copy by prepare-android-project.sh from
+                // prebuiltDir). ANDROID_PREBUILT_DIR is also read directly by
+                // android/engine-patches/02-android-opengl-es.patch, for gl4es.
                 // The CMAKE_FIND_ROOT_PATH* overrides below are needed
                 // because the NDK toolchain file restricts find_package/
                 // find_path/find_library to its own sysroot by default,
                 // which would otherwise miss our custom-installed SDL2 (see
                 // build-image/Dockerfile's SDL2_mixer build, which hit the
                 // exact same thing).
+                // -Wl,-z,max-page-size=16384: NDK 26 doesn't 16 KB-align ELF
+                // LOAD segments by default (only automatic in NDK 28+) - see
+                // build-image/Dockerfile's ANDROID_16KB_LDFLAGS, which does
+                // the same for the prebuilt SDL2/SDL2_mixer/fluidsynth-lite/
+                // gl4es .so's this links against.
+                // ANDROID_EXTRA_SOURCES is a semicolon-separated CMake list,
+                // not shell-split - AGP passes each "arguments" string
+                // straight through as one argv element to cmake, so the
+                // ';' below survives intact. ANDROID_EXTRA_INCLUDE_DIRS lets
+                // engine/'s own OpenGL.cc find "xr_session.h" (see
+                // android/engine-patches/11-android-openxr-cmake.patch,
+                // which adds it to include_directories()).
                 arguments "-DENABLE_SDL2=ON", "-DENABLE_SOUND=BUNDLED", "-DENABLE_FLUIDSYNTH=BUNDLED", \
-                    "-DCMAKE_PREFIX_PATH=/opt/prebuilt/android/sdl2", \
-                    "-DCMAKE_FIND_ROOT_PATH=/opt/prebuilt/android/sdl2", \
+                    "-DANDROID_PREBUILT_DIR=${prebuiltDir}", \
+                    "-DANDROID_EXTRA_INCLUDE_DIRS=${projectDir}/src/main/cpp", \
+                    "-DCMAKE_PREFIX_PATH=${prebuiltDir}/sdl2", \
+                    "-DCMAKE_FIND_ROOT_PATH=${prebuiltDir}/sdl2", \
                     "-DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=BOTH", \
                     "-DCMAKE_FIND_ROOT_PATH_MODE_LIBRARY=BOTH", \
                     "-DCMAKE_FIND_ROOT_PATH_MODE_INCLUDE=BOTH", \
-                    "-DANDROID_EXTRA_SOURCES=${projectDir}/src/main/cpp/questshock_native.c"
+                    "-DCMAKE_SHARED_LINKER_FLAGS=-Wl,-z,max-page-size=16384", \
+                    "-DANDROID_EXTRA_SOURCES=${projectDir}/src/main/cpp/questshock_native.c;${projectDir}/src/main/cpp/xr_session.c"
                 abiFilters 'arm64-v8a'
             }
         }

android/app/src/main/AndroidManifest.xml

@@ -12,6 +12,11 @@
     <!-- External mouse input events -->
     <uses-feature android:name="android.hardware.type.pc" android:required="false" />
 
+    <!-- Immersive OpenXR app now (see android/app/src/main/cpp/xr_session.c),
+         not a 2D Home panel - vr.headtracking is what actually declares that
+         to Horizon OS. -->
+    <uses-feature android:name="android.hardware.vr.headtracking" android:version="1" android:required="true" />
+
     <!-- Plain, unrestricted /sdcard access for the res/data,res/sound the
          user drops in and the shaders/soundfont this app extracts there on
          first run - see res/GET_ASSETS_QUEST.txt and QuestShockActivity.
@@ -28,17 +33,32 @@
         android:theme="@android:style/Theme.NoTitleBar.Fullscreen"
         android:hardwareAccelerated="true" >
 
+        <!-- Tells Horizon OS this activity wants the compositor for itself
+             (immersive VR), not the Home 2D-panel path - required for an
+             OpenXR session to actually start. -->
+        <meta-data android:name="com.oculus.vr.focusaware" android:value="true" />
+
         <activity android:name="de.ladkau.questshock.QuestShockActivity"
             android:label="@string/app_name"
             android:alwaysRetainTaskState="true"
             android:launchMode="singleInstance"
             android:configChanges="layoutDirection|locale|orientation|uiMode|screenLayout|screenSize|smallestScreenSize|keyboard|keyboardHidden|navigation"
             android:preferMinimalPostProcessing="true"
+            android:screenOrientation="landscape"
             android:exported="true"
             >
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
                 <category android:name="android.intent.category.LAUNCHER" />
+                <!-- The vendor-neutral, Khronos-defined way to declare an
+                     immersive OpenXR entry point (vs. e.g. Meta's own
+                     com.oculus.intent.category.VR) - see this project's
+                     "favor OpenXR" rule in the README. If Horizon OS still
+                     launches this as a flat panel on-device, the next thing
+                     to try is adding a com.oculus.supportedDevices meta-data
+                     listing the target Quest models - not confirmed
+                     necessary from static analysis alone. -->
+                <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
             </intent-filter>
             <intent-filter>
                 <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />

android/app/src/main/cpp/xr_session.c

@@ -0,0 +1,456 @@
+#include "xr_session.h"
+
+#include <dlfcn.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <android/log.h>
+#include <jni.h>
+
+#include <EGL/egl.h>
+#include <GLES3/gl3.h>
+
+#define XR_USE_PLATFORM_ANDROID 1
+#define XR_USE_GRAPHICS_API_OPENGL_ES 1
+#include <openxr/openxr.h>
+#include <openxr/openxr_platform.h>
+
+#include <SDL.h>
+
+#define TAG "QuestShock"
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, TAG, __VA_ARGS__)
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, TAG, __VA_ARGS__)
+
+// Fixed pose/size for the single game quad - 2m in front of the local space
+// origin, sized to preserve the game's own aspect ratio at a comfortable
+// visual angle. No per-eye view/projection work is needed for a quad layer
+// at all - the compositor handles reprojecting it per eye itself, which is
+// exactly why this milestone doesn't need xrLocateViews or any stereo
+// rendering (see the plan's step A notes).
+#define QUAD_DISTANCE_METERS 2.0f
+#define QUAD_WIDTH_METERS 1.6f
+
+// Up to this many swapchain images/FBOs - real runtimes report small counts
+// (2-4); this is just a fixed upper bound for the cache arrays below.
+#define MAX_SWAPCHAIN_IMAGES 8
+
+static XrInstance g_instance = XR_NULL_HANDLE;
+static XrSystemId g_system_id = XR_NULL_SYSTEM_ID;
+static XrSession g_session = XR_NULL_HANDLE;
+static XrSpace g_local_space = XR_NULL_HANDLE;
+static XrSessionState g_session_state = XR_SESSION_STATE_UNKNOWN;
+// Distinct from g_session_state - true from a successful xrBeginSession
+// until xrEndSession/loss/exit. Many runtimes only advance the *state*
+// (e.g. READY -> SYNCHRONIZED -> VISIBLE -> FOCUSED) in response to the
+// app actually calling xrWaitFrame/xrBeginFrame/xrEndFrame continuously
+// after xrBeginSession - gating frame submission on already having
+// reached SYNCHRONIZED+ (as this used to) is a chicken-and-egg deadlock,
+// since the runtime never progresses past READY without the frame loop
+// running in the first place. Frame calls just need the session to have
+// begun, per the standard OpenXR sample pattern - not any particular
+// later state.
+static bool g_session_running = false;
+
+static XrSwapchain g_game_swapchain = XR_NULL_HANDLE;
+static int g_game_width = 0;
+static int g_game_height = 0;
+static GLuint g_swapchain_fbos[MAX_SWAPCHAIN_IMAGES];
+static uint32_t g_swapchain_image_count = 0;
+
+static XrTime g_predicted_display_time = 0;
+static bool g_frame_should_render = false;
+static bool g_have_acquired_image = false;
+
+// This file's GL calls otherwise resolve to gl4es (the only GL symbol
+// provider linked into this binary - see android/engine-patches/
+// 02-android-opengl-es.patch), which is fine for anything shared with the
+// engine's own gl4es-routed rendering. But the swapchain images OpenXR
+// hands us are real driver texture objects gl4es never created itself,
+// and gl4es's own glFramebufferTexture2D can't attach a texture it has no
+// tracked metadata for. So the FBO *container* is created via gl4es's own
+// glGenFramebuffers/glBindFramebuffer (so gl4es recognizes the id as its
+// own and its own per-frame glBindFramebuffer succeeds), while the
+// texture-attach step - the specifically foreign part - goes through the
+// real driver directly, via dlsym against libGLESv2.so.
+typedef void (*PFNQSFRAMEBUFFERTEXTURE2D)(GLenum, GLenum, GLenum, GLuint, GLint);
+typedef GLenum (*PFNQSCHECKFRAMEBUFFERSTATUS)(GLenum);
+
+static PFNQSFRAMEBUFFERTEXTURE2D real_glFramebufferTexture2D;
+static PFNQSCHECKFRAMEBUFFERSTATUS real_glCheckFramebufferStatus;
+
+static bool xr_load_real_gles(void) {
+    void *lib = dlopen("libGLESv2.so", RTLD_NOW | RTLD_LOCAL);
+    if (lib == NULL) {
+        LOGE("XR: dlopen(libGLESv2.so) failed: %s", dlerror());
+        return false;
+    }
+    real_glFramebufferTexture2D = (PFNQSFRAMEBUFFERTEXTURE2D)dlsym(lib, "glFramebufferTexture2D");
+    real_glCheckFramebufferStatus =
+        (PFNQSCHECKFRAMEBUFFERSTATUS)dlsym(lib, "glCheckFramebufferStatus");
+    return real_glFramebufferTexture2D && real_glCheckFramebufferStatus;
+}
+
+static bool xr_check(XrResult result, const char *what) {
+    if (XR_SUCCEEDED(result))
+        return true;
+    char resultString[XR_MAX_RESULT_STRING_SIZE] = {0};
+    if (g_instance != XR_NULL_HANDLE)
+        xrResultToString(g_instance, result, resultString);
+    LOGE("XR: %s failed: %s (%d)", what, resultString[0] ? resultString : "?", (int)result);
+    return false;
+}
+
+static PFN_xrVoidFunction xr_get_proc(const char *name) {
+    PFN_xrVoidFunction fn = NULL;
+    // xrGetInstanceProcAddr itself works with a NULL instance for the
+    // handful of functions (like xrInitializeLoaderKHR) that must be called
+    // before an instance exists.
+    if (!xr_check(xrGetInstanceProcAddr(g_instance, name, &fn), name))
+        return NULL;
+    return fn;
+}
+
+// The Android OpenXR loader needs the JavaVM/context before anything else -
+// separate from XR_KHR_android_create_instance below, which only affects
+// xrCreateInstance itself. Skipping this is a common cause of
+// xrCreateInstance silently failing to find a runtime on Android.
+static bool xr_initialize_android_loader(JavaVM *vm, jobject activity) {
+    PFN_xrInitializeLoaderKHR initializeLoader =
+        (PFN_xrInitializeLoaderKHR)xr_get_proc("xrInitializeLoaderKHR");
+    if (initializeLoader == NULL) {
+        LOGE("XR: xrInitializeLoaderKHR not available - no Android OpenXR loader present?");
+        return false;
+    }
+
+    XrLoaderInitInfoAndroidKHR loaderInitInfo = {XR_TYPE_LOADER_INIT_INFO_ANDROID_KHR};
+    loaderInitInfo.applicationVM = vm;
+    loaderInitInfo.applicationContext = activity;
+    return xr_check(initializeLoader((const XrLoaderInitInfoBaseHeaderKHR *)&loaderInitInfo),
+                     "xrInitializeLoaderKHR");
+}
+
+// eglGetCurrentDisplay()/eglGetCurrentContext() hand us the display/context,
+// but not the EGLConfig they were created with - eglQueryContext's
+// EGL_CONFIG_ID plus eglChooseConfig is the standard way to recover it (the
+// same trick Khronos' own hello_xr sample uses).
+static EGLConfig xr_get_current_egl_config(EGLDisplay display, EGLContext context) {
+    EGLint configId = 0;
+    eglQueryContext(display, context, EGL_CONFIG_ID, &configId);
+
+    EGLint attribs[] = {EGL_CONFIG_ID, configId, EGL_NONE};
+    EGLConfig config = NULL;
+    EGLint numConfigs = 0;
+    eglChooseConfig(display, attribs, &config, 1, &numConfigs);
+    return config;
+}
+
+static bool xr_create_instance_and_session(int game_width, int game_height) {
+    JNIEnv *env = (JNIEnv *)SDL_AndroidGetJNIEnv();
+    jobject activity = (jobject)SDL_AndroidGetActivity();
+    if (env == NULL || activity == NULL) {
+        LOGE("XR: no JNIEnv/Activity from SDL - can't init OpenXR");
+        return false;
+    }
+    JavaVM *vm = NULL;
+    (*env)->GetJavaVM(env, &vm);
+
+    if (!xr_initialize_android_loader(vm, activity))
+        return false;
+
+    const char *extensions[] = {
+        XR_KHR_ANDROID_CREATE_INSTANCE_EXTENSION_NAME,
+        XR_KHR_OPENGL_ES_ENABLE_EXTENSION_NAME,
+    };
+
+    XrInstanceCreateInfoAndroidKHR androidInfo = {XR_TYPE_INSTANCE_CREATE_INFO_ANDROID_KHR};
+    androidInfo.applicationVM = vm;
+    androidInfo.applicationActivity = activity;
+
+    XrInstanceCreateInfo createInfo = {XR_TYPE_INSTANCE_CREATE_INFO};
+    createInfo.next = &androidInfo;
+    createInfo.enabledExtensionCount = sizeof(extensions) / sizeof(extensions[0]);
+    createInfo.enabledExtensionNames = extensions;
+    strncpy(createInfo.applicationInfo.applicationName, "QuestShock",
+            XR_MAX_APPLICATION_NAME_SIZE - 1);
+    strncpy(createInfo.applicationInfo.engineName, "Shockolate", XR_MAX_ENGINE_NAME_SIZE - 1);
+    createInfo.applicationInfo.applicationVersion = 1;
+    createInfo.applicationInfo.engineVersion = 1;
+    createInfo.applicationInfo.apiVersion = XR_CURRENT_API_VERSION;
+
+    if (!xr_check(xrCreateInstance(&createInfo, &g_instance), "xrCreateInstance"))
+        return false;
+
+    XrSystemGetInfo systemInfo = {XR_TYPE_SYSTEM_GET_INFO};
+    systemInfo.formFactor = XR_FORM_FACTOR_HEAD_MOUNTED_DISPLAY;
+    if (!xr_check(xrGetSystem(g_instance, &systemInfo, &g_system_id), "xrGetSystem"))
+        return false;
+
+    // Required by spec before creating an OpenGL ES-backed session, even
+    // though we don't gate on the returned min/max API version here.
+    PFN_xrGetOpenGLESGraphicsRequirementsKHR getGLESRequirements =
+        (PFN_xrGetOpenGLESGraphicsRequirementsKHR)xr_get_proc("xrGetOpenGLESGraphicsRequirementsKHR");
+    if (getGLESRequirements == NULL)
+        return false;
+    XrGraphicsRequirementsOpenGLESKHR glesRequirements = {XR_TYPE_GRAPHICS_REQUIREMENTS_OPENGL_ES_KHR};
+    if (!xr_check(getGLESRequirements(g_instance, g_system_id, &glesRequirements),
+                  "xrGetOpenGLESGraphicsRequirementsKHR"))
+        return false;
+
+    EGLDisplay display = eglGetCurrentDisplay();
+    EGLContext context = eglGetCurrentContext();
+    if (display == EGL_NO_DISPLAY || context == EGL_NO_CONTEXT) {
+        LOGE("XR: no current EGL display/context - call xr_init() after init_opengl()");
+        return false;
+    }
+
+    XrGraphicsBindingOpenGLESAndroidKHR graphicsBinding = {
+        XR_TYPE_GRAPHICS_BINDING_OPENGL_ES_ANDROID_KHR};
+    graphicsBinding.display = display;
+    graphicsBinding.config = xr_get_current_egl_config(display, context);
+    graphicsBinding.context = context;
+
+    XrSessionCreateInfo sessionInfo = {XR_TYPE_SESSION_CREATE_INFO};
+    sessionInfo.next = &graphicsBinding;
+    sessionInfo.systemId = g_system_id;
+    if (!xr_check(xrCreateSession(g_instance, &sessionInfo, &g_session), "xrCreateSession"))
+        return false;
+
+    XrReferenceSpaceCreateInfo spaceInfo = {XR_TYPE_REFERENCE_SPACE_CREATE_INFO};
+    spaceInfo.referenceSpaceType = XR_REFERENCE_SPACE_TYPE_LOCAL;
+    spaceInfo.poseInReferenceSpace.orientation.w = 1.0f;
+    if (!xr_check(xrCreateReferenceSpace(g_session, &spaceInfo, &g_local_space),
+                  "xrCreateReferenceSpace"))
+        return false;
+
+    // Prefer a plain linear 8-bit format over GL_SRGB8_ALPHA8: the source
+    // SDL surface pixels are already sRGB-encoded (as ordinary 8-bit image
+    // data conventionally is) and get uploaded/sampled as plain linear
+    // GL_RGBA with no decode step anywhere in this path, matching the
+    // desktop SDL_RenderCopy path this replaces - an sRGB swapchain format
+    // would auto-gamma-encode on write and double-encode already-encoded
+    // data.
+    uint32_t formatCount = 0;
+    xrEnumerateSwapchainFormats(g_session, 0, &formatCount, NULL);
+    int64_t *formats = (int64_t *)malloc(sizeof(int64_t) * formatCount);
+    xrEnumerateSwapchainFormats(g_session, formatCount, &formatCount, formats);
+    int64_t chosenFormat = formats[0];
+    for (uint32_t i = 0; i < formatCount; i++) {
+        LOGI("XR: swapchain format[%u] = 0x%llx", i, (unsigned long long)formats[i]);
+        if (formats[i] == GL_RGBA8) {
+            chosenFormat = GL_RGBA8;
+            break;
+        }
+    }
+    free(formats);
+
+    XrSwapchainCreateInfo swapchainInfo = {XR_TYPE_SWAPCHAIN_CREATE_INFO};
+    swapchainInfo.usageFlags = XR_SWAPCHAIN_USAGE_COLOR_ATTACHMENT_BIT | XR_SWAPCHAIN_USAGE_SAMPLED_BIT;
+    swapchainInfo.format = chosenFormat;
+    swapchainInfo.sampleCount = 1;
+    swapchainInfo.width = (uint32_t)game_width;
+    swapchainInfo.height = (uint32_t)game_height;
+    swapchainInfo.faceCount = 1;
+    swapchainInfo.arraySize = 1;
+    swapchainInfo.mipCount = 1;
+    if (!xr_check(xrCreateSwapchain(g_session, &swapchainInfo, &g_game_swapchain),
+                  "xrCreateSwapchain"))
+        return false;
+    g_game_width = game_width;
+    g_game_height = game_height;
+
+    uint32_t imageCount = 0;
+    xrEnumerateSwapchainImages(g_game_swapchain, 0, &imageCount, NULL);
+    if (imageCount > MAX_SWAPCHAIN_IMAGES) {
+        LOGE("XR: swapchain reports %u images, only room for %d", imageCount,
+             MAX_SWAPCHAIN_IMAGES);
+        return false;
+    }
+    // Zero-initialized, not just `.type` set per element - these structs
+    // also carry a `next` field the runtime may read, and an
+    // uninitialized stack array would leave it as garbage.
+    XrSwapchainImageOpenGLESKHR images[MAX_SWAPCHAIN_IMAGES] = {0};
+    for (uint32_t i = 0; i < imageCount; i++)
+        images[i].type = XR_TYPE_SWAPCHAIN_IMAGE_OPENGL_ES_KHR;
+    if (!xr_check(xrEnumerateSwapchainImages(g_game_swapchain, imageCount, &imageCount,
+                                              (XrSwapchainImageBaseHeader *)images),
+                  "xrEnumerateSwapchainImages"))
+        return false;
+    g_swapchain_image_count = imageCount;
+
+    if (!xr_load_real_gles()) {
+        LOGE("XR: couldn't resolve real GLES FBO functions via dlsym");
+        return false;
+    }
+
+    // Wraps each swapchain-provided texture in its own framebuffer, matching
+    // how OpenGL.cc's own CreateFrameBuffer() wraps backupBuffer - just
+    // without a depth/stencil attachment, since the final composite draw
+    // (see opengl_swap_and_restore) never needs one. The Gen/Bind calls are
+    // gl4es's own (linked, not dlsym'd) - see the comment above
+    // real_glFramebufferTexture2D for why.
+    bool all_complete = true;
+    for (uint32_t i = 0; i < imageCount; i++) {
+        glGenFramebuffers(1, &g_swapchain_fbos[i]);
+        glBindFramebuffer(GL_FRAMEBUFFER, g_swapchain_fbos[i]);
+        real_glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D,
+                                     images[i].image, 0);
+        GLenum status = real_glCheckFramebufferStatus(GL_FRAMEBUFFER);
+        if (status != GL_FRAMEBUFFER_COMPLETE) {
+            LOGE("XR: swapchain FBO %u incomplete: 0x%x", i, status);
+            all_complete = false;
+        }
+    }
+    glBindFramebuffer(GL_FRAMEBUFFER, 0);
+    if (!all_complete)
+        return false;
+
+    LOGI("XR: instance/session/swapchain ready (%dx%d, %u images)", game_width, game_height,
+         imageCount);
+    return true;
+}
+
+bool xr_init(int game_width, int game_height) {
+    if (!xr_create_instance_and_session(game_width, game_height)) {
+        LOGE("XR: bring-up failed - falling back to the normal window present path");
+        xr_shutdown();
+        return false;
+    }
+    return true;
+}
+
+void xr_poll_events(void) {
+    if (g_instance == XR_NULL_HANDLE)
+        return;
+
+    while (true) {
+        XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
+        XrResult result = xrPollEvent(g_instance, &event);
+        if (result == XR_EVENT_UNAVAILABLE)
+            break;
+        if (!xr_check(result, "xrPollEvent"))
+            break;
+
+        if (event.type == XR_TYPE_EVENT_DATA_SESSION_STATE_CHANGED) {
+            XrEventDataSessionStateChanged *stateEvent = (XrEventDataSessionStateChanged *)&event;
+            g_session_state = stateEvent->state;
+            LOGI("XR: session state -> %d", (int)g_session_state);
+
+            if (g_session_state == XR_SESSION_STATE_READY) {
+                XrSessionBeginInfo beginInfo = {XR_TYPE_SESSION_BEGIN_INFO};
+                beginInfo.primaryViewConfigurationType = XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO;
+                g_session_running = xr_check(xrBeginSession(g_session, &beginInfo), "xrBeginSession");
+            } else if (g_session_state == XR_SESSION_STATE_STOPPING) {
+                xr_check(xrEndSession(g_session), "xrEndSession");
+                g_session_running = false;
+            } else if (g_session_state == XR_SESSION_STATE_EXITING ||
+                       g_session_state == XR_SESSION_STATE_LOSS_PENDING) {
+                g_session_running = false;
+            }
+        }
+    }
+}
+
+bool xr_is_session_running(void) { return g_session_running; }
+
+bool xr_frame_begin(void) {
+    g_have_acquired_image = false;
+    if (!xr_is_session_running())
+        return false;
+
+    XrFrameWaitInfo waitInfo = {XR_TYPE_FRAME_WAIT_INFO};
+    XrFrameState frameState = {XR_TYPE_FRAME_STATE};
+    if (!xr_check(xrWaitFrame(g_session, &waitInfo, &frameState), "xrWaitFrame"))
+        return false;
+    g_predicted_display_time = frameState.predictedDisplayTime;
+    g_frame_should_render = frameState.shouldRender;
+
+    XrFrameBeginInfo beginInfo = {XR_TYPE_FRAME_BEGIN_INFO};
+    if (!xr_check(xrBeginFrame(g_session, &beginInfo), "xrBeginFrame"))
+        return false;
+
+    if (!g_frame_should_render)
+        return false;
+
+    uint32_t imageIndex = 0;
+    XrSwapchainImageAcquireInfo acquireInfo = {XR_TYPE_SWAPCHAIN_IMAGE_ACQUIRE_INFO};
+    if (!xr_check(xrAcquireSwapchainImage(g_game_swapchain, &acquireInfo, &imageIndex),
+                  "xrAcquireSwapchainImage"))
+        return false;
+
+    XrSwapchainImageWaitInfo waitImageInfo = {XR_TYPE_SWAPCHAIN_IMAGE_WAIT_INFO};
+    waitImageInfo.timeout = XR_INFINITE_DURATION;
+    if (!xr_check(xrWaitSwapchainImage(g_game_swapchain, &waitImageInfo), "xrWaitSwapchainImage"))
+        return false;
+
+    // gl4es's own (linked, not dlsym'd) bind - this targets an FBO id
+    // gl4es itself created (see xr_create_instance_and_session()), so its
+    // own "current FBO" bookkeeping updates correctly and its immediate-
+    // mode draw calls in android_draw_surface_as_quad() land in the right
+    // place.
+    glBindFramebuffer(GL_FRAMEBUFFER, g_swapchain_fbos[imageIndex]);
+    glViewport(0, 0, g_game_width, g_game_height);
+
+    g_have_acquired_image = true;
+    return true;
+}
+
+void xr_frame_end(void) {
+    if (g_session == XR_NULL_HANDLE)
+        return;
+
+    if (g_have_acquired_image) {
+        XrSwapchainImageReleaseInfo releaseInfo = {XR_TYPE_SWAPCHAIN_IMAGE_RELEASE_INFO};
+        xr_check(xrReleaseSwapchainImage(g_game_swapchain, &releaseInfo),
+                 "xrReleaseSwapchainImage");
+    }
+
+    if (!xr_is_session_running())
+        return;
+
+    XrCompositionLayerQuad quad = {XR_TYPE_COMPOSITION_LAYER_QUAD};
+    quad.space = g_local_space;
+    quad.eyeVisibility = XR_EYE_VISIBILITY_BOTH;
+    quad.subImage.swapchain = g_game_swapchain;
+    quad.subImage.imageRect.extent.width = g_game_width;
+    quad.subImage.imageRect.extent.height = g_game_height;
+    quad.pose.orientation.w = 1.0f;
+    quad.pose.position.z = -QUAD_DISTANCE_METERS;
+    quad.size.width = QUAD_WIDTH_METERS;
+    quad.size.height = QUAD_WIDTH_METERS * (float)g_game_height / (float)g_game_width;
+
+    const XrCompositionLayerBaseHeader *layers[1] = {(XrCompositionLayerBaseHeader *)&quad};
+
+    XrFrameEndInfo endInfo = {XR_TYPE_FRAME_END_INFO};
+    endInfo.displayTime = g_predicted_display_time;
+    endInfo.environmentBlendMode = XR_ENVIRONMENT_BLEND_MODE_OPAQUE;
+    endInfo.layerCount = g_have_acquired_image ? 1 : 0;
+    endInfo.layers = g_have_acquired_image ? layers : NULL;
+    xr_check(xrEndFrame(g_session, &endInfo), "xrEndFrame");
+}
+
+void xr_shutdown(void) {
+    for (uint32_t i = 0; i < g_swapchain_image_count; i++) {
+        if (g_swapchain_fbos[i] != 0)
+            glDeleteFramebuffers(1, &g_swapchain_fbos[i]);
+    }
+    g_swapchain_image_count = 0;
+
+    if (g_game_swapchain != XR_NULL_HANDLE)
+        xrDestroySwapchain(g_game_swapchain);
+    g_game_swapchain = XR_NULL_HANDLE;
+
+    if (g_local_space != XR_NULL_HANDLE)
+        xrDestroySpace(g_local_space);
+    g_local_space = XR_NULL_HANDLE;
+
+    if (g_session != XR_NULL_HANDLE)
+        xrDestroySession(g_session);
+    g_session = XR_NULL_HANDLE;
+
+    if (g_instance != XR_NULL_HANDLE)
+        xrDestroyInstance(g_instance);
+    g_instance = XR_NULL_HANDLE;
+
+    g_session_state = XR_SESSION_STATE_UNKNOWN;
+    g_session_running = false;
+}

android/app/src/main/cpp/xr_session.h

@@ -0,0 +1,56 @@
+// Minimal OpenXR bring-up for questshock's immersive Quest build. Keeps the
+// game's own rendering untouched (see android/engine-patches/
+// 12-android-openxr-present.patch) - this module only owns the OpenXR
+// instance/session/swapchain and the final "submit a quad layer instead of
+// presenting to a window" step. No stereo rendering, no controller input
+// yet (see the plan's steps B/C/D for those) - the game composite is shown
+// as a single flat quad floating in front of the viewer.
+#ifndef QUESTSHOCK_XR_SESSION_H
+#define QUESTSHOCK_XR_SESSION_H
+
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Call once, right after init_opengl() (OpenGL.cc) has created and made
+// current the GL context SDL/gl4es already use - creates the OpenXR
+// instance/session sharing that same EGL display/context, plus one
+// swapchain sized to the game's logical resolution (game_width/height, i.e.
+// grd_cap->w/h - see Shock.c's InitSDL()). Returns false if OpenXR bring-up
+// failed (e.g. no runtime installed) - callers should fall back to the
+// existing window-present path in that case.
+bool xr_init(int game_width, int game_height);
+
+// Pumps XR session-state events. Call once per frame, before
+// xr_frame_begin(). Must still be called even when xr_init() returned
+// false (no-op in that case).
+void xr_poll_events(void);
+
+// True once the session has reached a state where frames are expected
+// (XR_SESSION_STATE_SYNCHRONIZED or later) - i.e. it's safe/required to
+// start calling xr_frame_begin()/xr_frame_end() each frame.
+bool xr_is_session_running(void);
+
+// Begins the XR frame (xrWaitFrame/xrBeginFrame) and, if the runtime wants
+// this frame rendered, acquires the next swapchain image and binds its
+// framebuffer as the current render target - ready for the caller to draw
+// into exactly as it would have drawn to the default framebuffer. Returns
+// true if the caller should draw this frame; xr_frame_end() must be called
+// unconditionally afterward either way (a begun XR frame must always be
+// ended, rendered or not).
+bool xr_frame_begin(void);
+
+// Releases the swapchain image (if one was acquired this frame) and
+// submits it as a single XrCompositionLayerQuad positioned in front of the
+// local reference space's origin, then ends the XR frame.
+void xr_frame_end(void);
+
+void xr_shutdown(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

android/app/src/main/java/de/ladkau/questshock/QuestShockActivity.java

@@ -1,10 +1,15 @@
 package de.ladkau.questshock;
 
 import android.Manifest;
+import android.app.AlertDialog;
+import android.content.Context;
 import android.content.pm.PackageManager;
 import android.content.res.AssetManager;
 import android.os.Bundle;
+import android.os.Handler;
+import android.os.Looper;
 import android.util.Log;
+import android.view.SurfaceHolder;
 import androidx.core.app.ActivityCompat;
 import java.io.File;
 import java.io.FileOutputStream;
@@ -12,16 +17,26 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
 import org.libsdl.app.SDLActivity;
+import org.libsdl.app.SDLSurface;
 
 /**
- * Everything here runs before super.onCreate() (which is what loads the
- * native libraries and eventually calls Shockolate's own main()) - see
- * android/engine-patches/ for why: engine/ itself is never modified, so
- * this Java-side setup is the only place left to prepare
- * /sdcard/questshock/ the way Shockolate's plain relative-path file I/O
- * ("res/data/...", confirmed via grep - none of it goes through SDL_RWops,
- * so Android's asset-manager fallback for SDL_RWFromFile doesn't apply
- * here) expects to find it.
+ * Prepares /sdcard/questshock/ the way Shockolate's plain relative-path
+ * file I/O ("res/data/...", confirmed via grep - none of it goes through
+ * SDL_RWops, so Android's asset-manager fallback for SDL_RWFromFile
+ * doesn't apply here) expects to find it - see android/engine-patches/ for
+ * why this is done from Java instead of patching engine/ itself, which is
+ * never modified.
+ *
+ * super.onCreate() (SDLActivity's) must always run first and unconditionally
+ * - Android throws SuperNotCalledException otherwise, checked right after
+ * onCreate() returns, regardless of what this subclass does afterwards.
+ * SDLActivity's own onCreate() only loads libraries, sets up JNI and the
+ * surface - the actual native SDL_main thread doesn't start until later, from
+ * one of several lifecycle paths (onResume(), onWindowFocusChanged(), and
+ * SDLSurface.surfaceChanged() - see GameSurface below for why that last one
+ * needs its own fix) - so it's safe to do our own checks (and set
+ * SDLActivity.mBrokenLibraries, which most - but not all - of those paths
+ * gate on) afterwards.
  */
 public class QuestShockActivity extends SDLActivity {
     private static final String TAG = "QuestShock";
@@ -44,8 +59,6 @@ public class QuestShockActivity extends SDLActivity {
     // has no public chdir() (confirmed against the actual API 34 stub jar).
     private static native void nativeChdir(String path);
 
-    private Bundle mSavedInstanceState;
-
     @Override
     protected String[] getLibraries() {
         return new String[] {
@@ -56,9 +69,66 @@ public class QuestShockActivity extends SDLActivity {
         };
     }
 
+    // SDLSurface.surfaceChanged() (org/libsdl/app/, vendored from SDL2's own
+    // template) starts the native SDL thread directly - unlike onResume()/
+    // onWindowFocusChanged(), it never checks SDLActivity.mBrokenLibraries
+    // first. Since surfaceChanged() fires on essentially every launch
+    // regardless of that flag, setting mBrokenLibraries alone (see onCreate()/
+    // setUpGameDirAndContinue()) does NOT actually stop the engine from
+    // starting - confirmed on-device: the missing-assets crash still happened
+    // with mBrokenLibraries set, from exactly this path. Route through a
+    // subclass that adds the missing check instead of patching the vendored
+    // file directly.
+    private static class GameSurface extends SDLSurface {
+        GameSurface(Context context) {
+            super(context);
+        }
+
+        @Override
+        public void surfaceChanged(SurfaceHolder holder, int format, int width, int height) {
+            if (SDLActivity.mBrokenLibraries) {
+                return;
+            }
+            super.surfaceChanged(holder, format, width, height);
+        }
+
+        // Diagnostic only (see OpenGL.cc's matching log) - Android's real,
+        // legitimate signal for "this View's laid-out size actually
+        // changed" is onSizeChanged(), fired by the framework itself, not
+        // something we have to poll or guess about. If Quest's Home shell
+        // settles a freshly-launched panel into its final <layout> size via
+        // a genuine later layout pass, this is where that would show up -
+        // confirming whether a real event exists to hook, before writing
+        // any fix around it.
+        @Override
+        protected void onSizeChanged(int w, int h, int oldw, int oldh) {
+            super.onSizeChanged(w, h, oldw, oldh);
+            Log.i(TAG, "GameSurface.onSizeChanged() " + oldw + "x" + oldh + " -> " + w + "x" + h);
+        }
+    }
+
+    @Override
+    protected SDLSurface createSDLSurface(Context context) {
+        return new GameSurface(context);
+    }
+
     @Override
     protected void onCreate(Bundle savedInstanceState) {
-        mSavedInstanceState = savedInstanceState;
+        super.onCreate(savedInstanceState);
+        if (SDLActivity.mBrokenLibraries) {
+            // SDLActivity's own onCreate() already showed its "SDL Error"
+            // dialog for this - nothing left for us to do.
+            return;
+        }
+        // Provisionally block the native engine from starting - cleared only
+        // once setUpGameDirAndContinue() confirms game data is present. Must
+        // happen before requestPermissions() below: the storage-permission
+        // dialog closing can fire onWindowFocusChanged(true) - which starts
+        // the native SDLThread - before the async onRequestPermissionsResult()
+        // callback (which is what actually calls setUpGameDirAndContinue())
+        // gets a chance to run, so mBrokenLibraries has to already be true
+        // going into that race, not set afterwards.
+        SDLActivity.mBrokenLibraries = true;
         if (ActivityCompat.checkSelfPermission(this, Manifest.permission.WRITE_EXTERNAL_STORAGE)
                 != PackageManager.PERMISSION_GRANTED) {
             ActivityCompat.requestPermissions(this,
@@ -96,12 +166,67 @@ public class QuestShockActivity extends SDLActivity {
             copyAssetFile("GET_ASSETS_QUEST.txt", marker);
         }
 
+        // Shockolate's engine/ is never patched to check this itself (see the
+        // class doc above) - it just does plain fopen("res/data/...", ...)
+        // and, on a fresh install with no game data copied in yet, that
+        // fails deep inside startup (init_popups(), which doesn't NULL-check
+        // the load) as a hard native crash instead of a message. Catch the
+        // missing-data case here instead, before Shockolate's native
+        // SDL_main ever starts.
+        if (!isNonEmptyDir(new File(gameDir, "res/data")) || !isNonEmptyDir(new File(gameDir, "res/sound"))) {
+            // mBrokenLibraries is already true (set in onCreate()) - leave it
+            // that way. Every path that starts the native SDL_main thread
+            // (onWindowFocusChanged(), resumeNativeThread(), etc.) already
+            // checks this flag before doing anything native, so this
+            // reliably prevents the engine from starting without having to
+            // duplicate all of SDLActivity's own lifecycle guards ourselves.
+            showMissingAssetsDialog();
+            return;
+        }
+
         // chdir() is process-wide, not per-thread - already in effect for
         // every thread (including the one that will run Shockolate's own
-        // SDL_main) by the time super.onCreate() below starts it.
+        // SDL_main) by the time the native thread actually starts. Done
+        // before clearing mBrokenLibraries below so the engine can never
+        // start pre-chdir.
         nativeChdir(GAME_DIR);
 
-        super.onCreate(mSavedInstanceState);
+        // Assets confirmed present - safe to let the native engine start now.
+        SDLActivity.mBrokenLibraries = false;
+    }
+
+    private static boolean isNonEmptyDir(File dir) {
+        String[] entries = dir.list();
+        return entries != null && entries.length > 0;
+    }
+
+    // Same single-button, non-cancelable pattern as SDLActivity's own
+    // "broken libraries" dialog (org/libsdl/app/SDLActivity.java) - there's
+    // no game to start without this data, so the only way forward is to
+    // close, copy the assets, and relaunch. Message text mirrors
+    // res/assets/GET_ASSETS_QUEST.txt (also extracted to GAME_DIR) so the
+    // user isn't sent hunting for a second file just to read it the first
+    // time - it points back there at the end in case they need it again.
+    private void showMissingAssetsDialog() {
+        new AlertDialog.Builder(this)
+            .setTitle("Game data missing")
+            .setMessage("This app does not include System Shock's game data - it's "
+                + "copyrighted, proprietary content that can't be redistributed. To "
+                + "play, you need to own a copy of System Shock: Enhanced Edition (e.g. "
+                + "from gog.com), installed (on Windows, or via Wine/Proton on Linux).\n\n"
+                + "Using SideQuest (or any MTP file browser) with your Quest connected, "
+                + "copy its res/data/ and res/sound/ folders directly into:\n"
+                + GAME_DIR + "/res/data/\n"
+                + GAME_DIR + "/res/sound/\n"
+                + "They already contain everything needed, in the right layout - no "
+                + "merging or extraction required.\n\n"
+                + "Then relaunch.\n\n"
+                + "(These instructions are also in GET_ASSETS_QUEST.txt in the "
+                + "questshock folder on this device, if you need to read them again.)")
+            .setCancelable(false)
+            .setPositiveButton("Exit", (dialog, which) -> finish())
+            .create()
+            .show();
     }
 
     private void copyAssetFile(String assetPath, File dest) {

android/engine-patches/02-android-opengl-es.patch

@@ -12,8 +12,8 @@
  if(ENABLE_OPENGL)
 -	find_package(OpenGL REQUIRED)
 +	if(ANDROID)
-+		set(OPENGL_INCLUDE_DIRS /opt/prebuilt/android/gl4es/include)
-+		set(OPENGL_LIBRARIES /opt/prebuilt/android/gl4es/lib/libGL.so)
++		set(OPENGL_INCLUDE_DIRS ${ANDROID_PREBUILT_DIR}/gl4es/include)
++		set(OPENGL_LIBRARIES ${ANDROID_PREBUILT_DIR}/gl4es/lib/libGL.so)
 +	else()
 +		find_package(OpenGL REQUIRED)
 +	endif()

android/engine-patches/05-android-audio-driver.patch

@@ -0,0 +1,20 @@
+--- a/src/MacSrc/Shock.c
++++ b/src/MacSrc/Shock.c
+@@ -162,6 +162,17 @@
+ void InitSDL() {
+     SDL_SetHint(SDL_HINT_NO_SIGNAL_HANDLERS, "1");
+     SDL_SetHint(SDL_HINT_RENDER_DRIVER, "opengl");
++#ifdef __ANDROID__
++    // SDL2 2.28.5's AAudio backend (Android's default since API 26) only
++    // ever allows one open non-capture (playback) device at a time - it
++    // keeps a single static handle and asserts on a second open
++    // ('SDL_assert((audioDevice == NULL) || iscapture)' in
++    // src/audio/aaudio/SDL_aaudio.c). SDLSound.c opens two: one directly via
++    // SDL_OpenAudioDevice() for cutscene audio, one via Mix_OpenAudio() for
++    // SFX/MIDI. The older OpenSL ES backend has no such limitation, so force
++    // it instead of AAudio.
++    SDL_SetHint(SDL_HINT_AUDIODRIVER, "openslES");
++#endif
+     if (SDL_Init(SDL_INIT_VIDEO | SDL_INIT_TIMER | SDL_INIT_AUDIO) < 0) {
+         DEBUG("%s: Init failed", __FUNCTION__);
+     }

android/engine-patches/06-android-resize-event.patch

@@ -0,0 +1,27 @@
+--- a/src/Libraries/INPUT/Source/sdl_events.c
++++ b/src/Libraries/INPUT/Source/sdl_events.c
+@@ -737,7 +737,24 @@
+                 break;
+ 
+             case SDL_WINDOWEVENT_MOVED:
++                break;
++
+             case SDL_WINDOWEVENT_RESIZED:
++#ifdef __ANDROID__
++                // Android's SDL video backend (Android_SendResize() in
++                // src/video/android/SDL_androidvideo.c) only ever sends
++                // RESIZED for surface-driven resizes - e.g. the Quest Home
++                // shell settling the 2D panel into its requested <layout>
++                // defaultWidth/defaultHeight after activity launch - never
++                // SIZE_CHANGED (unlike desktop platforms, where an
++                // app-driven SDL_SetWindowSize() triggers both, handled
++                // above). Without this, opengl_resize() never re-runs after
++                // that late resize, leaving the GL viewport stuck at
++                // whatever (smaller) size the window first reported,
++                // rendered into one corner of the now-larger surface.
++                if (can_use_opengl())
++                    opengl_resize(ev.window.data1, ev.window.data2);
++#endif
+                 break;
+ 
+             case SDL_WINDOWEVENT_FOCUS_GAINED:

android/engine-patches/07-android-size-diagnostics.patch

@@ -0,0 +1,24 @@
+--- a/src/MacSrc/OpenGL.cc
++++ b/src/MacSrc/OpenGL.cc
+@@ -332,6 +332,21 @@
+ 
+     int width, height;
+     SDL_GetWindowSize(window, &width, &height);
++#ifdef __ANDROID__
++    // Temporary diagnostic: the reported panel/surface size is correct
++    // (confirmed via SDLSurface's own "Window size" log and a Java-side
++    // onSizeChanged() probe showing no later relayout), but the rendered
++    // content still only fills a small corner of it. That means the
++    // divergence is somewhere below the Java/Activity layer - between what
++    // SDL_GetWindowSize() (the value used for opengl_resize() below) reports
++    // and what SDL/EGL/gl4es actually believe the live drawable size is.
++    // Compare all three directly instead of guessing further.
++    int drawable_w, drawable_h, output_w, output_h;
++    SDL_GL_GetDrawableSize(window, &drawable_w, &drawable_h);
++    SDL_GetRendererOutputSize(renderer, &output_w, &output_h);
++    INFO("Android size diag: SDL_GetWindowSize=%dx%d SDL_GL_GetDrawableSize=%dx%d SDL_GetRendererOutputSize=%dx%d",
++         width, height, drawable_w, drawable_h, output_w, output_h);
++#endif
+     opengl_resize(width, height);
+ 
+     // Now make the palettes

android/engine-patches/08-android-logcat-link.patch

@@ -0,0 +1,10 @@
+--- a/CMakeLists.txt
++++ b/CMakeLists.txt
+@@ -440,6 +440,7 @@
+ 	${FLUIDSYNTH_LIBRARIES}
+ 	${OPENGL_LIBRARIES}
+ 	${ALSA_LIBRARIES}
++	$<$<BOOL:${ANDROID}>:log>
+ )
+ 
+ # Turn on address sanitizing if wanted (desktop only - not meaningful for

android/engine-patches/09-android-logcat-output.patch

@@ -0,0 +1,45 @@
+--- a/src/Libraries/LG/Source/LOG/src/log.c
++++ b/src/Libraries/LG/Source/LOG/src/log.c
+@@ -28,6 +28,10 @@
+ 
+ #include "log.h"
+ 
++#ifdef __ANDROID__
++#include <android/log.h>
++#endif
++
+ static struct {
+   void *udata;
+   log_LockFn lock;
+@@ -99,6 +103,23 @@
+   time_t t = time(NULL);
+   struct tm *lt = localtime(&t);
+ 
++#ifdef __ANDROID__
++  /* Plain stdout/stderr isn't captured by logcat on this platform (unlike
++     e.g. gl4es's own "LIBGL"-tagged logging, which goes through this same
++     API directly) - route there instead so every existing INFO/DEBUG/WARN/
++     ERROR call site in the engine becomes visible for on-device debugging,
++     with no changes needed at those call sites. */
++  if (!L.quiet) {
++    static const int android_priority[] = {
++        ANDROID_LOG_VERBOSE, ANDROID_LOG_DEBUG, ANDROID_LOG_INFO,
++        ANDROID_LOG_WARN, ANDROID_LOG_ERROR, ANDROID_LOG_FATAL
++    };
++    va_list args;
++    va_start(args, fmt);
++    __android_log_vprint(android_priority[level], "QuestShock", fmt, args);
++    va_end(args);
++  }
++#else
+   /* Log to stderr */
+   if (!L.quiet) {
+     va_list args;
+@@ -116,6 +137,7 @@
+     va_end(args);
+     fprintf(stderr, "\n");
+   }
++#endif
+ 
+   /* Log to file */
+   if (L.fp) {

android/engine-patches/10-android-no-window-resize.patch

@@ -0,0 +1,31 @@
+--- a/src/MacSrc/ShockBitmap.c
++++ b/src/MacSrc/ShockBitmap.c
+@@ -42,11 +42,28 @@
+ 
+     SDL_RenderClear(renderer);
+ 
++#ifndef __ANDROID__
++    // On Android there's exactly one OS-controlled-size surface - no
++    // desktop-style window to resize, move, or toggle fullscreen on.
++    // SDL_SetWindowSize() still "succeeds" there (Android has no
++    // SetWindowSize driver hook, so SDL's generic layer just overwrites its
++    // own cached window->w/h to the requested game resolution, e.g.
++    // 640x480, and synthesizes a resize event from that) - which desyncs
++    // SDL's own notion of the window size from the real, unchanged Android
++    // surface size (e.g. 1600x1200), and that desync is exactly what then
++    // makes both SDL's internal renderer viewport and this engine's own
++    // custom GL viewport (OpenGL.cc's opengl_resize(), driven by that same
++    // now-wrong cached size) shrink to the game's resolution instead of
++    // filling the real surface - confirmed on-device via added logcat
++    // diagnostics (see android/engine-patches/07-09) showing the correct
++    // 1600x1200 size at startup, then this exact call sequence collapsing
++    // it to 640x480 the moment the splash screen sets its video mode.
+     extern bool fullscreenActive;
+     SDL_SetWindowFullscreen(window, fullscreenActive ? SDL_WINDOW_FULLSCREEN_DESKTOP : 0);
+ 
+     SDL_SetWindowSize(window, width, height);
+     SDL_SetWindowPosition(window, SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED);
++#endif
+ 
+     SDL_RenderSetLogicalSize(renderer, width, height);
+ 

android/engine-patches/11-android-openxr-cmake.patch

@@ -0,0 +1,39 @@
+--- a/CMakeLists.txt
++++ b/CMakeLists.txt
+@@ -64,6 +64,19 @@
+ 	endif(WIN32)
+ endif(ENABLE_OPENGL)
+ 
++# OpenXR loader (Android only for now - see android/app/src/main/cpp/
++# xr_session.c, which submits the game's existing render as a composition
++# layer instead of presenting to a normal window/surface). EGL is linked
++# explicitly too - xr_session.c calls eglGetCurrentDisplay/Context/
++# QueryContext/ChooseConfig directly (to share the GL context gl4es/SDL
++# already made), and unlike GL itself (where gl4es's own libGL.so already
++# provides every symbol the engine or xr_session.c call), there's no other
++# EGL provider in this link.
++if(ANDROID)
++	set(OPENXR_INCLUDE_DIRS ${ANDROID_PREBUILT_DIR}/openxr/include)
++	set(OPENXR_LIBRARIES ${ANDROID_PREBUILT_DIR}/openxr/lib/libopenxr_loader.so EGL)
++endif(ANDROID)
++
+ if(ENABLE_SDL2 MATCHES "ON")
+ 	find_package(SDL2 REQUIRED)
+ 	if(SDL2_FOUND)
+@@ -109,6 +122,8 @@
+ 	${SDL2_MIXER_INCLUDE_DIRS}
+ 	${FLUIDSYNTH_INCLUDE_DIRS}
+ 	${OPENGL_INCLUDE_DIRS}
++	${OPENXR_INCLUDE_DIRS}
++	${ANDROID_EXTRA_INCLUDE_DIRS}
+ )
+ 
+ if(NOT WIN32)
+@@ -439,6 +454,7 @@
+ 	${SDL2_MIXER_LIBRARIES}
+ 	${FLUIDSYNTH_LIBRARIES}
+ 	${OPENGL_LIBRARIES}
++	${OPENXR_LIBRARIES}
+ 	${ALSA_LIBRARIES}
+ 	$<$<BOOL:${ANDROID}>:log>
+ )

android/engine-patches/12-android-openxr-present.patch

@@ -0,0 +1,252 @@
+--- a/src/MacSrc/OpenGL.cc	2026-07-25 07:10:06.189412183 +0200
++++ b/src/MacSrc/OpenGL.cc	2026-07-25 07:12:05.356301052 +0200
+@@ -36,6 +36,7 @@
+     if (loc >= 0)
+         glUniform1f(loc, size);
+ }
++#include "xr_session.h"
+ #endif // __ANDROID__
+ 
+ extern "C" {
+@@ -382,6 +383,21 @@
+ #endif
+     opengl_resize(width, height);
+ 
++#ifdef __ANDROID__
++    // Bring up the OpenXR session now that the shared GL context above is
++    // current (xr_init() reuses it via eglGetCurrentContext/Display - see
++    // xr_session.c) - sized to the game's own logical resolution, not the
++    // physical window, since the swapchain is composited by the XR runtime
++    // rather than upscaled by us into a physical-window-sized viewport (see
++    // opengl_swap_and_restore()/android_composite_software_frame() below).
++    // Failure here (e.g. no OpenXR runtime installed) just means the
++    // immersive path never activates - SDLDraw() falls back to the plain
++    // window-present path for the rest of the run.
++    int xr_logical_width, xr_logical_height;
++    SDL_RenderGetLogicalSize(renderer, &xr_logical_width, &xr_logical_height);
++    xr_init(xr_logical_width, xr_logical_height);
++#endif
++
+     // Now make the palettes
+     opaquePalette = SDL_AllocPalette(256);
+     transparentPalette = SDL_AllocPalette(256);
+@@ -498,7 +514,109 @@
+     *y_scale = output_height / screen_height;
+ }
+ 
++#ifdef __ANDROID__
++// Shared by opengl_swap_and_restore()'s UI-overlay blit and
++// android_composite_software_frame() below - draws an SDL_Surface as a
++// fullscreen textured quad via gl4es. SDL's own renderer can't be used
++// here: it's tied to the window's own EGL surface, not whatever XR
++// swapchain framebuffer the caller already bound via xr_frame_begin().
++static void android_draw_surface_as_quad(SDL_Surface *ui, bool blend) {
++    SDL_Surface *uiRgba = SDL_ConvertSurfaceFormat(ui, SDL_PIXELFORMAT_RGBA32, 0);
++    if (uiRgba == nullptr)
++        return;
++
++    glUseProgram(textureShaderProgram.shaderProgram);
++    GLint tcAttrib = textureShaderProgram.tcAttrib;
++    GLint lightAttrib = textureShaderProgram.lightAttrib;
++    glUniform1i(textureShaderProgram.uniNightSight, false);
++    glUniformMatrix4fv(textureShaderProgram.uniView, 1, false, IdentityMatrix);
++    glUniformMatrix4fv(textureShaderProgram.uniProj, 1, false, IdentityMatrix);
++
++    // Persistent texture, reused every call instead of a fresh
++    // gen/upload/delete each frame.
++    static GLuint s_uiTexture = 0;
++    if (s_uiTexture == 0)
++        glGenTextures(1, &s_uiTexture);
++    bind_texture(s_uiTexture);
++    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST);
++    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
++    glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, uiRgba->w, uiRgba->h, 0, GL_RGBA, GL_UNSIGNED_BYTE,
++                 uiRgba->pixels);
++
++    set_blend_mode(blend);
++
++    // Real per-vertex arrays, not glBegin/glVertexAttrib/glVertex3f
++    // immediate mode: glVertexAttrib*() is GLES2's *constant*-attribute
++    // API - without an enabled vertex array it sets one value for the
++    // whole draw call, not a fresh value per vertex. gl4es's immediate-mode
++    // emulation only reproduces desktop GL's per-vertex-capture behavior
++    // for attribute 0 (position, driven directly by glVertex3f), not for
++    // custom attributes like this shader's texcoords/light.
++    //
++    // V is flipped (1 at the bottom, 0 at the top): GL texture v=0
++    // addresses the first row of data passed to glTexImage2D, but uiRgba
++    // (an SDL surface) stores its rows top-down.
++    struct QuadVertex {
++        float x, y, z;
++        float u, v;
++        float light;
++    };
++    static const QuadVertex quadVerts[4] = {
++        {1.0f, -1.0f, 0.0f, 1.0f, 1.0f, 1.0f},
++        {1.0f, 1.0f, 0.0f, 1.0f, 0.0f, 1.0f},
++        {-1.0f, -1.0f, 0.0f, 0.0f, 1.0f, 1.0f},
++        {-1.0f, 1.0f, 0.0f, 0.0f, 0.0f, 1.0f},
++    };
++    glEnableVertexAttribArray(0);
++    glEnableVertexAttribArray(tcAttrib);
++    glEnableVertexAttribArray(lightAttrib);
++    glVertexAttribPointer(0, 3, GL_FLOAT, GL_FALSE, sizeof(QuadVertex), &quadVerts[0].x);
++    glVertexAttribPointer(tcAttrib, 2, GL_FLOAT, GL_FALSE, sizeof(QuadVertex), &quadVerts[0].u);
++    glVertexAttribPointer(lightAttrib, 1, GL_FLOAT, GL_FALSE, sizeof(QuadVertex),
++                           &quadVerts[0].light);
++    glDrawArrays(GL_TRIANGLE_STRIP, 0, 4);
++    // The engine's other rendering uses glBegin/glVertexAttrib/glVertex3f
++    // immediate mode for attribute 0, which depends on it not having an
++    // enabled array bound.
++    glDisableVertexAttribArray(0);
++    glDisableVertexAttribArray(tcAttrib);
++    glDisableVertexAttribArray(lightAttrib);
++    glFlush();
++
++    SDL_FreeSurface(uiRgba);
++}
++
++void android_composite_software_frame(SDL_Surface *ui) {
++    // Deliberately no SDL_GL_MakeCurrent() here - see the comment in
++    // opengl_swap_and_restore() below for why.
++    glClear(GL_COLOR_BUFFER_BIT);
++    android_draw_surface_as_quad(ui, false);
++}
++#endif
++
+ void opengl_swap_and_restore(SDL_Surface *ui) {
++#ifdef __ANDROID__
++    // No SDL_GL_MakeCurrent() here on Android, deliberately - unlike the
++    // desktop path below. init_opengl() already made (window, context)
++    // current once; re-asserting it every frame turned out to reset
++    // gl4es's own internal "current framebuffer" bookkeeping back to
++    // whatever it associates with that context/surface pair (observed
++    // on-device: the XR swapchain image reliably received our real
++    // glClear/bind from xr_frame_begin(), but every actual gl4es-routed
++    // draw call after a fresh SDL_GL_MakeCurrent() here kept landing
++    // somewhere else - the quad stayed permanently black). Confirmed this
++    // exact class of gl4es/OpenXR interaction against RTCWQuest (Team
++    // Beef Studios), a shipped gl4es+Khronos-OpenXR-loader Quest port:
++    // it makes its EGL context current exactly once at init and never
++    // again per-frame, for the same reason.
++    //
++    // xr_frame_begin() (called from SDLDraw()) already bound the XR
++    // swapchain's framebuffer and a full-size viewport - no physical-
++    // window letterboxing needed here either, unlike the desktop/2D-panel
++    // path below, since the swapchain is sized to exactly the game's
++    // logical resolution (see xr_init()).
++    glClear(GL_COLOR_BUFFER_BIT);
++#else
+     // restore the view backup (without HUD overlay) for incremental
+     // updates in the subsequent frame
+     SDL_GL_MakeCurrent(window, context);
+@@ -510,6 +628,7 @@
+     // Set the drawable area for the 3d view
+     glViewport(phys_offset_x * x_hdpi_scale, phys_offset_y * y_hdpi_scale, phys_width * x_hdpi_scale,
+                phys_height * y_hdpi_scale);
++#endif
+     set_blend_mode(false);
+ 
+     // Bind and setup our general shader program
+@@ -552,6 +671,11 @@
+     if (err != GL_NO_ERROR)
+         ERROR("OpenGL error: %i", err);
+ 
++#ifdef __ANDROID__
++    // Blit the UI canvas over the 3d view (see android_draw_surface_as_quad()
++    // above - SDL's renderer can't target the XR swapchain framebuffer).
++    android_draw_surface_as_quad(ui, true);
++#else
+     // Blit the UI canvas over the 3d view
+     SDL_Texture *texture = SDL_CreateTextureFromSurface(renderer, ui);
+     SDL_SetTextureBlendMode(texture, SDL_BLENDMODE_BLEND);
+@@ -561,6 +685,7 @@
+ 
+     // Finally, swap to the screen
+     SDL_RenderPresent(renderer);
++#endif
+ }
+ 
+ void toggle_opengl() {
+--- a/src/MacSrc/OpenGL.h	2026-07-19 13:11:51.000000000 +0200
++++ b/src/MacSrc/OpenGL.h	2026-07-25 07:10:06.353410581 +0200
+@@ -22,6 +22,15 @@
+ void opengl_swap_and_restore(SDL_Surface *ui);
+ void opengl_change_palette();
+ 
++#ifdef __ANDROID__
++// Composites a plain software-rendered frame (the same content SDLDraw's
++// non-OpenGL fallback would otherwise present via SDL_RenderCopy) into the
++// XR swapchain image already bound by xr_frame_begin() - see Shock.c's
++// SDLDraw(), which needs this for the splash screen/cutscenes/menus that
++// render this way instead of through opengl_swap_and_restore().
++void android_composite_software_frame(SDL_Surface *ui);
++#endif
++
+ void opengl_set_viewport(int x, int y, int width, int height);
+ int opengl_draw_tmap(int n, g3s_phandle *vp, grs_bitmap *bm);
+ int opengl_light_tmap(int n, g3s_phandle *vp, grs_bitmap *bm);
+--- a/src/MacSrc/Shock.c	2026-07-25 07:10:06.181412261 +0200
++++ b/src/MacSrc/Shock.c	2026-07-25 07:10:06.353410581 +0200
+@@ -30,6 +30,10 @@
+ #include <math.h>
+ #include <SDL.h>
+ 
++#ifdef __ANDROID__
++#include "xr_session.h"
++#endif
++
+ #include "InitMac.h"
+ #include "Modding.h"
+ #include "OpenGL.h"
+@@ -301,6 +305,21 @@
+ }
+ 
+ void SDLDraw() {
++#ifdef __ANDROID__
++    // The true once-a-frame present hook for the immersive OpenXR path -
++    // unlike opengl_swap_and_restore() below, this runs every frame
++    // regardless of should_opengl_swap() (e.g. also during the splash
++    // screen/cutscenes/menus, which render through the plain software
++    // path below, not the OpenGL one). xr_poll_events() needs exactly that
++    // - called unconditionally - to ever observe the session reach a
++    // running state in the first place.
++    xr_poll_events();
++    if (!xr_frame_begin()) {
++        xr_frame_end();
++        return;
++    }
++#endif
++
+     if (should_opengl_swap()) {
+         // We want the UI background to be transparent!
+         sdlPalette->colors[255].a = 0x00;
+@@ -310,14 +329,27 @@
+ 
+         // Set the palette back, and we are done
+         sdlPalette->colors[255].a = 0xff;
++#ifdef __ANDROID__
++        xr_frame_end();
++#endif
+         return;
+     }
+ 
++#ifdef __ANDROID__
++    // Same software-rendered frame the desktop path below would present
++    // via SDL_RenderCopy/SDL_RenderPresent, composited into the XR
++    // swapchain image xr_frame_begin() bound above instead - SDL's
++    // renderer is tied to the window's own EGL surface, not that FBO.
++    android_composite_software_frame(drawSurface);
++    xr_frame_end();
++    return;
++#endif
++
+     // Clear the screen!
+     SDL_RenderClear(renderer);
+     SDL_Texture *texture = SDL_CreateTextureFromSurface(renderer, drawSurface);
+ 
+-    // Blit to the screen by drawing the surface 
++    // Blit to the screen by drawing the surface
+     SDL_Rect srcRect = {0, 0, gScreenWide, gScreenHigh};
+     SDL_RenderCopy(renderer, texture, &srcRect, NULL);
+     SDL_DestroyTexture(texture);

build-image/Dockerfile

@@ -46,10 +46,25 @@ ARG ANDROID_COMPILE_SDK_VERSION=34
 ARG ANDROID_BUILD_TOOLS_VERSION=34.0.0
 ARG ANDROID_NDK_VERSION=26.1.10909125
 ARG ANDROID_CMAKE_VERSION=3.22.1
+# NDK 26 doesn't yet default to 16 KB-aligned ELF LOAD segments (that only
+# became automatic in NDK 28+) - Google requires this for Play Store
+# submissions targeting Android 15+ as of Nov 2025, and it's cheap/harmless
+# to do regardless of Play Store status. Passed to every Android shared-lib
+# CMake configure below, and to the engine's own build via
+# android/app/build.gradle's externalNativeBuild.cmake.arguments.
+ARG ANDROID_16KB_LDFLAGS="-Wl,-z,max-page-size=16384"
 # GL4ES (https://github.com/ptitSeb/gl4es) - translates the engine's
 # desktop-style immediate-mode OpenGL calls into real GLES/EGL calls, so
 # engine/src/MacSrc/OpenGL.cc needs no immediate-mode rewrite on Android.
 ARG ANDROID_GL4ES_VERSION=1.1.6
+# Khronos' own OpenXR loader (https://github.com/KhronosGroup/OpenXR-SDK) -
+# the vendor-neutral loader, not Meta's redistributed copy, per this
+# project's "favor OpenXR" rule (see README's Design principles). Only the
+# loader is built (BUILD_LOADER=ON, everything else off) - the actual XR
+# runtime implementation is resolved on-device by Horizon OS at load time,
+# nothing else needs bundling. Verify this is still the latest release tag
+# at https://github.com/KhronosGroup/OpenXR-SDK/releases when bumping.
+ARG ANDROID_OPENXR_VERSION=1.1.42
 
 ENV DEBIAN_FRONTEND=noninteractive
 
@@ -77,12 +92,17 @@ ENV DEBIAN_FRONTEND=noninteractive
 # build cache for this layer - and vice versa, adding a package here only
 # ever costs a rebuild of the (slow) layers below it, not a re-download
 # of packages that didn't change.
+# patchelf: fixes up GL4ES's built-in ELF SONAME below (see the gl4es
+# build step) - the Android APK packager (AGP) refuses to bundle a
+# jniLibs file whose name doesn't literally end in ".so", but the
+# dynamic linker resolves NEEDED entries by embedded SONAME, not
+# filename - patchelf lets both agree on "libGL.so".
 RUN apt-get update && apt-get install -y --no-install-recommends \
         build-essential cmake make git curl ca-certificates pkg-config gosu \
         libgl1-mesa-dev libglx-dev libxext-dev libx11-dev libxrandr-dev \
         libxi-dev libxfixes-dev libxss-dev libxinerama-dev libxcursor-dev \
         libogg-dev libvorbis-dev libasound2-dev openssh-client \
-        openjdk-17-jdk-headless unzip \
+        openjdk-17-jdk-headless unzip patchelf \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /opt/prebuilt
@@ -177,6 +197,7 @@ RUN curl -sSLO "https://www.libsdl.org/release/SDL2-${ANDROID_SDL2_VERSION}.tar.
         -DANDROID_ABI="${ANDROID_ABI}" -DANDROID_PLATFORM="android-${ANDROID_PLATFORM_VERSION}" \
         -DCMAKE_INSTALL_PREFIX=/opt/prebuilt/android/sdl2 -DBUILD_SHARED_LIBS=ON \
         -DSDL_STATIC=OFF \
+        -DCMAKE_SHARED_LINKER_FLAGS="${ANDROID_16KB_LDFLAGS}" \
     && cmake --build build-sdl2-android -j"$(nproc)" \
     && cmake --install build-sdl2-android \
     && rm -rf "SDL2-${ANDROID_SDL2_VERSION}" "SDL2-${ANDROID_SDL2_VERSION}.tar.gz" build-sdl2-android
@@ -202,6 +223,7 @@ RUN curl -sSLO "https://www.libsdl.org/projects/SDL_mixer/release/SDL2_mixer-${A
         -DSDL2MIXER_FLAC=OFF -DSDL2MIXER_GME=OFF -DSDL2MIXER_MOD=OFF \
         -DSDL2MIXER_MP3=OFF -DSDL2MIXER_MIDI=OFF -DSDL2MIXER_OPUS=OFF -DSDL2MIXER_VORBIS=OFF \
         -DSDL2MIXER_WAVPACK=OFF \
+        -DCMAKE_SHARED_LINKER_FLAGS="${ANDROID_16KB_LDFLAGS}" \
     && cmake --build build-sdl2mixer-android -j"$(nproc)" \
     && cmake --install build-sdl2mixer-android \
     && rm -rf "SDL2_mixer-${ANDROID_SDL2_MIXER_VERSION}" "SDL2_mixer-${ANDROID_SDL2_MIXER_VERSION}.tar.gz" build-sdl2mixer-android
@@ -217,6 +239,7 @@ RUN git clone https://github.com/EtherTyper/fluidsynth-lite.git fluidsynth-lite-
     && cmake -S fluidsynth-lite-android -B build-fluidsynth-android \
         -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK_TOOLCHAIN}" \
         -DANDROID_ABI="${ANDROID_ABI}" -DANDROID_PLATFORM="android-${ANDROID_PLATFORM_VERSION}" \
+        -DCMAKE_SHARED_LINKER_FLAGS="${ANDROID_16KB_LDFLAGS}" \
     && cmake --build build-fluidsynth-android -j"$(nproc)" \
     && mkdir -p /opt/prebuilt/android/fluidsynth-lite/lib /opt/prebuilt/android/fluidsynth-lite/include \
     && cp -a build-fluidsynth-android/src/libfluidsynth.so* /opt/prebuilt/android/fluidsynth-lite/lib/ \
@@ -231,8 +254,17 @@ RUN git clone https://github.com/EtherTyper/fluidsynth-lite.git fluidsynth-lite-
 
 # gl4es's own CMakeLists.txt writes its output straight to
 # ${CMAKE_SOURCE_DIR}/lib (the source tree, not the build dir) and gives
-# the GL target a ".so.1" suffix - stage explicitly rather than
-# `cmake --install` (which it doesn't support for this target anyway).
+# the GL target a ".so.1" suffix, both in filename and in its embedded
+# ELF SONAME - stage explicitly rather than `cmake --install` (which it
+# doesn't support for this target anyway). Renaming the *file* to
+# "libGL.so" isn't enough on its own: the dynamic linker resolves
+# libmain.so's NEEDED entry by the *embedded* SONAME, not by whatever
+# filename it was linked against, so a bare rename would link fine but
+# fail to dlopen on-device. And keeping the real "libGL.so.1" filename
+# isn't an option either - AGP's jniLibs packaging silently drops any
+# native library whose filename doesn't literally end in ".so". So
+# patchelf the embedded SONAME to "libGL.so" too, making the rename
+# consistent both at link time and at runtime.
 RUN git clone --branch "v${ANDROID_GL4ES_VERSION}" --depth 1 \
         https://github.com/ptitSeb/gl4es.git gl4es-android \
     && rm -rf gl4es-android/.git \
@@ -240,12 +272,34 @@ RUN git clone --branch "v${ANDROID_GL4ES_VERSION}" --depth 1 \
         -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK_TOOLCHAIN}" \
         -DANDROID_ABI="${ANDROID_ABI}" -DANDROID_PLATFORM="android-${ANDROID_PLATFORM_VERSION}" \
         -DANDROID=ON -DUSE_ANDROID_LOG=ON -DSTATICLIB=OFF \
+        -DCMAKE_SHARED_LINKER_FLAGS="${ANDROID_16KB_LDFLAGS}" \
     && cmake --build build-gl4es-android -j"$(nproc)" \
     && mkdir -p /opt/prebuilt/android/gl4es/lib /opt/prebuilt/android/gl4es/include \
     && cp -a gl4es-android/lib/libGL.so.1 /opt/prebuilt/android/gl4es/lib/libGL.so \
+    && patchelf --set-soname libGL.so /opt/prebuilt/android/gl4es/lib/libGL.so \
     && cp -a gl4es-android/include/. /opt/prebuilt/android/gl4es/include/ \
     && rm -rf gl4es-android build-gl4es-android
 
+# OpenXR loader, for the immersive VR mode (android/app/src/main/cpp/
+# xr_session.c and friends) - see android/engine-patches/
+# 11-android-openxr-cmake.patch for how the engine links it.
+RUN git clone --branch "release-${ANDROID_OPENXR_VERSION}" --depth 1 \
+        https://github.com/KhronosGroup/OpenXR-SDK.git openxr-sdk-android \
+    && rm -rf openxr-sdk-android/.git \
+    && cmake -S openxr-sdk-android -B build-openxr-android \
+        -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK_TOOLCHAIN}" \
+        -DANDROID_ABI="${ANDROID_ABI}" -DANDROID_PLATFORM="android-${ANDROID_PLATFORM_VERSION}" \
+        -DCMAKE_INSTALL_PREFIX=/opt/prebuilt/android/openxr \
+        -DBUILD_LOADER=ON -DBUILD_TESTS=OFF -DBUILD_API_LAYERS=OFF \
+        -DBUILD_CONFORMANCE_TESTS=OFF -DBUILD_WITH_SYSTEM_JSONCPP=OFF \
+        -DDYNAMIC_LOADER=ON \
+        -DCMAKE_SHARED_LINKER_FLAGS="${ANDROID_16KB_LDFLAGS}" \
+    && cmake --build build-openxr-android -j"$(nproc)" --target openxr_loader \
+    && cmake --install build-openxr-android \
+    && mkdir -p /opt/prebuilt/android/openxr/include \
+    && cp -a openxr-sdk-android/include/. /opt/prebuilt/android/openxr/include/ \
+    && rm -rf openxr-sdk-android build-openxr-android
+
 COPY build-image/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
 COPY build-image/build-engine.sh /usr/local/bin/build-engine.sh
 RUN chmod +x /usr/local/bin/docker-entrypoint.sh /usr/local/bin/build-engine.sh

build-image/build-apk.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
-# Builds the Quest APK from a scratch, patched copy of engine/ (see
-# android/engine-patches/ - engine/ itself is never modified) plus the
-# Android SDL2/SDL2_mixer/fluidsynth-lite prebuilt into this image at
-# /opt/prebuilt/android/*. Run via ../run-image.sh (or directly, if
-# already inside this image - see the Makefile's `apk` target).
+# Builds the Quest APK - see build-image/prepare-android-project.sh (which
+# this calls) for how android/ gets a scratch, patched copy of engine/,
+# the Android SDL2/SDL2_mixer/fluidsynth-lite/gl4es prebuilts, and bundled
+# assets staged in. Run via ../run-image.sh (or directly, if already
+# inside this image - see the Makefile's `apk` target).
 #
 # Unlike build-engine.sh, this step needs network access: Gradle/AGP's
 # own dependency resolution isn't prebuilt into the image (see
@@ -12,53 +12,29 @@ set -euo pipefail
 
 REPO_ROOT="$(pwd)"
 ANDROID_DIR="$REPO_ROOT/android"
-SCRATCH_ENGINE="$REPO_ROOT/build/android-engine"
 
-echo "== Preparing a scratch, patched copy of engine/ =="
-rm -rf "$SCRATCH_ENGINE"
-mkdir -p "$(dirname "$SCRATCH_ENGINE")"
-cp -a "$REPO_ROOT/engine" "$SCRATCH_ENGINE"
-for p in "$ANDROID_DIR"/engine-patches/*.patch; do
-    patch -p1 -d "$SCRATCH_ENGINE" < "$p"
-done
+bash "$REPO_ROOT/build-image/prepare-android-project.sh"
 
-echo "== Wiring up prebuilt Android SDL2_mixer/fluidsynth-lite (BUNDLED mode, like the desktop build) =="
-mkdir -p "$SCRATCH_ENGINE/build_ext/built_sdl_mixer" "$SCRATCH_ENGINE/build_ext/fluidsynth-lite"
-cp -a /opt/prebuilt/android/sdl2_mixer/. "$SCRATCH_ENGINE/build_ext/built_sdl_mixer/"
-mkdir -p "$SCRATCH_ENGINE/build_ext/fluidsynth-lite/src"
-cp -a /opt/prebuilt/android/fluidsynth-lite/lib/. "$SCRATCH_ENGINE/build_ext/fluidsynth-lite/src/"
-cp -a /opt/prebuilt/android/fluidsynth-lite/include/. "$SCRATCH_ENGINE/build_ext/fluidsynth-lite/include/"
-
-echo "engineDir=$SCRATCH_ENGINE" > "$ANDROID_DIR/engine.properties"
-
-echo "== Staging bundled assets (shaders, soundfont, get-assets text) =="
-ASSETS_DIR="$ANDROID_DIR/app/src/main/assets"
-rm -rf "$ASSETS_DIR"
-mkdir -p "$ASSETS_DIR/shaders" "$ASSETS_DIR/res"
-# GLES ports of engine/shaders/ (see android/gles-shaders/ and
-# android/engine-patches/04-android-opengl-es-render.patch) - not
-# engine/shaders/ itself, which is desktop-only GLSL.
-cp -a "$ANDROID_DIR/gles-shaders/." "$ASSETS_DIR/shaders/"
-cp "/opt/prebuilt/soundfont/default.sf2" "$ASSETS_DIR/res/soundfont.sf2"
-cp "$REPO_ROOT/res/assets/GET_ASSETS_QUEST.txt" "$ASSETS_DIR/GET_ASSETS_QUEST.txt"
-
-echo "== Staging prebuilt Android SDL2/SDL2_mixer/fluidsynth-lite/gl4es .so's into jniLibs =="
-JNI_LIBS_DIR="$ANDROID_DIR/app/src/main/jniLibs/arm64-v8a"
-rm -rf "$ANDROID_DIR/app/src/main/jniLibs"
-mkdir -p "$JNI_LIBS_DIR"
-find /opt/prebuilt/android/sdl2/lib /opt/prebuilt/android/sdl2_mixer/lib /opt/prebuilt/android/fluidsynth-lite/lib \
-    /opt/prebuilt/android/gl4es/lib \
-    -name '*.so' -exec cp -a {} "$JNI_LIBS_DIR/" \;
+echo "== Determining version (shared with 'make package', see build-image/version.sh) =="
+git config --global --add safe.directory "$REPO_ROOT" 2>/dev/null || true
+VERSION="$("$REPO_ROOT/build-image/version.sh")"
+# versionName (VERSION, above) can be anything, but Android's versionCode
+# must be a positive, monotonically-increasing integer - the commit count
+# is a simple, deterministic stand-in for that.
+VERSION_CODE="$(git -C "$REPO_ROOT" rev-list --count HEAD)"
+echo "Version: $VERSION (versionCode $VERSION_CODE)"
 
 echo "== Building the APK (gradlew assembleDebug) =="
 cd "$ANDROID_DIR"
-./gradlew --no-daemon assembleDebug
+./gradlew --no-daemon assembleDebug \
+    "-PquestshockVersionName=$VERSION" "-PquestshockVersionCode=$VERSION_CODE"
 
 APK="$ANDROID_DIR/app/build/outputs/apk/debug/app-debug.apk"
 [ -f "$APK" ] || { echo "BUILD FAIL: $APK not found after assembleDebug" >&2; exit 1; }
 
 mkdir -p "$REPO_ROOT/dist"
-cp "$APK" "$REPO_ROOT/dist/questshock-debug.apk"
+PKG_NAME="questshock-$VERSION-android-arm64.apk"
+cp "$APK" "$REPO_ROOT/dist/$PKG_NAME"
 
 echo "== Done =="
-echo "APK: $REPO_ROOT/dist/questshock-debug.apk"
+echo "APK: $REPO_ROOT/dist/$PKG_NAME"

build-image/prepare-android-project.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Prepares android/ to be built: a scratch, patched copy of engine/ (see
+# android/engine-patches/ - engine/ itself is never modified), the
+# Android SDL2/SDL2_mixer/fluidsynth-lite/gl4es/openxr prebuilts staged
+# into jniLibs, bundled assets, and android/engine.properties (engineDir/
+# prebuiltDir, read by android/app/build.gradle). Always run inside this
+# image (via ../run-image.sh, or directly if already inside it) - it
+# reads from /opt/prebuilt/android/*, which only exists there.
+#
+# Two modes:
+#   (no args)      - for build-apk.sh's own gradlew, invoked in this same
+#                     container - engine.properties points at this
+#                     container's own paths (e.g. /workspace/build/...).
+#   --host-paths   - for building android/ natively in Android Studio on
+#                     the HOST afterwards, instead of via build-apk.sh.
+#                     Needs HOST_REPO_ROOT (set by run-image.sh) to know
+#                     this container's bind-mounted repo root's path on
+#                     the host, since a plain container-internal path
+#                     like /workspace/... doesn't resolve there. Also
+#                     exports /opt/prebuilt/android (host-invisible,
+#                     image-only) to build/android-prebuilt so a host-side
+#                     CMake configure can actually find it.
+set -euo pipefail
+
+HOST_PATHS=0
+if [ "${1:-}" = "--host-paths" ]; then
+    HOST_PATHS=1
+fi
+
+REPO_ROOT="$(pwd)"
+ANDROID_DIR="$REPO_ROOT/android"
+SCRATCH_ENGINE="$REPO_ROOT/build/android-engine"
+PREBUILT_EXPORT_DIR="$REPO_ROOT/build/android-prebuilt"
+
+echo "== Preparing a scratch, patched copy of engine/ =="
+rm -rf "$SCRATCH_ENGINE"
+mkdir -p "$(dirname "$SCRATCH_ENGINE")"
+cp -a "$REPO_ROOT/engine" "$SCRATCH_ENGINE"
+for p in "$ANDROID_DIR"/engine-patches/*.patch; do
+    patch -p1 -d "$SCRATCH_ENGINE" < "$p"
+done
+
+echo "== Wiring up prebuilt Android SDL2_mixer/fluidsynth-lite (BUNDLED mode, like the desktop build) =="
+mkdir -p "$SCRATCH_ENGINE/build_ext/built_sdl_mixer" "$SCRATCH_ENGINE/build_ext/fluidsynth-lite"
+cp -a /opt/prebuilt/android/sdl2_mixer/. "$SCRATCH_ENGINE/build_ext/built_sdl_mixer/"
+mkdir -p "$SCRATCH_ENGINE/build_ext/fluidsynth-lite/src"
+cp -a /opt/prebuilt/android/fluidsynth-lite/lib/. "$SCRATCH_ENGINE/build_ext/fluidsynth-lite/src/"
+cp -a /opt/prebuilt/android/fluidsynth-lite/include/. "$SCRATCH_ENGINE/build_ext/fluidsynth-lite/include/"
+
+if [ "$HOST_PATHS" -eq 1 ]; then
+    : "${HOST_REPO_ROOT:?--host-paths needs HOST_REPO_ROOT set - run via ./run-image.sh, not directly}"
+    echo "== Exporting prebuilt Android SDL2/SDL2_mixer/fluidsynth-lite/gl4es for host-side use =="
+    rm -rf "$PREBUILT_EXPORT_DIR"
+    cp -a /opt/prebuilt/android "$PREBUILT_EXPORT_DIR"
+    ENGINE_DIR_PROP="$HOST_REPO_ROOT/build/android-engine"
+    PREBUILT_DIR_PROP="$HOST_REPO_ROOT/build/android-prebuilt"
+else
+    ENGINE_DIR_PROP="$SCRATCH_ENGINE"
+    PREBUILT_DIR_PROP="/opt/prebuilt/android"
+fi
+
+{
+    echo "engineDir=$ENGINE_DIR_PROP"
+    echo "prebuiltDir=$PREBUILT_DIR_PROP"
+} > "$ANDROID_DIR/engine.properties"
+
+echo "== Staging bundled assets (shaders, soundfont, get-assets text) =="
+ASSETS_DIR="$ANDROID_DIR/app/src/main/assets"
+rm -rf "$ASSETS_DIR"
+mkdir -p "$ASSETS_DIR/shaders" "$ASSETS_DIR/res"
+# GLES ports of engine/shaders/ (see android/gles-shaders/ and
+# android/engine-patches/04-android-opengl-es-render.patch) - not
+# engine/shaders/ itself, which is desktop-only GLSL.
+cp -a "$ANDROID_DIR/gles-shaders/." "$ASSETS_DIR/shaders/"
+cp "/opt/prebuilt/soundfont/default.sf2" "$ASSETS_DIR/res/soundfont.sf2"
+cp "$REPO_ROOT/res/assets/GET_ASSETS_QUEST.txt" "$ASSETS_DIR/GET_ASSETS_QUEST.txt"
+
+echo "== Staging prebuilt Android SDL2/SDL2_mixer/fluidsynth-lite/gl4es/openxr .so's into jniLibs =="
+JNI_LIBS_DIR="$ANDROID_DIR/app/src/main/jniLibs/arm64-v8a"
+rm -rf "$ANDROID_DIR/app/src/main/jniLibs"
+mkdir -p "$JNI_LIBS_DIR"
+find /opt/prebuilt/android/sdl2/lib /opt/prebuilt/android/sdl2_mixer/lib /opt/prebuilt/android/fluidsynth-lite/lib \
+    /opt/prebuilt/android/gl4es/lib /opt/prebuilt/android/openxr/lib \
+    -name '*.so' -exec cp -a {} "$JNI_LIBS_DIR/" \;
+
+echo "== Done =="
+echo "engineDir=$ENGINE_DIR_PROP"
+echo "prebuiltDir=$PREBUILT_DIR_PROP"
+if [ "$HOST_PATHS" -eq 1 ]; then
+    echo "android/ is ready to open and build natively in Android Studio on the host."
+fi

build-image/version.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Prints the release version used to name both dist/shockolate-*.tar.gz
+# (see `make package`) and dist/questshock-*.apk (see build-apk.sh), so
+# the two are always versioned identically.
+#
+# Defaults to the current git tag (vX.Y.Z, prefix stripped) if HEAD is
+# exactly on one matching that pattern; otherwise a 0.0.0-dev+<sha>
+# placeholder (with a warning on stderr) - push a vX.Y.Z tag to drive a
+# real release version. Override either way with VERSION=1.2.3 in the
+# environment.
+set -euo pipefail
+
+V="${VERSION:-}"
+if [ -z "$V" ]; then
+    if TAG=$(git describe --tags --exact-match --match 'v[0-9]*.[0-9]*.[0-9]*' 2>/dev/null); then
+        V="${TAG#v}"
+    else
+        V="0.0.0-dev+$(git rev-parse --short HEAD)"
+        echo "WARNING: HEAD is not on a vX.Y.Z tag - building placeholder version $V (push a tag to drive a real release version)" >&2
+    fi
+fi
+
+case "$V" in
+    [0-9]*.[0-9]*.[0-9]*) ;;
+    *) echo "PREFLIGHT FAIL: VERSION '$V' is not a semantic version (expected X.Y.Z, optionally with a -pre+meta suffix)" >&2; exit 1;;
+esac
+
+echo "$V"

res/assets/GET_ASSETS.txt

@@ -1,16 +1,14 @@
 This package does not include System Shock's game data - it's
 copyrighted, proprietary content that can't be redistributed. To play,
-you need a copy of System Shock: Enhanced Edition (e.g. from gog.com).
+you need to own a copy of System Shock: Enhanced Edition (e.g. from
+gog.com), installed (on Windows, or via Wine/Proton on Linux).
 
-From your Enhanced Edition install, you need its classic-game data and
-sound files - the res/pc/hd/data and res/pc/cdrom/data trees merged
-together (res/pc/hd's copies win the couple of filenames present in
-both: intro.res, objprop.dat), and the res/pc/hd/sound tree, packed
-inside the install's sshock.kpf (a zip file).
-
-Copy that merged data into place, alongside this file:
-  res/data/   <- res/pc/hd/data + res/pc/cdrom/data, merged
-  res/sound/  <- res/pc/hd/sound
+Copy its res/data/ and res/sound/ folders directly into place here,
+alongside this file:
+  res/data/
+  res/sound/
+They already contain everything needed, in the right layout - no
+merging or extraction required.
 
 Once res/data/ and res/sound/ exist next to this file, run ./run.sh from
 the root of this package to play.

res/assets/GET_ASSETS_QUEST.txt

@@ -1,17 +1,14 @@
 This app does not include System Shock's game data - it's copyrighted,
-proprietary content that can't be redistributed. To play, you need a
-copy of System Shock: Enhanced Edition (e.g. from gog.com).
-
-From your Enhanced Edition install, you need its classic-game data and
-sound files - the res/pc/hd/data and res/pc/cdrom/data trees merged
-together (res/pc/hd's copies win the couple of filenames present in
-both: intro.res, objprop.dat), and the res/pc/hd/sound tree, packed
-inside the install's sshock.kpf (a zip file).
+proprietary content that can't be redistributed. To play, you need to
+own a copy of System Shock: Enhanced Edition (e.g. from gog.com),
+installed (on Windows, or via Wine/Proton on Linux).
 
 Using SideQuest (or any MTP file browser) with your Quest connected,
-copy that merged data into:
+copy its res/data/ and res/sound/ folders directly into:
   /sdcard/questshock/res/data/
   /sdcard/questshock/res/sound/
+They already contain everything needed, in the right layout - no
+merging or extraction required.
 
 (shaders/ and this app's default soundfont are already here, extracted
 automatically on first launch - only res/data/ and res/sound/ are

run-image.sh

@@ -39,11 +39,17 @@ docker image inspect "$IMAGE" >/dev/null 2>&1 \
 TTY_FLAGS="-i"
 [ -t 1 ] && TTY_FLAGS="-it"
 
+# HOST_REPO_ROOT: lets scripts running in the container (e.g.
+# build-image/prepare-android-project.sh --host-paths) write paths that
+# resolve on the HOST filesystem instead of this container's own
+# /workspace - needed so a gradlew/Android Studio running natively on the
+# host afterwards can find them.
 # shellcheck disable=SC2086
 docker run --rm $TTY_FLAGS \
     -v "$ROOT:/workspace" \
     -e HOST_UID="$(id -u)" \
     -e HOST_GID="$(id -g)" \
+    -e HOST_REPO_ROOT="$ROOT" \
     "$IMAGE" \
     "$@"