- AndroidManifest.xml: add android:screenOrientation="landscape" and a

<layout> defaultWidth/defaultHeight/minWidth/minHeight/gravity hint -
  Quest's Home shell otherwise defaults a freshly-launched 2D panel to a
  portrait shape, cropping the game's 4:3 640x480 content down to a
  sliver.
- The actual root cause of the remaining crop (game rendering into one
  corner of an otherwise correctly-sized panel), found via on-device
  logcat and the new diagnostics below rather than guesswork:
  ChangeScreenSize() (engine/src/MacSrc/ShockBitmap.c) calls
  SDL_SetWindowSize() whenever the game sets its video mode. That's a
  desktop-only operation in effect - Android has no SetWindowSize driver
  hook, so SDL's generic layer instead overwrites its own cached window
  size to the game's internal resolution (640x480) and synthesizes a
  resize event from that, desyncing SDL's notion of the window size from
  the real, unchanged Android surface (e.g. 1600x1200). Both SDL's own
  renderer viewport and the engine's custom GL viewport then scale
  against that corrupted cached size. 10-android-no-window-resize.patch
  skips the desktop-only SDL_SetWindowFullscreen/SetWindowSize/
  SetWindowPosition calls on Android, keeping the legitimate
  SDL_RenderSetLogicalSize/offscreen-bitmap setup.
- 06-android-resize-event.patch: also react to SDL_WINDOWEVENT_RESIZED
  in the engine's event loop, not just SIZE_CHANGED - Android's SDL video
  backend never sends SIZE_CHANGED for surface-driven resizes, only
  RESIZED, an independent gap worth closing regardless of the bug above.
- 08/09-android-logcat-*.patch: route the engine's existing log.c output
  (previously plain fprintf(stderr,...), never actually captured by
  logcat on this build) through __android_log_vprint instead, so every
  existing INFO/DEBUG/WARN/ERROR call site becomes visible for on-device
  debugging. This is what made the diagnostic below (and everything
  since) observable at all.
- 07-android-size-diagnostics.patch: one-time startup log comparing
  SDL_GetWindowSize/SDL_GL_GetDrawableSize/SDL_GetRendererOutputSize -
  the evidence that actually pinned down the SDL_SetWindowSize bug above.
- QuestShockActivity.java: add a diagnostic onSizeChanged() log on
  GameSurface, used to rule out a later Android-side panel relayout as
  the cause before finding the real one.

.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

@@ -22,9 +22,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 +64,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 +88,11 @@ 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` - 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.
 
 1. Install the APK with [SideQuest](https://sidequestvr.com/) (or `adb
    install`).
@@ -99,6 +107,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
+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

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,20 +101,28 @@ 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.
                 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}", \
+                    "-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", \
+                    "-DCMAKE_SHARED_LINKER_FLAGS=-Wl,-z,max-page-size=16384", \
                     "-DANDROID_EXTRA_SOURCES=${projectDir}/src/main/cpp/questshock_native.c"
                 abiFilters 'arm64-v8a'
             }

android/app/src/main/AndroidManifest.xml

@@ -34,6 +34,7 @@
             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>
@@ -43,6 +44,19 @@
             <intent-filter>
                 <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
             </intent-filter>
+            <!-- Without this, Quest's Home shell picks its own default 2D
+                 panel shape for this activity - a tall portrait rectangle,
+                 which crops a 4:3 landscape game like System Shock's classic
+                 640x480 down to a sliver. defaultWidth/defaultHeight (the
+                 standard Android multi-window sizing hint, which Quest's
+                 panel system honors for 2D apps) requests a properly
+                 landscape, 4:3-ish panel instead; minWidth/minHeight keep it
+                 from being resized below the game's native resolution. -->
+            <layout android:defaultWidth="1280dp"
+                android:defaultHeight="960dp"
+                android:minWidth="640dp"
+                android:minHeight="480dp"
+                android:gravity="center" />
         </activity>
     </application>
 

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);
+ 

build-image/Dockerfile

@@ -46,6 +46,13 @@ 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.
@@ -77,12 +84,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 +189,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 +215,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 +231,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 +246,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,9 +264,11 @@ 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
 

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 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 .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 "== 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" \
     "$@"