Skip to content

Android Setup

Jump to bottom
Bubbleshum edited this page May 22, 2026 · 2 revisions

Android Setup

Warning

The Android target currently launches to a white screen on this fork (see "Known limitations" in the README). The project builds and installs, but the Avalonia UI doesn't yet render on Android. Treat the Android path as build-only until that's resolved.

Active desktop development is on net8.0-windows10.0.17763.0. If you want a working WPR right now, see Windows Setup.

What works today

  • Project builds for net8.0-android (when the workload version lines up).
  • APK installs on ARM64 devices.
  • SDL2 + FFmpeg native bindings ship via Java bindings projects.

What doesn't

  • The main Avalonia UI shows a white screen on first launch — no library, no Add button, no game list.
  • Game launch path past the UI is untested on Android.

The white-screen issue is tracked in the project README under "Known limitations & TODO".

Requirements (for building)

Requirement Notes
Android device ARM64 recommended
Android 10+ Min SDK is set higher than upstream WPR
.NET 8 SDK Same as desktop
Android workload See SDK version notes below — version matters
Android SDK platform 35 or 36 installed net8.0-android resolves to TargetPlatformVersion=36.0 on the system SDK
ADB or sideload-friendly device For installing the APK

SDK version pitfalls

This is the part that trips people up. From the project's own dev notes:

Component What it provides
System .NET SDK (C:\Program Files\dotnet) .NET 10.0.203 + Android workload 36.1.43 / 10.0.100 — no .NET 8 manifest
User-local SDK (%USERPROFILE%\.dotnet, if installed) .NET 8.0.420 + Android workload 34.0.154 — not visible to Rider
Android SDK platforms installed android-35, android-36 — no android-34

Consequences:

  • Every net8.0-android* TFM resolves to TargetPlatformVersion=21.0 on the system SDK (the workload has no net8 manifest, falls back to 21).
  • SupportedOSPlatformVersion higher than 21.0 triggers NETSDK1135.
  • Setting <TargetPlatformVersion> in the csproj does not override the workload fallback.
  • Don't pin Rider to your user-local SDK via global.json — Rider's MSBuild uses the system SDK, and a global.json pointing elsewhere fails with NETSDK1141.

If you want to actually build the Android leg right now, either get the SDK / workload triple to match what your csproj asks for, or build only the desktop target with -f net8.0-windows10.0.17763.0.

Building the Android APK

If your workload + SDK setup is consistent:

dotnet build Src/UI/WPR.UI.Android/WPR.UI.Android.csproj -c Debug

Output APK lands at:

Src/UI/WPR.UI.Android/bin/Debug/net8.0-android/

For the full solution, see Building WPR — the -f net8.0-windows10.0.17763.0 flag deliberately skips the Android leg when you don't need it, which is the common case while desktop work is under way.

Installing

adb install path/to/com.bubbleshum.WPR.UI.Android.apk

Or transfer to device + open via file manager. Grant storage permissions on first launch if prompted.

Reporting Android issues

Because Android is currently broken at the UI layer, the most useful kind of report right now is anything diagnostic about the white screen — logcat from launch through the white screen, with the WPR tag filter:

adb logcat -s "WPR:V" "AndroidRuntime:V" "DOTNET:V"

Open an issue at https://github.com/Bubbleshum/WPR/issues with:

  • Device model and Android version
  • WPR commit hash you built from
  • The logcat trace
  • Screenshot if anything other than a white screen appears

Related pages

  • Building WPR — full build instructions, CLI flags, SDK pitfalls.
  • Windows Setup — what works today.
  • Architecture — how the pipeline is structured (same pipeline runs on Android, modulo the UI bug).

Clone this wiki locally