Android port: build an arm64 APK from your own disc (Vulkan, touch controls, on-device training)

[LiquidAzir]

Hi! I got Wind Waker Recomp running natively on Android and wanted to offer the port back in case it's useful.
It follows the project's model exactly: the player builds their own APK from their own disc, and nothing
game-derived is in this PR.

What it is

• scripts/android/build.py builds on top of scripts/windows/build.py: the same RecompCore/DolRecomp pins, disc
  checks, translation, verified digest (54f54434), mods and source steps run on the Windows PC, then the game
  module and the app are compiled for arm64 Android with the NDK's clang. Aurora already supports Android, so it
  draws through Dawn on Vulkan (Aurora's prebuilt dawn-android-aarch64), with SDL3 statically linked into
  libmain.so. The APK is assembled without Gradle (javac, d8, aapt2, apksigner from the SDK).
• android/: an entry shim (default paths in the app's storage, a session log mirrored to logcat, an optional
  launch.env), a touch overlay (stick, A/B/X/Y, L/R/Z, START, D-pad, drag on the right half for the C-stick)
  that feeds Aurora's virtual pad the way the iOS overlay does and hides when a controller connects, and the
  activity (a 60 Hz display request).
• scripts/android/install.py installs the APK and pushes main.dol, the RELs and the disc image to the app's
  folder over adb.
• --device SERIAL runs the local optimization training on the phone: an instrumented module plays the
  Windows builder's training route headless to player control on Outset (plain, then widescreen + Better Wind
  Waker), and the counts guide the real compile. The profile stays local, as on the other platforms.
• --train-app (with --device) also trains libmain.so on the phone. The module's training is headless, so
  it never runs the GX worker or the render thread; this one plays the opening once, drawn and paced, with an
  instrumented app and the real module. With libmain.so linked -Bsymbolic-functions (its exported functions
  were called through the PLT even from within), the GX worker went from 51 to 47 M cycles a frame on the
  title's sea.
• Shared code changes are small: Android's Back opens the options menu (settings_menu.cpp, one line), and
  cmake/composite accepts optional extra sources (used only for the training module's profile flush).

Two things Android needed that might be worth knowing

• Aurora's Android window code waits for SDLSurface to call auroraNativeSetSurfaceReady, which stock SDL
  never does, so the game hangs before its first frame. The builder patches SDL's Java as it copies it (along with
  a 64 MB stack for SDL's game thread, matching the Windows link).
• On phones, sustained speed is set by temperature. On a Galaxy Z Fold 7, Samsung's thermal manager lowers the
  CPU limit from 4.47 GHz to about 2.0/1.7/1.4 GHz as the surface passes 38/40/42 °C. Work per frame and memory
  stay flat (measured with simpleperf stat), so late-session slowdowns are the frequency cap rather than a leak.
  docs/ANDROID.md has the numbers.

Tested on one device, a Galaxy Z Fold 7 (Snapdragon 8 Elite, Adreno 830, Android 16), from a Redump-verified
disc. This branch, rebased on windows-release 8cc06de (RecompCore 9618e9d), generates the verified composite
(54f54434), builds with the default options and, freshly installed with install.py, plays the scripted route
to player control on Outset. Before the rebase the port was played on the phone for some hours: it boots and plays
on both screens with touch, and runs at 30 FPS in most of the opening, with dips in the
heaviest views once the phone throttles. Not yet tried: other devices and GPUs, controllers on Android, saving and reloading, the
new save states and climbing on Android, the HD packs and the later game. See docs/ANDROID.md.

Things you may want to change

• The application id defaults to the profile's bundle id (dev.bluewake.BlueWake) and the label to "Wind Waker
  Recomp". Both are builder options.
• The build host is Windows only (it reuses the Windows builder); a Mac/Linux host would need the same
  subclassing of scripts/builder.
• The activity honors an adb-only --ez showWhenLocked true extra, for testing and training on a locked phone.
  Drop it if you'd rather not have it.
• Docs and README wording are yours to adapt; docs/ANDROID.md is written in the style of docs/WINDOWS.md.

This was developed with substantial AI assistance (Claude), like the rest of the project.

🤖 Generated with Claude Code

---

Summary by cubic

Adds a native Android (arm64) port: scripts/android/build.py builds a signed APK on a Windows PC from your own disc, reusing the Windows builder's pins, disc checks, translation, and verified composite digest. The game module and app are compiled with the NDK's clang, drawing through Aurora on Vulkan with SDL3, and the optimization profile can be trained on the phone itself.

What's in it

• New android/ app: entry shim, touch overlay (stick, buttons, D-pad, C-stick drag) feeding Aurora's virtual pad, activity, and docs.
• scripts/android/install.py installs the APK and pushes main.dol, the RELs, and the disc image over adb.
• --device SERIAL trains the game module on the phone; --train-app also trains libmain.so (-Bsymbolic-functions cut the GX worker from 51 to 47 M cycles a frame on the title's sea).

Noteworthy details

• The build patches SDL's Java: a 64 MB game thread stack, and telling Aurora when SDLSurface is ready (stock SDL never does, so the game would hang before its first frame).
• Android's Back opens the options menu; a bluewake_settings_is_open hook (an atomic flag for cross-thread reads) leaves a touch away from the controls to the menu; cmake/composite accepts optional extra sources for the training module's profile flush.
• Climbing and save states are included (the host's climb.c, save_state.c and zlib, as on iOS), and install.py makes the pushed game folders 2775 so a new app can read them.
• Follow-up fixes: touch pushes track pointer ids 16–31; the adb-only lock-screen switch applies only while launch.env is present; the manifest requires Vulkan 1.1; install.py skips existing files only on size plus SHA-1 match.
• Tested on a Galaxy Z Fold 7; docs/ANDROID.md documents the phone's thermal throttling that sets sustained speed.

^{Written for commit b66adcb. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 14 files

<sub>Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic</sub>

[LiquidAzir]

Thanks for the review. e3f0947 addresses all 15 comments (replies in each thread).

Checked so far: the branch builds (Java, libmain.so and the APK); the manifest now requires Vulkan 1.1 and makes OpenGL ES optional; nativeMenuOpen and bluewake_settings_is_open are exported; and a profile in a folder with a space in its name reaches the compiler as one argument and compiles.

Still to do: an on-device check of the touch and launch changes (the menu's right side by touch, rapid taps, and the lock-screen switch only with launch.env). The phone wasn't available today; I'll follow up here once it's done.

[cubic-dev-ai]

All reported issues were addressed across 10 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[LiquidAzir]

On-device check of e3f0947 done on the Galaxy Z Fold 7 (cover screen), from a fresh install.py install with the default application id:

• install.py: a fresh install pushes main.dol, the RELs and the disc image and opens the folders; a second run finds all three identical (size and SHA-1) and skips them in about 3 seconds.
• Options menu by touch: with the menu open, a tap on the right half of the screen (on the Render resolution combo) opens the combo instead of moving the C-stick.
• Short taps: quick taps on the touch START take the title through to the memory card prompt.
• showWhenLocked: read from the keyguard state with the screen locked:
  • With launch.env present and the extra, the game shows over the lock screen (occluded).
  • A following ordinary launch turns that off.
  • The extra without launch.env is refused.

[chrissotraidis]

Hi @LiquidAzir, thanks for all the work on this. Wind Waker Recomp is moving into BlueWake, which Elliott and I now maintain together. Could you open this against https://github.com/chrissotraidis/bluewake? An Android port is new platform work, so we'd review it there as its own project, with your authorship. Building the APK from the player's own disc fits how BlueWake handles phones and tablets.