Getting Started

Getting Started

1. Get the emulator

• Download a build: Actions → latest Build HyperHLE run → artifacts for Windows (x64), macOS, Linux, Android (arm64). Tagged runs additionally appear under Releases.
• Android: just install the APK — versionCode auto-increments, so new builds install directly over old ones (no uninstall needed).
• Build from source: see Build and CI.

2. Get an app

HyperHLE runs iPhone OS apps: an .app bundle (directory) or an .ipa archive. It does not use any iOS firmware/system files — the "OS" is re-implemented in Rust.

⚠️ Apps and games are copyrighted — obtain them legally from backups of apps you own.

3. Run it

Desktop (Windows/macOS/Linux):

# Linux/macOS
touchHLE path/to/App.app
touchHLE path/to/App.ipa

# Windows
touchHLE.exe path\to\App.ipa

Android: install the APK, then open it and pick your .ipa file when asked (the app acts as a file picker/importer).

4. Useful options

Full list: touchHLE --help (source: OPTIONS_HELP.txt in the repo).

• --fullscreen — full-screen display (Android is always full screen)
• --landscape-left / --landscape-right / --upside-down — force startup orientation
• --scale-hack=2 — render at 2× internal resolution (crisper but slower, may glitch)
• --deadzone=0.1 — touch deadzone tuning (see --help)

5. If an app doesn't work

High-level emulation means compatibility is per-app work. Check Compatibility for known-good apps and how to report; use Debugging → Finding unimplemented APIs to see exactly which functions your app is missing.