User Tools

Site Tools


Current version: 0.8.5
iOS: 0.8.1+
Android: 0.8.5 (Play/Market version is obsolete!)

Github Coding has become social! Fork us!


Latest commit

# ideally, but does not work on sourceforge (does elsewhere); even http proxies don't help rss> 1 author 30m sidebar for frequently accessed stuff


iOS (iPhone/iPad/iPod Touch)

Version info

Builds are compiled and uploaded automatically to sourceforge. Complete source to the iOS version of GemRB is contained within the GemRB git repository. Anyone with an Apple developer certificate and Xcode can download the source and compile themselves without the need to jailbreak.


  • Jailbroken (or a dev certificate) iOS 4.3 or higher
  • iPhone/iPod touch require a retina display. (iPhone/iTouch 4 or above)
  • Computer with iTunes.
  • Enabled ssh access to device; install open SSH via Cydia. Unless you like strangers being able to access your iDevice remotely please follow Cydia's directions for changing the passwords. only required for manual updates or removing installed games
  • Alternative to above requirement be sure to adapt the installation steps to this method. see above.
  • software capable of SFTP (Transmit/WinSCP/etc) or just a terminal if you like. see above.
  • Phone configuration tool for windows or for mac to view the console logs for troubleshooting, if you don't have other means of doing this already. no longer required but still useful..


  1. Jailbreak your device (or have a developer certificate. see below)
  2. Download from here. see top of page.
  3. Double click GemRB.ipa to add the application into iTunes.
  4. Use either iTunes+AppSync or Installous to install GemRB onto your device.
  5. Copy your IE game of choice to somewhere on the device not on the system partition (/private/var/mobile)
  6. load the config file via iTunes file sharing to GemRB. GemRB auto generates config files now.
  7. Follow the directions for “Game Data Installation” (see below)

Alternate Installation (Codesign the app)

Note: an Xcode project with an iOS target is available in the git source and you can compile your own build. However, some iOS customizations are not in the master repo and you will have to build all dependent libraries yourself. SDL still has some bugs in source that are patched in the iOS official distribution.

The following assumes that you have a valid Apple iOS developer certificate. As such it does not require a jailbroken device.

  1. Download GemRB.ipa as per instructions above.
  2. Download the AppResigner AppleScript from GitHub
  3. Expand GemRB.ipa (rename to .zip), locate and drag it on AppResigner. Choose the appropriate developer identity when asked.

Option 1

  1. Drag the newly code-signed app on the Xcode Organizer and over your iOS device.

Option 2

  1. Replace Payload/ with the re-signed application as an IPA by replacing with the one from AppResigner
  2. make sure no hidden files exist in Payload (I'm looking at you .DS_Store!)
  3. re-zip Payload with the iTunesArtwork and iTunesMetadata.plist
  4. rename the extension to .ipa
  5. follow the standard install instructions using your IPA.


See this forum thread for help.

GemRB for iOS can redirect stderr and stdout to a file (GemRB.log) in the GemRB “Documents” folder by enabling “Debug” mode. Connect your device to iTunes and download that file to your computer to open and read in a text editor for troubleshooting. This file is truncated each time you run GemRB.

Game Data Installation

You don't need widescreen mod to play fullscreen on iOS! All the original data is in 4:3 ratio, iOS will scale everything to fullscreen for you. You may widescreen if you wish, but you should only go up to 1024×768, otherwise things will be too small to play.

Its possible that widescreen mod will cause graphical corruption in the intro videos, but it is negligible.

use iTunes to load games, configuration files, and saves.

using iTunes File Sharing you can load files with the “.cfg” extension to GemRB's documents; you can select which of these files to load at runtime.

iTunes can also be used to upload games. simply create a zip archive of the game directory and rename the file extension to the lowercase GameType for the game (ie BG1, BG2, IWD, PST…). When you run GemRB after uploading a game you can choose to install the game which will unzip the archive to “Library/GameType” and copy the default configuration file and name it “foldername.gametype.cfg”. This config file will contain automatically generated paths to the data. If you install a file that already exists the old one will be overwritten so beware.

Crating Your Archive

These are some simple methods for crating a compatible archive, thought far from the only way:

  • Mac: right click your game folder and select “Compress”
  • Windows: ???
  • Unix/Linux: from a command line zip -r GameName.Gametype GameDirectory

Be sure to rename the extension to the lowercase game type.

Depending on your IE game and what device you are using (iPad vs iPhone) you will need to change your config resolution. If you don't have the IE game modded with the widescreen mod the maximum resolution you can set for iPhone (assuming your IE game supports it) is 800×600 and the maximum for ipad (no widescreen mod required) is 1024×768.

Features Unique to iOS

Any of these could be implemented on other platforms, although, some of the code behind it is not in the GemRB branch. (I will share if asked for it)

  • replacement of mouse cursors with scaled overhead action icons. (there is no mouse after all!) since iOS development merged with main development this feature has been left behind.
  • per-pixel scrolling of TextAreas
  • Cocoa Application Wrapper with special iOS features.
  • load games/config/saves via iTunes.

Known bugs

  • resuming GemRB sometimes causes the audio to pause fixed via hack. Still would like to find a proper fix.
  • interacting with a scrollbar prevents being able to scroll a text area with 1 finger (2 fingers still work) Fixed?
  • possible crash issue regarding file handles when starting a new game (BG1)

Known Issues (and bugs outside our control i.e. SDL bugs)

  • The console sometimes wont appear. Usually swipe down a couple times (even if the keyboard isn't up) and try again. fixed?
  • iPhone seems to run in portrait mode (SDL bug) fixed?
  • GameType=auto does not work. this is because iOS doesn't have a full python install. you could make it work your self by editing the info.plist and setting a PYTHON_HOME environment variable to a path to a full python install from Cydia.
  • Its possible that widescreen mod will cause graphical corruption in the intro videos, but it is negligible.
Known Issues With GemRB's SDL 2 driver (affects only builds after 0.7.0-292)
  • Cursors and tooltips dont work.
  • Modal windows don't have the darkening effect on the background interface.
  • gamma setting doesnt work.
  • Game Rendering is extremely inefficient (tho this was a problem before when using the compatibility layer too)


install/ios.txt · Last modified: 2015/01/01 23:17 by lightkey