Android APK export

Android uses the macOS toolchain with its Android runtime installed. This initial implementation runs on ARM64 devices with Android 8.0 or newer and Vulkan 1.1. Emulator checks pass; physical phone/tablet and vendor GPU acceptance remain outstanding.

Set up the tools

Install the Android SDK (platform-tools, build-tools and an API 35 or newer platform), Android NDK, Java JDK 17 or newer and Python 3.10 or newer. Set ANDROID_HOME and JAVA_HOME if they are not found automatically. The runtime was validated with NDK 29.0.13599879 and SDK build-tools 36.

Source builds stage the Android runtime with python3 android/tools/build_runtime.py, after building the host toolchain and its WGSL engine shaders. See the repository's docs/ANDROID_BUILD.md for build options and the complete platform limits.

Run on Android

  1. Start an ARM64 emulator, or connect an Android device with USB debugging enabled and authorize the computer.
  2. Choose the device under Run On > Android Devices and Emulators. Refresh the device menu if it was connected after the IDE opened.
  3. Choose Run, or Run with Touch Controls for a keyboard/gamepad layout. Use Edit Touch Controls to record keys, drag controls and save layouts.
  4. The IDE builds, signs, installs and starts the APK. DebugLog and runtime errors appear in the output pane. Stop closes the running app.

Android debug builds provide runtime checks and file/line errors. IDE breakpoints, stepping and variable inspection are not yet supported on this target. The Windows IDE does not yet offer Android export.

Create an APK

Choose Create Executable > Android application (.apk). Use Include touch controls to preview and embed a saved configuration. The APK contains its native runtime, assets and controls; the device does not need the IDE or the source layout file.

blitzcc --mode extended --target android --bundle-id com.example.game -o Game.apk game.bb
blitzcc --mode extended --target android --touch-controls classic --run --device emulator-5554 -o Game.apk game.bb

IDE exports and ordinary command-line exports use the Android debug signing key. For distribution, pass --android-keystore release.jks --android-key-alias game and set B3D_ANDROID_STORE_PASSWORD and B3D_ANDROID_KEY_PASSWORD in the environment. Keep the same package ID and signing key when installing an update. AAB/store publishing and version metadata are outside this initial APK export path.

Input and assets

Touch, acceleration and virtual controls use the same commands as iOS. Multiple fingers can hold movement and action controls together. TouchMouse provides compatibility with mouse commands; overlay contacts are captured and cannot click through. Sensor presence is optional and sampling starts only when requested. Pause, focus loss and rotation release held input and invalidate old samples.

Assets are copied into the app's private writable directory when it is installed or updated. Unrelated saved files survive updates; bundled assets are refreshed. Use --assets directory to choose a separate asset folder. APKs include runtime licence notices.

The runtime provides 2D/3D rendering, physics, files, sockets, fonts and WAV/Ogg audio. Desktop GUI windows, file panels, MIDI, desktop DLL calls, VR, hardware audio effects and Shared World transport are not implemented on Android. Check platform capabilities before using those features.

Mobile input guide ยท Guides