docs/BUILD_ANDROID.md

MonkeyStudio - Full Build & Android Export Guide (A to Z)

This document is the complete, step-by-step guide for STEP 1 (setup) and STEP 5 (build a real .apk) of the MonkeyStudio project.

Everything described here was executed and verified on Debian 12 with Godot 4.7.2-stable. Commands are copy-paste ready.

---

STEP 1 - Godot install + Android project setup

1.1 Install the Godot editor (Linux / macOS / Windows)

Linux (Debian/Ubuntu) - scripted:

# Give the script execute permission
chmod +x scripts/install_godot.sh

# Run the installer (downloads editor + export templates + runtime libs)
./scripts/install_godot.sh

Linux - manual (what the script does):

# 1. Download the editor binary for the latest stable release
curl -fL -o godot.zip \
  https://github.com/godotengine/godot/releases/download/4.7.2-stable/Godot_v4.7.2-stable_linux.x86_64.zip

# 2. Unzip it
unzip godot.zip

# 3. Make it executable and put it on your PATH
chmod +x Godot_v4.7.2-stable_linux.x86_64
sudo mv Godot_v4.7.2-stable_linux.x86_64 /usr/local/bin/godot

# 4. Verify
godot --version
# -> 4.7.2.stable.official.XXXXXXXXX

Windows / macOS: download the matching .zip / .dmg / .app from https://godotengine.org/download and place the binary on your PATH. All other steps below are identical from the editor UI.

1.2 Install export templates

Export templates are the pre-compiled engine the game runs on.

# Editor method (recommended, one click)
#   Editor menu > Manage Export Templates > Download and Install

# Headless / CLI method
TEMPLATE_DIR="$HOME/.local/share/godot/export_templates/4.7.2.stable"
mkdir -p "$TEMPLATE_DIR"
curl -fL -o templates.tpz \
  https://github.com/godotengine/godot/releases/download/4.7.2-stable/Godot_v4.7.2-stable_export_templates.tpz
unzip -o templates.tpz -d /tmp/godot_tpl
cp /tmp/godot_tpl/templates/* "$TEMPLATE_DIR/"

1.3 Install the Android build toolchain

You need three things: OpenJDK 17, the Android SDK command-line tools, and the Android NDK is only required if you use a custom Gradle build (MonkeyStudio's default APK build does not need the NDK).

# OpenJDK 17
sudo apt-get update
sudo apt-get install -y openjdk-17-jdk unzip curl

# Verify
java -version
# -> openjdk version "17.x"

# Android command-line tools
mkdir -p "$HOME/android-sdk/cmdline-tools"
cd "$HOME/android-sdk/cmdline-tools"
curl -fL -o cmdline.zip \
  https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
unzip -o cmdline.zip
mv cmdline-tools latest    # the SDK expects <sdk>/cmdline-tools/latest

# Set environment variables (add these to ~/.bashrc)
export ANDROID_HOME="$HOME/android-sdk"
export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools"

# Accept licenses and install the required packages
yes | sdkmanager --licenses
sdkmanager "platform-tools" "build-tools;34.0.0" "platforms;android-34"

# Create the debug keystore Godot uses for testing builds
keytool -keyalg RSA -genkeypair -alias androiddebugkey \
  -keypass android -keystore debug.keystore -storepass android \
  -dname "CN=Android Debug,O=Android,C=US" -validity 9999 -deststoretype pkcs12

1.4 Point Godot at the toolchain

Editor > Editor Settings > Export > Android
  Android SDK Path      -> $HOME/android-sdk
  Debug Keystore        -> $HOME/debug.keystore
  Debug Keystore User   -> androiddebugkey
  Debug Keystore Pass   -> android
  Java SDK Path         -> /usr/lib/jvm/java-17-openjdk-amd64

Alternatively, from a terminal, write the same paths into ~/.config/godot/editor_settings-4.tres (advanced). The UI is safer.

1.5 Project display / renderer settings (mobile)

These are already set in project.godot so you do not have to click through the UI, but here is exactly what they do:

Setting	Value	Why
display/window/size/viewport_width	1280	landscape base
display/window/size/viewport_height	720	720p target
display/window/stretch/mode	canvas_items	UI scales, 3D stays crisp
display/window/handheld/orientation	1	landscape
rendering/renderer/rendering_method	mobile	Mobile Vulkan/GLES path
rendering/textures/vram_compression/import_etc2_astc	true	required for mobile
rendering/anti_aliasing/quality/msaa_3d	0	no MSAA (saves GPU/mem)

mobile renderer = Vulkan on modern phones, automatically falls back to the gl_compatibility (OpenGL ES 3.0) path on older 4GB devices.

---

STEP 5 - Build a real .apk

5.1 One-time: generate an export preset

Open the project in the editor, then:

Project > Export... > Add... > Android

A minimal preset is committed at export_presets.cfg. Key fields:

export_path="build/MonkeyStudio.apk"
architectures/armeabi-v7a=true   # 32-bit ARM (old 4GB phones)
architectures/arm64-v8a=true     # 64-bit ARM (required by Play Store)
architectures/x86=false
architectures/x86_64=false
package/unique_name="com.monkeycode.monkeystudio"
version/code=1
version/name="0.1.0"

5.2 Build from the command line (headless, CI-friendly)

# Make sure the output directory exists
mkdir -p build

# Export a signed debug APK
godot --headless --export-debug "Android" build/MonkeyStudio.apk

# Export a release APK (needs keystore/release set in the preset + editor settings)
godot --headless --export-release "Android" build/MonkeyStudio.apk

# Verify it is a real APK
unzip -l build/MonkeyStudio.apk | head

5.3 Build from the editor UI

Project > Export... > Android > Export Project

5.4 Install / test on a device

# Enable USB debugging on the phone, then:
adb devices
adb install -r build/MonkeyStudio.apk

# Stream logs while the app runs
adb logcat | grep -i godot

---

Keystore & Gradle troubleshooting

Error: "Invalid keystore ... or wrong password"

Regenerate the debug keystore and re-check the pass:

keytool -keyalg RSA -genkeypair -alias androiddebugkey \
  -keypass android -keystore debug.keystore -storepass android \
  -dname "CN=Android Debug,O=Android,C=US" -validity 9999 -deststoretype pkcs12

# Inspect what is inside an existing keystore
keytool -list -v -keystore debug.keystore -storepass android

Make sure the password in Editor Settings > Export > Android matches the -keypass / -storepass you used (they must be the same for the debug store).

Error: "Could not find SDK / Build Tools 34.0.0"

sdkmanager --list | grep build-tools
sdkmanager "build-tools;34.0.0" "platforms;android-34" "platform-tools"

Then re-set Android SDK Path in Editor Settings.

Error: "Missing ‘platform-tools’ / adb not found"

sdkmanager "platform-tools"
export PATH="$PATH:$ANDROID_HOME/platform-tools"
adb version

Gradle build fails: "Could not resolve com.android.tools.build:gradle"

This only happens when gradle_build/use_gradle_build=true. If you see it, either switch the preset back to the default (non-Gradle) APK build (which is what MonkeyStudio ships with) or make sure the Gradle build needs network access:

export GRADLE_OPTS="-Dorg.gradle.daemon=false"

Error: "Export template not found"

Re-run section 1.2 (or use Manage Export Templates > Download). The template folder name must exactly match the engine version, e.g. 4.7.2.stable.

Error: "Java version not compatible"

Godot's Android exporter requires JDK 17. Point Godot at it explicitly:

sudo update-alternatives --config java   # choose java-17

App crashes on launch with OOM on a 4GB phone

1. Lower MemoryManager.asset_budget_mb (default 512 MB) in scripts/core/memory_manager.gd.
2. Keep renderer/rendering_method = mobile.
3. Turn off shadows on low-end devices (already done automatically by studio_main.gd when FPS drops below 30).
4. Import textures as ETC2/ASTC (already enabled in project.godot).

---

Verifying the project without a device

# 1. Reimport all resources (catches broken scripts)
godot --headless --import

# 2. Run the automated subsystem tests (exits 0 on success)
godot --headless res://tests/self_test.tscn

self_test.tscn exercises MemoryManager, all mesh generators, every sculpt brush, the rigging/skinning path, cloth + hair simulation and the timeline.