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:**

```bash
# 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):**

```bash
# 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.

```bash
# 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).

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

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

```bash
# 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"
```

```bash
# 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

```text
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:

```text
Project > Export... > Add... > Android
```

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

```ini
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)

```bash
# 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

```text
Project > Export... > Android > Export Project
```

### 5.4 Install / test on a device

```bash
# 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:

```bash
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"

```bash
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"

```bash
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:

```bash
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:

```bash
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

```bash
# 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.