feature/android export

docs/en/setup/build.md

@@ -218,6 +218,59 @@ python3 -m http.server 8000
 After starting the server, access `http://localhost:8000` in your browser to verify it works.
 (Since this plugin operates with `nothread` on the Web, it can be launched with a simple HTTP server without requiring special CORS headers.)
 
+### Android Platform Export and Testing
+
+Android export templates are template APKs packaged by the engine's Gradle project. Unlike the desktop platforms, the template build therefore has three stages (runtime → per-ABI engine libraries → Gradle packaging) before `install-template.sh`.
+
+**Prerequisites**
+- Android SDK and NDK, with `cargo-ndk` and the Rust Android targets installed (`aarch64-linux-android`, `armv7-linux-androideabi`, `x86_64-linux-android`).
+- Export the SDK/NDK paths so the build scripts can find them (adjust to your environment):
+  ```bash
+  export ANDROID_HOME="$HOME/Library/Android/sdk"
+  export ANDROID_NDK_ROOT="$ANDROID_HOME/ndk/<ndk-version>"
+  ```
+- In the Godot editor settings, configure the Android SDK path and a debug keystore (`export/android/android_sdk_path`, `export/android/debug_keystore`, `export/android/debug_keystore_pass`).
+
+1. **Build the runtime and templates**
+   Build the Rust runtime once, then build the engine shared library for each ABI/target, and package them into the template APKs with Gradle.
+   ```bash
+   # Rust runtime (a single release build is reused by both template targets)
+   ./scripts/build-runtime.sh platform=android build=release
+   # Alternatively, fetch the prebuilt runtime for all platforms instead of building it:
+   #   ./scripts/download-sdk.sh
+
+   # Engine .so per ABI. arch: arm64 / arm32 / x86_64, target: template_release / template_debug
+   ./scripts/build.sh platform=android arch=arm64  target=template_release
+   ./scripts/build.sh platform=android arch=arm32  target=template_release
+   ./scripts/build.sh platform=android arch=x86_64 target=template_release
+   ./scripts/build.sh platform=android arch=arm64  target=template_debug   # add other ABIs as needed
+
+   # Package into android_release.apk / android_debug.apk / android_source.zip
+   (cd godot/platform/android/java && ./gradlew generateGodotTemplates)
+   ```
+   > The `arch` values follow Godot's names (`arm64`, `arm32`, `x86_64`, `x86_32`), while the runtime libraries are placed under the matching Android ABI directories (`arm64-v8a`, `armeabi-v7a`, `x86_64`, `x86`). You only need the ABI of the device/emulator you intend to run on.
+
+2. **Install templates**
+   ```bash
+   ./scripts/install-template.sh android
+   ```
+
+3. **Run export from CLI**
+   ```bash
+   mkdir -p bin_export
+   ./godot/Godot.app/Contents/MacOS/Godot --path ./examples/dev_module/ --headless --export-debug "Android" "$(pwd)/bin_export/dev_module_debug.apk"
+   ```
+   > **Note:** Android export requires ETC2/ASTC texture import to be enabled. Otherwise the export aborts with a configuration error whose message is empty. Set `rendering/textures/vram_compression/import_etc2_astc=true` in the project settings (already enabled in `examples/dev_module`).
+
+4. **Install and run on a device / emulator**
+   ```bash
+   adb install -r bin_export/dev_module_debug.apk
+   adb shell am start -n com.crimw.devmodule/com.godot.game.GodotAppLauncher
+   adb logcat -s godot        # check the engine log / errors
+   adb exec-out screencap -p > screen.png   # capture the rendered frame
+   ```
+   The `dev_module` sample plays the `Knight_arrow` animation on `SpriteStudioPlayer2D` with autoplay, so a successful run renders the character on screen.
+
 ### GDExtension Export and Testing
 
 For GDExtensions (e.g., `dev_gdextension`), **rebuilding the engine itself or installing custom templates is unnecessary**. You can export as-is using the standard Godot editor and official export templates distributed by Godot.
@@ -247,6 +300,20 @@ For GDExtensions (e.g., `dev_gdextension`), **rebuilding the engine itself or in
    ```
    > During export, Godot will automatically bundle the plugin files (`.so`, `.framework`, `.dll`, etc.) into the exported artifacts.
 
+   **Android note:** Android needs a few extra steps beyond the desktop flow above:
+   - Build the Android plugin libraries with `./scripts/release-gdextension-android.sh` (requires the Android SDK/NDK, `cargo-ndk`, the Rust Android targets, and the Android runtime — build it with `./scripts/build-runtime.sh platform=android build=release` or fetch the prebuilt one with `./scripts/download-sdk.sh`). The `arch` values are Godot's names (`arm64`, `arm32`, `x86_64`), while the runtime is linked from the matching Android ABI directory (`arm64-v8a`, `armeabi-v7a`, `x86_64`).
+   - Also build the **host** plugin (e.g. `./scripts/release-gdextension-macos.sh`). During export the `.ssab` resources are loaded on the host machine, so without a working host library the export drops them with a `Failed loading resource` error and the resulting APK ships without animation data.
+   - Install the official **Android** export templates for the official Godot version you are using (via *Manage Export Templates* in the editor, or by placing the `.tpz` contents under `.../export_templates/<version>/`).
+   - Enable `rendering/textures/vram_compression/import_etc2_astc=true` in the project settings (already set in `examples/dev_gdextension`); otherwise the export aborts with a configuration error whose message is empty.
+   - Then export and run on a device / emulator:
+     ```bash
+     mkdir -p bin_export
+     godot --path ./examples/dev_gdextension/ --headless --export-debug "Android" "$(pwd)/bin_export/dev_gdextension_debug.apk"
+     adb install -r bin_export/dev_gdextension_debug.apk
+     adb shell am start -n com.crimw.devgdext/com.godot.game.GodotAppLauncher
+     adb logcat -s godot
+     ```
+
 ## Debugging the GDExtension
 
 You can debug the C++ code for GDExtensions using almost the same steps as a custom module. The only difference is that the launch program is the "official Godot editor".

docs/ja/setup/build.md

@@ -213,6 +213,59 @@ python3 -m http.server 8000
 サーバー起動後、ブラウザで `http://localhost:8000` にアクセスすると動作確認ができます。
 （本プラグインは Web においては `nothread` での動作となるため、特殊なCORSヘッダーなしの単純なHTTPサーバーで起動可能です）
 
+### Androidプラットフォームのエクスポートと動作確認
+
+Android のエクスポートテンプレートは、エンジンの Gradle プロジェクトでパッケージされるテンプレートAPKです。そのためデスクトップ系と異なり、`install-template.sh` の前にテンプレートのビルドが3段階（ランタイム → ABIごとのエンジンライブラリ → Gradleパッケージ）になります。
+
+**事前準備**
+- Android SDK と NDK、`cargo-ndk`、および Rust の Android ターゲット（`aarch64-linux-android`, `armv7-linux-androideabi`, `x86_64-linux-android`）をインストールしておきます。
+- ビルドスクリプトが参照できるよう、SDK/NDK のパスを環境変数に設定します（環境に合わせて調整してください）:
+  ```bash
+  export ANDROID_HOME="$HOME/Library/Android/sdk"
+  export ANDROID_NDK_ROOT="$ANDROID_HOME/ndk/<ndk-version>"
+  ```
+- Godot のエディタ設定で、Android SDK パスとデバッグ用キーストアを設定します（`export/android/android_sdk_path`, `export/android/debug_keystore`, `export/android/debug_keystore_pass`）。
+
+1. **ランタイムとテンプレートのビルド**
+   まず Rust ランタイムを一度ビルドし、次に ABI／ターゲットごとにエンジンの共有ライブラリをビルドして、Gradle でテンプレートAPKにパッケージします。
+   ```bash
+   # Rust ランタイム（1回のreleaseビルドを両テンプレートで共用します）
+   ./scripts/build-runtime.sh platform=android build=release
+   # ビルドの代わりに、全プラットフォームのプリビルドランタイムを取得することもできます:
+   #   ./scripts/download-sdk.sh
+
+   # ABIごとのエンジン .so。arch: arm64 / arm32 / x86_64, target: template_release / template_debug
+   ./scripts/build.sh platform=android arch=arm64  target=template_release
+   ./scripts/build.sh platform=android arch=arm32  target=template_release
+   ./scripts/build.sh platform=android arch=x86_64 target=template_release
+   ./scripts/build.sh platform=android arch=arm64  target=template_debug   # 必要に応じて他のABIも
+
+   # android_release.apk / android_debug.apk / android_source.zip としてパッケージ
+   (cd godot/platform/android/java && ./gradlew generateGodotTemplates)
+   ```
+   > `arch` は Godot の名称（`arm64`, `arm32`, `x86_64`, `x86_32`）で指定しますが、ランタイムライブラリは対応する Android ABI ディレクトリ（`arm64-v8a`, `armeabi-v7a`, `x86_64`, `x86`）に配置されます。実行する端末／エミュレータの ABI のみビルドすれば十分です。
+
+2. **テンプレートのインストール**
+   ```bash
+   ./scripts/install-template.sh android
+   ```
+
+3. **CLIからのエクスポート実行**
+   ```bash
+   mkdir -p bin_export
+   ./godot/Godot.app/Contents/MacOS/Godot --path ./examples/dev_module/ --headless --export-debug "Android" "$(pwd)/bin_export/dev_module_debug.apk"
+   ```
+   > **Note:** Android のエクスポートには ETC2/ASTC テクスチャインポートの有効化が必要です。無効のままだとメッセージが空の設定エラーでエクスポートが中断します。プロジェクト設定に `rendering/textures/vram_compression/import_etc2_astc=true` を設定してください（`examples/dev_module` では設定済みです）。
+
+4. **端末／エミュレータへのインストールと実行**
+   ```bash
+   adb install -r bin_export/dev_module_debug.apk
+   adb shell am start -n com.crimw.devmodule/com.godot.game.GodotAppLauncher
+   adb logcat -s godot        # エンジンのログ／エラー確認
+   adb exec-out screencap -p > screen.png   # 描画結果のキャプチャ
+   ```
+   `dev_module` サンプルは `SpriteStudioPlayer2D` で `Knight_arrow` アニメーションを autoplay 再生するため、正常に動作すればキャラクターが画面に描画されます。
+
 ### GDExtension のエクスポートと動作確認
 
 GDExtension（例: `dev_gdextension`）の場合、**エンジン本体の再ビルドやカスタムテンプレートのインストールは不要**です。Godot公式が配布している標準のGodotエディタとエクスポートテンプレートを使用して、そのままエクスポートが可能です。
@@ -242,6 +295,20 @@ GDExtension（例: `dev_gdextension`）の場合、**エンジン本体の再ビ
    ```
    > 実行時に `.so`, `.framework`, `.dll` などのプラグインファイルは Godot が自動的にエクスポート成果物の中に同梱してくれます。
 
+   **Android の注意点:** Android では上記のデスクトップ手順に加えて、いくつか追加のステップが必要です。
+   - Android 用プラグインライブラリを `./scripts/release-gdextension-android.sh` でビルドします（Android SDK/NDK、`cargo-ndk`、Rust の Android ターゲット、および Android ランタイムが必要。ランタイムは `./scripts/build-runtime.sh platform=android build=release` でビルドするか、`./scripts/download-sdk.sh` でプリビルドを取得します）。`arch` は Godot の名称（`arm64`, `arm32`, `x86_64`）で指定しますが、ランタイムは対応する Android ABI ディレクトリ（`arm64-v8a`, `armeabi-v7a`, `x86_64`）からリンクされます。
+   - **ホスト用**プラグイン（例: `./scripts/release-gdextension-macos.sh`）もビルドしてください。エクスポート時の `.ssab` リソースの読み込みはホストマシン上で行われるため、動作するホストライブラリが無いと `Failed loading resource` エラーで `.ssab` が除外され、生成された APK にアニメーションデータが入りません。
+   - 使用する公式 Godot のバージョンに対応した **Android** のエクスポートテンプレートを導入します（エディタの *エクスポートテンプレートの管理* から、または `.tpz` の中身を `.../export_templates/<version>/` に配置）。
+   - プロジェクト設定で `rendering/textures/vram_compression/import_etc2_astc=true` を有効にします（`examples/dev_gdextension` では設定済み）。無効のままだとメッセージが空の設定エラーでエクスポートが中断します。
+   - あとはエクスポートして端末／エミュレータで実行します。
+     ```bash
+     mkdir -p bin_export
+     godot --path ./examples/dev_gdextension/ --headless --export-debug "Android" "$(pwd)/bin_export/dev_gdextension_debug.apk"
+     adb install -r bin_export/dev_gdextension_debug.apk
+     adb shell am start -n com.crimw.devgdext/com.godot.game.GodotAppLauncher
+     adb logcat -s godot
+     ```
+
 ## GDExtension のデバッグ方法
 
 GDExtension の場合も、カスタムモジュールとほぼ同じ手順でC++コードをデバッグできます。違いは起動するプログラムが「公式のGodotエディタ」になる点のみです。

examples/dev_gdextension/project.godot

@@ -28,3 +28,4 @@ config/icon="res://icon.svg"
 rendering_device/driver.windows="d3d12"
 renderer/rendering_method="gl_compatibility"
 renderer/rendering_method.mobile="gl_compatibility"
+textures/vram_compression/import_etc2_astc=true

examples/dev_module/project.godot

@@ -18,3 +18,7 @@ config/name="dev_module"
 run/main_scene="res://node_2d.tscn"
 config/features=PackedStringArray("4.6", "GL Compatibility")
 config/icon="res://icon.svg"
+
+[rendering]
+
+textures/vram_compression/import_etc2_astc=true

scripts/build-runtime.ps1

@@ -150,8 +150,8 @@ echo "Copying libraries from $SRC_DIR..."
 
 if ($PLATFORM -eq "android") {
     $android_archs = @{
-        "arm64" = "aarch64-linux-android"
-        "arm32" = "armv7-linux-androideabi"
+        "arm64-v8a" = "aarch64-linux-android"
+        "armeabi-v7a" = "armv7-linux-androideabi"
         "x86_64" = "x86_64-linux-android"
         "x86" = "i686-linux-android"
     }

scripts/build-runtime.sh

@@ -150,8 +150,8 @@ fi
 if [[ "$PLATFORM" == "android" ]]; then
     typeset -A android_archs
     android_archs=(
-        "arm64" "aarch64-linux-android"
-        "arm32" "armv7-linux-androideabi"
+        "arm64-v8a" "aarch64-linux-android"
+        "armeabi-v7a" "armv7-linux-androideabi"
         "x86_64" "x86_64-linux-android"
         "x86" "i686-linux-android"
     )

ss_player/sources.py

@@ -19,10 +19,24 @@ def get_include_paths(base_dir=""):
         os.path.join(base_dir, "runtime/include"),
     ]
 
+# Godot's scons arch names differ from the Android ABI directory names the SDK
+# packages libraries under (this is also what download-sdk / build-runtime emit).
+# Map the build arch to the on-disk ABI directory so the linker finds the lib.
+_ANDROID_ARCH_TO_ABI = {
+    "arm64": "arm64-v8a",
+    "arm32": "armeabi-v7a",
+    "x86_64": "x86_64",
+    "x86_32": "x86",
+    "x86": "x86",
+}
+
 def get_runtime_lib_path(base_dir, platform, arch):
     # Unify logic: platforms like macos, ios, and web typically don't use arch subdirs in this project's structure
     if platform in ['macos', 'ios', 'web']:
         return os.path.join(base_dir, "runtime", "libs", platform)
+    elif platform == 'android':
+        abi = _ANDROID_ARCH_TO_ABI.get(arch, arch)
+        return os.path.join(base_dir, "runtime", "libs", platform, abi)
     else:
         return os.path.join(base_dir, "runtime", "libs", platform, arch)