Add basic Android APK integration

.github/workflows/build.yml

@@ -105,6 +105,50 @@ jobs:
           name: opengothic_${{ needs.setup.outputs.semver }}_linux_x64.deb
           path: opengothic_${{ needs.setup.outputs.semver }}_linux_x64.deb
 
+  android-arm64:
+    needs: setup
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: '17'
+
+      - uses: gradle/actions/setup-gradle@v5
+        with:
+          gradle-version: '8.9'
+
+      - uses: ./.github/actions/setup-vulkan
+        with:
+          os: Linux
+          vk-sdk: ${{ env.VK_SDK }}
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y glslang-tools ninja-build
+          "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" "platforms;android-35" "build-tools;35.0.0" "ndk;27.0.12077973" "cmake;3.22.1"
+
+      - name: Generate build version
+        run: |
+          echo '#pragma once' > game/build.h
+          echo "static const char* appBuild = \"${{ needs.setup.outputs.version }}\";" >> game/build.h
+
+      - name: Configure
+        run: |
+          "$ANDROID_HOME/cmake/3.22.1/bin/cmake" -S . -B build/android -G Ninja \
+            -DCMAKE_TOOLCHAIN_FILE="$ANDROID_HOME/ndk/27.0.12077973/build/cmake/android.toolchain.cmake" \
+            -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-24 \
+            -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }}
+
+      - name: Build APK
+        run: |
+          "$ANDROID_HOME/cmake/3.22.1/bin/cmake" --build build/android --target OpenGothic-apk
+
   windows:
     needs: setup
     runs-on: windows-latest

CMakeLists.txt

@@ -12,7 +12,11 @@ set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 set(CMAKE_SKIP_RPATH ON)
 
 add_library(${PROJECT_NAME} STATIC)
-add_executable(Gothic2Notr)
+if(ANDROID)
+  add_library(Gothic2Notr SHARED)
+else()
+  add_executable(Gothic2Notr)
+endif()
 add_executable(Spacer)
 
 if(MSVC)
@@ -92,6 +96,8 @@ endif()
 
 if(WIN32)
   target_link_libraries(${PROJECT_NAME} shlwapi DbgHelp)
+elseif(ANDROID)
+  target_link_libraries(${PROJECT_NAME} dl)
 elseif(UNIX)
   target_link_libraries(${PROJECT_NAME} -lpthread -ldl)
 endif()
@@ -178,7 +184,7 @@ if(WIN32)
 endif()
 
 # in debug mode, enable sanitizers
-if(${CMAKE_BUILD_TYPE} MATCHES "Debug")
+if(${CMAKE_BUILD_TYPE} MATCHES "Debug" AND NOT ANDROID)
   add_compile_options(-fsanitize=address)
   add_compile_options(-fsanitize=leak)
   add_link_options   (-fsanitize=address)
@@ -197,13 +203,23 @@ if(IOS)
     XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer")
 endif()
 
-target_sources(Gothic2Notr PRIVATE game/main.cpp icon.rc)
+target_sources(Gothic2Notr PRIVATE game/main.cpp)
+if(WIN32)
+  target_sources(Gothic2Notr PRIVATE icon.rc)
+endif()
 target_link_libraries(Gothic2Notr PRIVATE OpenGothic)
 
 # editor
 target_sources(Spacer PRIVATE ${SPACER_SOURCES} spacer/main.cpp)
 target_include_directories(Spacer PRIVATE "spacer")
 target_link_libraries(Spacer PRIVATE OpenGothic SpacerAssets)
 
+if(ANDROID)
+  add_android_apk(OpenGothic-apk
+    PACKAGE_NAME org.opengothic.app
+    CODE Gothic2Notr
+    MANIFEST android/AndroidManifest.xml)
+endif()
+
 # installation
 install(TARGETS Gothic2Notr Spacer DESTINATION bin)

README.md

@@ -91,6 +91,10 @@ There are ongoing efforts to support parts of it to make at least some popular m
 - Ninja
 
 ## Build Instructions
+### Android
+
+The basic ARM64 APK build and ADB game-file setup are documented in [android/README.md](android/README.md).
+
 ### Linux
 Install dependencies:
 * Ubuntu 20.04/22.04 and their derived distros

android/AndroidManifest.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-feature android:name="android.hardware.vulkan.level" android:version="0" android:required="true" />
+    <uses-feature android:name="android.hardware.vulkan.version" android:version="0x00401000" android:required="true" />
+    <application android:label="OpenGothic" android:hasCode="false" android:allowBackup="false"
+        android:theme="@android:style/Theme.Material.NoActionBar.Fullscreen">
+        <activity android:name="android.app.NativeActivity" android:exported="true"
+            android:screenOrientation="landscape"
+            android:configChanges="keyboard|keyboardHidden|navigation|orientation|screenSize|screenLayout|smallestScreenSize|density|uiMode">
+            <meta-data android:name="android.app.lib_name" android:value="Gothic2Notr" />
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+</manifest>

android/README.md

@@ -0,0 +1,32 @@
+# Android
+
+An ARM64 NativeActivity APK using Tempest's Android backend and generated Gradle project. This is the basic platform integration; touch controls, controller input and game-file importing are not included yet. Android window destruction closes the application, including when backgrounding or locking destroys its surface.
+
+## Build
+
+Install JDK 17, Gradle 8.9, CMake 3.22.1 or newer, Ninja and the Android SDK with SDK 35, build-tools 35.0.0, NDK 27.0.12077973 and SDK CMake 3.22.1. Set `JAVA_HOME`, `ANDROID_HOME` and `VULKAN_SDK`. Put Gradle, Ninja and the host Vulkan SDK's `glslangValidator` on `PATH`. Vulkan headers come from the host SDK; Android links the NDK's Vulkan loader.
+
+Clone with `git clone --recursive https://github.com/Try/OpenGothic.git`, or run `git submodule update --init --recursive` in an existing checkout. Replace `/path/to/ndk` below with the NDK installation directory. The same commands work in PowerShell and a Linux shell.
+
+```sh
+cmake -S . -B build/android -G Ninja -DCMAKE_TOOLCHAIN_FILE=/path/to/ndk/build/cmake/android.toolchain.cmake -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-24 -DCMAKE_BUILD_TYPE=Release
+cmake --build build/android --target OpenGothic-apk
+```
+
+APK: `build/android/OpenGothic-apk/build/outputs/apk/release/OpenGothic-apk-release.apk`. Use `-DCMAKE_BUILD_TYPE=Debug` for a debuggable APK under `outputs/apk/debug/OpenGothic-apk-debug.apk`. Desktop builds do not invoke the APK helper or require Android tools.
+
+## Install and game files
+
+Use a legally owned Gothic II: Night of the Raven installation. No game files are included in the APK. Copy the installation root, not only its `Data` directory: `Data`, `_work` and `System` must be directly inside `Gothic2`.
+
+```sh
+adb install -r build/android/OpenGothic-apk/build/outputs/apk/release/OpenGothic-apk-release.apk
+adb shell mkdir -p /sdcard/Android/data/org.opengothic.app/files/Gothic2
+adb push "/path/to/Gothic II/." /sdcard/Android/data/org.opengothic.app/files/Gothic2/
+adb shell am start -n org.opengothic.app/android.app.NativeActivity
+adb logcat -s app AndroidRuntime DEBUG
+```
+
+Game files use app-specific external storage, without storage permissions. Logs, saves and writable settings use the app's internal files directory. Uninstalling removes both directories. Ray tracing and mesh shading are disabled for this initial Android build.
+
+With a debug APK, read the file log using `adb shell run-as org.opengothic.app cat files/log.txt`.

common/commandline.h

@@ -64,7 +64,7 @@ class CommandLine {
     Benchmark           isBenchmark  = Benchmark::None;
     bool                isWindow     = false;
     bool                isDebug      = false;
-#if defined(__OSX__)
+#if defined(__OSX__) || defined(__ANDROID__)
     bool                isRQuery     = false;
     bool                isMeshSh     = false;
 #else

common/utils/crashlog.cpp

@@ -10,11 +10,17 @@
 #include <fstream>
 #include <cstring>
 
+#if defined(__ANDROID__)
+#include <cstdint>
+#include <dlfcn.h>  // dladdr
+#include <unwind.h> // _Unwind_Backtrace
+#endif
+
 #if defined(__cpp_lib_stacktrace)
 #include <stacktrace>
 #endif
 
-#if defined(__LINUX__) || defined(__APPLE__)
+#if (defined(__LINUX__) && !defined(__ANDROID__)) || defined(__APPLE__)
 #include <execinfo.h> // backtrace
 #include <dlfcn.h>    // dladdr
 #include <cxxabi.h>   // __cxa_demangle
@@ -136,6 +142,8 @@ void CrashLog::dumpStack(const char *sig, const char *extGpuLog) {
 #elif defined(__WINDOWS__)
   traceback.collect(0);
   traceback.log(db, std::cout);
+#elif defined(__ANDROID__)
+  tracebackAndroid(std::cout);
 #elif defined(__LINUX__) || defined(__APPLE__)
   tracebackLinux(std::cout);
 #endif
@@ -150,6 +158,8 @@ void CrashLog::dumpStack(const char *sig, const char *extGpuLog) {
   tracebackStd(fout);
 #elif defined(__WINDOWS__)
   traceback.log(db, fout);
+#elif defined(__ANDROID__)
+  tracebackAndroid(fout);
 #elif defined(__LINUX__) || defined(__APPLE__)
   tracebackLinux(fout);
 #endif
@@ -168,8 +178,38 @@ void CrashLog::tracebackStd(std::ostream &out) {
 #endif
   }
 
+void CrashLog::tracebackAndroid(std::ostream &out) {
+#if defined(__ANDROID__)
+  struct Backtrace {
+    void*  frames[64] = {};
+    size_t count = 0;
+    } trace;
+  _Unwind_Backtrace([](_Unwind_Context* context, void* arg) {
+    auto& trace = *static_cast<Backtrace*>(arg);
+    const uintptr_t pc = _Unwind_GetIP(context);
+    if(pc!=0)
+      trace.frames[trace.count++] = reinterpret_cast<void*>(pc);
+    return trace.count==64 ? _URC_END_OF_STACK : _URC_NO_REASON;
+    }, &trace);
+
+  for(size_t i=0; i<trace.count; ++i) {
+    Dl_info info = {};
+    out << "#" << i+1 << ": ";
+    if(dladdr(trace.frames[i], &info)) {
+      const uintptr_t offset = reinterpret_cast<uintptr_t>(trace.frames[i])-reinterpret_cast<uintptr_t>(info.dli_fbase);
+      out << (info.dli_sname ? info.dli_sname : "?") << " - " << (info.dli_fname ? info.dli_fname : "?");
+      out << " + 0x" << std::hex << offset << std::dec;
+      }
+    else {
+      out << trace.frames[i];
+      }
+    out << std::endl;
+    }
+#endif
+  }
+
 void CrashLog::tracebackLinux(std::ostream &out) {
-#if defined(__LINUX__) || defined(__APPLE__)
+#if (defined(__LINUX__) && !defined(__ANDROID__)) || defined(__APPLE__)
   // inspired by https://gist.github.com/fmela/591333/36faca4c2f68f7483cd0d3a357e8a8dd5f807edf (BSD)
   void *callstack[64] = {};
   char **symbols = nullptr;

common/utils/crashlog.h

@@ -11,6 +11,7 @@ class CrashLog final {
 
   private:
     static void tracebackStd(std::ostream& out);
+    static void tracebackAndroid(std::ostream &out);
     static void tracebackLinux(std::ostream &out);
     static void tracebackGpu(std::ostream &out, const char* extGpuLog);
     static void writeSysInfo(std::ostream& fout);

common/utils/installdetect.cpp

@@ -2,6 +2,10 @@
 
 #include <Tempest/Platform>
 
+#ifdef __ANDROID__
+#include <Tempest/AndroidApi>
+#endif
+
 #ifdef __WINDOWS__
 #include "windows.h"
 #include "shlobj.h"
@@ -31,11 +35,26 @@ std::u16string InstallDetect::detectG2() {
   if(FileUtil::exists(appDir))
     return appDir;
   return u"";
+#elif defined(__ANDROID__)
+  auto path = Tempest::AndroidApi::externalDataPath();
+  if(path.empty())
+    return u"";
+  path /= "Gothic2";
+  std::filesystem::create_directories(path);
+  return path.u16string();
 #else
   return u"";
 #endif
   }
 
+#ifdef __ANDROID__
+std::filesystem::path InstallDetect::androidInternalDataPath() {
+  auto path = Tempest::AndroidApi::internalDataPath();
+  std::filesystem::create_directories(path);
+  return path;
+  }
+#endif
+
 std::u16string InstallDetect::detectG2(std::u16string pfiles) {
   if(pfiles.empty())
     return u"";

common/utils/installdetect.h

@@ -3,13 +3,19 @@
 #include <Tempest/Platform>
 #include <string>
 
+#ifdef __ANDROID__
+#include <filesystem>
+#endif
+
 class InstallDetect final {
   public:
     InstallDetect();
 
     std::u16string detectG2();
 #if defined(__OSX__) || defined(__IOS__)
     static std::u16string applicationSupportDirectory();
+#elif defined(__ANDROID__)
+    static std::filesystem::path androidInternalDataPath();
 #endif
 
   private:

game/main.cpp

@@ -14,8 +14,9 @@
 #include <Tempest/MetalApi>
 #endif
 
-#if defined(__IOS__)
+#if defined(__IOS__) || defined(__ANDROID__)
 #include "utils/installdetect.h"
+#include <filesystem>
 #endif
 
 #include "utils/crashlog.h"
@@ -68,7 +69,9 @@ std::unique_ptr<Tempest::AbstractGraphicsApi> mkApi(const CommandLine& g) {
   }
 
 int main(int argc,const char** argv) {
-#if defined(__IOS__)
+#if defined(__ANDROID__)
+  std::filesystem::current_path(InstallDetect::androidInternalDataPath());
+#elif defined(__IOS__)
   {
     auto appdir = InstallDetect::applicationSupportDirectory();
     std::filesystem::current_path(appdir);

shader/CMakeLists.txt

@@ -20,7 +20,7 @@ file(GLOB_RECURSE GLSL_SOURCES
   "${CMAKE_SOURCE_DIR}/shader/*.glsl")
 
 # GLSL to SPIRV compiler
-find_program(GLSLANGVALIDATOR glslangValidator "/opt/homebrew/bin")
+find_program(GLSLANGVALIDATOR glslangValidator "/opt/homebrew/bin" NO_CMAKE_FIND_ROOT_PATH)
 if(NOT GLSLANGVALIDATOR)
   message(FATAL_ERROR "glslangValidator required")
 endif()