Run Android ARM64 VR APKs on Apple Vision Pro
Executing Android ARM64 VR Applications on Apple Vision Pro
Klepton is a specialized compatibility layer and JIT-less relinker designed to enable the execution of Android XR and Quest APKs on both macOS and visionOS.
🛠️ Core Architecture
The heart of the project is klepton-ld, which performs a translation of Android .so libraries into Apple-compatible .dylib and .framework files. These are subsequently linked into the primary Klepton runtime.
Note: Klepton is currently limited to Java-heavy Java-thin applications. It does not implement a full Android Runtime (ART) or a Java Virtual Machine (JVM).
System Flow
The following diagram illustrates how the guest application interacts with the Klepton runtime and the underlying Apple hardware:
🎨 Graphics Translation
Klepton handles graphics by mapping Android's APIs to Metal-based backends:
| Android API | Translation Layer | Target Backend |
|---|---|---|
| GLES 3.2 | Vendored ANGLE (GLES 3.0) | Metal |
| Vulkan | MoltenVK | Metal |
⚙️ Technical Nuances
The Register Conflict
A significant hurdle in this translation is the handling of the x18 register. While both macOS and Android reserve this register, many legacy Android apps still utilize it. However, macOS explicitly zeros out during context switches.
To resolve this, klepton-ld patches all instances of x18 usage, redirecting them to use per-library Thread Local Storage (TLS) slots instead.
JIT Considerations
Klepton supports the runtime patching and loading of .so files using mmap. While this is possible, it is primarily beneficial on macOS where Just-In-Time (JIT) compilation is permitted.
[!IMPORTANT] Applications relying on scripting engines that mandate JIT (such as V8 or LuaJIT) will likely still require JIT capabilities to function.
🚀 Getting Started
1. Install Host Dependencies
Ensure you have the following tools installed via Homebrew:
brew install pkg-config sdl3 apktool
2. Prepare the Application
You must provide your own APK. Use apktool to extract the contents:
# Extract the APK into a folder named 'beatsaber'
apktool d -f -o beatsaber beatsaber.apk
3. Build and Verify
Run the regression suite to ensure everything is configured correctly:
make check
4. Execution Scripts
Depending on your target platform, use one of the following:
- macOS Frontend:
./build_run_viewer.sh - Vision Pro Frontend:
./build_run_vpro.sh - Steam VR Link (WIP):
./build_run_slink.sh --shell --view
📊 Current Project Status
- Beat Saber: Functional on macOS and visionOS (some minor graphical glitches persist).
- Steam VR Link: Currently under development.
- Generalizability: Improving build tooling and broader app support.
Repository Details:
- Author:
shinyquagsire23 - Stars: 94
- Forks: 5