diff --git a/docs/en/setup/build.md b/docs/en/setup/build.md index bf63b07..c48841f 100644 --- a/docs/en/setup/build.md +++ b/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/" + ``` +- 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//`). + - 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". diff --git a/docs/ja/setup/build.md b/docs/ja/setup/build.md index 37fd3e8..86aa396 100644 --- a/docs/ja/setup/build.md +++ b/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/" + ``` +- 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//` に配置)。 + - プロジェクト設定で `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エディタ」になる点のみです。 diff --git a/examples/dev_gdextension/project.godot b/examples/dev_gdextension/project.godot index 4a80780..a901139 100644 --- a/examples/dev_gdextension/project.godot +++ b/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 diff --git a/examples/dev_module/project.godot b/examples/dev_module/project.godot index fb9413a..1e895d0 100644 --- a/examples/dev_module/project.godot +++ b/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 diff --git a/scripts/build-runtime.ps1 b/scripts/build-runtime.ps1 index 28efb43..f340164 100644 --- a/scripts/build-runtime.ps1 +++ b/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" } diff --git a/scripts/build-runtime.sh b/scripts/build-runtime.sh index 40c6e20..d624659 100755 --- a/scripts/build-runtime.sh +++ b/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" ) diff --git a/ss_player/SpriteStudio-SDK b/ss_player/SpriteStudio-SDK index e49c4b6..cabd8cb 160000 --- a/ss_player/SpriteStudio-SDK +++ b/ss_player/SpriteStudio-SDK @@ -1 +1 @@ -Subproject commit e49c4b66722f8ee24b6cd5690d214f5404b80513 +Subproject commit cabd8cbd517e0631ec1cadc6154b81fa96ea9850 diff --git a/ss_player/sources.py b/ss_player/sources.py index 27e9478..d099ebe 100644 --- a/ss_player/sources.py +++ b/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)