touchHLE is a high-level emulator for iPhone OS apps. It runs on modern desktop operating systems and Android, and is written in Rust.

touchHLE’s high-level emulation (HLE) approach differs from low-level emulation (LLE) in that it does not directly simulate the iPhone/iPod touch hardware. Instead of running iPhone OS inside emulation, touchHLE itself takes the place of iPhone OS and provides its own implementations of the system frameworks (Foundation, UIKit, OpenGL ES, OpenAL, etc). The only code the emulated CPU executes is the app binary and a handful of libraries.

The goal of this project is to run games from the early days of iOS:

  • Currently: iPhone and iPod touch apps for iPhone OS 2.x.
  • Next: iPhone OS 3.0 support.
  • Longer term: iPhone OS 3.1, iPad apps (iPhone OS 3.2), iOS 4.x, …
  • Never: 64-bit iOS.

Support for apps that aren’t games isn’t a priority: it’s more complex and less fun.

The touchHLE app compatibility database tracks which apps work in touchHLE. It is a crowdsourced effort to which anyone can contribute.

If you’re curious about the history and motivation behind the project, you might want to read the original announcement. For an introduction to some of the technical details, check out touchHLE in depth.

Important disclaimer

This project is not affiliated with or endorsed by Apple Inc in any way. iPhone, iOS, iPod, iPod touch and iPad are trademarks of Apple Inc in the United States and other countries.

Only use touchHLE to emulate software you have obtained legally.

Platform support

  • Officially supported: x64 Windows, x64 macOS and AArch64 Android.
    • These are the platforms with binary releases.
    • If you’re an Apple Silicon Mac user, the x64 build reportedly works in Rosetta.
  • Probably works, but you must build it yourself: AArch64 macOS, x64 Linux, AArch64 Linux.
  • Never?: other architectures.

Input methods:

  • For simulated touch input, there are four options:
    • Mouse/trackpad input (tap/hold/drag by pressing the left mouse button)
    • Virtual cursor using a game controller (move the cursor with the right analog stick , and tap/hold/drag by pressing the stick or the right shoulder button)
    • Mapping of game controller buttons (see the description of --button-to-touch= in OPTIONS_HELP.txt)
    • Real touch input, if you’re on a device that has a touch screen
  • For simulated accelerometer input, there are two options:
    • Tilt control simulation using the left analog stick of a game controller
    • Real accelerometer input, if you are using a phone, tablet or some other device with a built-in accelerometer (TODO: support game controllers with accelerometers)
      • This apparently doesn’t work on certain Android devices, particularly Xiaomi/MIUI devices, but we don’t know why

Development status

Real development started in December 2022. This is so far a single person’s full-time passion project; please consider helping me to keep doing this by donating! There are also a number of volunteers contributing in their free time. There’s only been a handful of releases so far and no promises can be made about the future. Please be patient.

In general, the supported functionality is defined by the supported apps: most contributors are interested in getting a particular game working, and contribute support for whichever missing features are needed for that game. Consequently, the completeness varies a lot between APIs, e.g. UIKit is easily the most hacky and incomplete of the large frameworks that have been implemented, because most games don’t use very much of its functionality, whereas the OpenGL ES and OpenAL implementations are probably complete enough to cover a large number of early apps, because games make heavy use of these.

Usage

First obtain touchHLE, either a binary release or by building it yourself (see the next section).

You’ll then need an app that you can run. The app compatibility database is a good guide for which versions of which apps are known to work, but bear in mind that it may contain outdated or inaccurate information. Note that the app binary must be decrypted to be usable.

There’s a few ways you can run an app in touchHLE.

Special Android notes

Windows, Mac and Linux users can skip this section.

On Android, only the graphical user interface (app picker) is available. Therefore, you must put your “.ipa” files or “.app” bundles inside the “touchHLE_apps” directory. Note that you can only do that once you have run touchHLE at least once.

File management can be tricky on Android due to restrictions introduced by Google in newer Android versions. One of these methods may work:

  • If you tap the “Open file manager” button in touchHLE, this should open some sort of file manager. You might also be able to find touchHLE in your device’s file manager app (often called “Files”), alongside cloud storage services. There are some limitations on what kinds of operations are possible. The files in this location are stored on your device.
  • If you have an older version of Android, you may be able to directly access touchHLE’s files by browsing to /sdcard/Android/data/org.touchhle.android/files/touchHLE_apps. Note that the /sdcard directory is usually not on the SD card.
  • You may be able to use ADB. If you’re unfamiliar with ADB, try using https://yume-chan.github.io/ya-webadb/ (in Google Chrome or another browser with WebUSB) with your device connected over USB. touchHLE’s files can be found in “sdcard” > “Android” > “data” > “org.touchhle.android” > “files” > “touchHLE_apps”.

Graphical user interface

touchHLE has a built-in app picker. If you put your .ipa files and .app bundles in the touchHLE_apps directory, they will show up in the app picker when you run touchHLE.

To configure the options, you can edit the touchHLE_options.txt file. To get a list of options, look in the OPTIONS_HELP.txt file.

Command-line user interface

This section does not apply on Android.

You can see the command-line usage by passing the --help flag.

If you’re a Windows user and unfamiliar with the command line, these instructions may help you get started:

  1. Move the .ipa file or .app bundle to the same folder as touchHLE.exe.
  2. Hold the Shift key and right-click on the empty space in the folder window.
  3. Click “Open with PowerShell”.
  4. Type .\touchHLE.exe "YourAppNameHere.ipa" (or .app as appropriate) and press Enter. If you want to specify options, add a space after the app name (outside the quotes) and then type the options, separated by spaces.

Other stuff

Any data saved by the app (e.g. saved games) are stored in the touchHLE_sandbox folder.

If the emulator crashes almost immediately while running a known-working version of a game, please check whether you have any overlays turned on like the Steam overlay, Discord overlay, RivaTuner Statistics Server, etc. Sadly, as useful as these tools are, they work by injecting themselves into other apps or games and don’t always clean up after themselves, so they can break touchHLE… it’s not our fault. 😢 Currently only RivaTuner Statistics Server is known to be a problem. If you find another overlay that doesn’t work, please tell us about it.

Building and contributing

Please see the BUILDING.md, DEBUGGING.md and CONTRIBUTING.md files in the git repo.

License

touchHLE © 2023 hikari_no_yume and other contributors.

The source code of touchHLE itself (not its dependencies) is licensed under the Mozilla Public License, version 2.0.

Due to license compatibility concerns, binaries are under the GNU General Public License version 3 or later.

For a best effort listing of all licenses of dependencies, build touchHLE and pass the --copyright flag when running it, or click the “Copyright info” button in the app picker.

Please note that different licensing terms apply to the bundled dynamic libraries (in touchHLE_dylibs/) and fonts (in touchHLE_fonts/). Please consult the respective directories for more information.

Thanks

We stand on the shoulders of giants. Thank you to:

This is a list of apps known to work in touchHLE right now.

Pay attention to the supported versions. Versions that haven’t been tested might not work. For each listed version, the name in “quotes” is the display name (i.e. the name you’d see on the home screen), and the number is the bundle version number. If you’re not sure which version of an app you have, you can look at the App bundle info: output when you run it in touchHLE.

Scale hack supported means an app is compatible with the --scale-hack= option, which enables it to run with increased internal resolution. Assume that at least 2× and 3× scales work with no noticeable performance impact. Some apps have been tested at scales as high as 4K.

Default button mappings means that touchHLE has pre-configured button mappings for the app, making it more convenient to use on a game controller. See touchHLE_default_options.txt for details.

Performance is tested with release builds of touchHLE on a 2017 Retina MacBook, which is a fairly underpowered (passively cooled!) dual-core laptop. Your computer is probably faster.

Please click to expand the details for the app you are interested in.

  • Crash Bandicoot Nitro Kart 3D (2008, Vivendi/Polarbit, App Store day-two title)
    • Working versions:
      • “CBNK3D” 1.0 (in-game version number: 0.7.5)
      • “Crash Kart” 1.0 (in-game version number: 0.7.6)
    • Broken versions:
      • “Crash Kart” 1.7.7 (in-game version number: 1.0.1)
    • The intro video that plays before the title screen is skipped.
    • Otherwise fully playable, everything works. Among other things:
      • Sound effects and music
      • All menu screens
      • All game modes
      • Save game persistence (settings, unlocks, records)
      • Continuing a previous game after closing and reopening the app
    • Consistent full framerate (60fps)
    • Scale hack supported
    • Default button mappings
  • Fastlane Street Racing (2008, Atod AB)
    • Working versions:
      • “Fastlane” 2.0 (in-game version number: 1.20.0)
    • Known issue: the specular lighting effect on the cars only seems to appear on Android. This is probably an issue with touchHLE’s GLES1-on-GL2 compatibility layer, which isn’t needed on Android.
    • Otherwise fully playable, everything works. Among other things:
      • Sound effects and music
      • All game modes
      • Saving and playing back replays
      • Save game persistence (settings, unlocks, records)
    • High framerate, but with some frames dropped in loading tunnels
    • Scale hack supported
    • Default button mappings
  • Mystery Mania (2009, Electronic Arts)
    • Working versions:
      • “Mystery Mania” 1.1.0
    • Broken versions:
      • “Mystery Mania” 1.1.26
    • Known issue: Depending on your system language, you may get stuck at the language selection screen the first time you run the game. But the second time you run it, you will get to the main menu, and the game is playable.
    • touchHLE will crash if you open the music player or tap “More EA Games”.
    • Not fully tested, but the first few puzzles are fully playable:
      • Sound effects and music
      • Save game persistence
    • Consistent full framerate (30fps)
    • Scale hack unsupported
  • Super Monkey Ball (2008, SEGA/Other Ocean Interactive, App Store launch title)
    • Working versions:
      • “Monkey Ball” 1.0
      • “Monkey Ball” 1.02
      • “Monkey Ball” 1.3 (this is the most heavily tested version)
      • “SMB Lite” 1.0
    • Fully playable, everything works. Among other things:
      • Sound effects and music
      • Logo, title, menu, ranking, settings and credits screens
      • Main Game, Instant Game (Shuffle Play) and Practice game modes
      • Save game persistence (settings, unlocks, records)
      • Continuing a previous game after closing and reopening the app
      • The tutorial (in the versions that have it)
    • Consistent full framerate (30fps)
    • Scale hack supported
    • Default button mappings
  • Touch & Go (2009, The Game Creators)
    • Working versions:
      • “Touch & Go” 1.1
      • “Touch & Go LITE” 1.2
    • Broken version:
      • “App Pack 1” 1.0 (several games bundled into one app, doesn’t work yet)
    • Fully playable, everything works. Among other things:
      • Sound effects and music
      • Menu screens
      • All the levels in the LITE version
      • High score persistence
    • Consistent full framerate (60fps)
    • Scale hack supported
  • Various (Donut Games)
    • iPhone OS 2.x versions of many old titles by this developer seem to work. (But all of these still available for modern iOS and Android, and in some cases Windows.)
  • Wolfenstein 3D (2009, id Software)
    • Working versions:
      • 1.0 from the official open source release
    • Broken versions:
      • 1.1 from the official open source release and later
    • Multi-touch is not supported yet, so you can’t move and shoot at the same time
    • Not a touchHLE bug: random flashing colors in-game are caused by a bug in the app itself
    • Otherwise seemingly fully playable:
      • At least the first level :)
      • Sound effects and music work
      • Saving works
    • Consistent full framerate (60fps)
    • Scale hack supported