Nonobsolete Android builds & Installing GemRB on your Android device

[rmtew]

This post has been archived. Up to date instructions are available here: http://www.gemrb.org/wiki/doku.php?id=install:android

Getting GemRB to run on your Android device is a confusing affair. This post is intended to collect all the scattered information that is still relevant, and write it up in a way that removes as much of that confusion as possible.

Note that it needs some fleshing out with regard to the following:

• The differences involved in games other than Baldur's Gate 1.
• Android devices that support an external sdcard. My HTC One X does not, and differs from the standard. For the most part this should be covered below, but there may be some remaining points of confusion.

If they apply to you, then you may want to go away and google (of bing if you're into that) for further detail before using any of the following information.

PLEASE. If your experience differs, or you have something to add, reply to this and I'll modify to suit. Even if you have an observation about what playing GemRB is like on your device, or how you had to use a different GemRB.cfg setting. THANKS.

How playable is GemRB on your phone?

It isn't very playable yet.

• The hotbar at the bottom of the screen is only partially visible.
• Everything is too small, and some decent support for zooming in and out and scrolling around when zoomed in might make a difference.

Requirements

Apart from GemRB, you need some other things.

• The game you wish to play with GemRB. For me, this is the GOG.com version of Baldur's Gate. If you do not have any games, you can download the Baldur's Gate II demo from within GemRB. BUT If you do choose to download the demo, it will be immediately playable and you do not need to bother with anything in this post.
• The Widescreen Mod. This post was written with the current version being 3.05.

Where do I get GemRB for Android?

There are currently two different versions you can install.

• GemRB on Google Play.
• The build on SourceForge.

Which should you use? There are advantages to using either. The market version is developed externally to the GemRB project, so may contain Android specific improvements that the SourceForge version does not. The SourceForge version gets updated more often, and will contain GemRB improvements that have not yet been incorporated into the market version.

Installing the version from SourceForge

This is aimed at someone who wishes to get one of their games working on their Android device.

• Obtain the latest GemRB .apk from SourceForge.
• Install it, but do not run/open it. This will involve turning on a Settings option on your device that allows installation of non-Market apps, if you have not done this already.

Complication: If your android device does not support an external SD card, scroll down to the section below titled "My Android device does not allow external SD cards".

Okay, so your device supports an external SD card. Good for you. Now run GemRB and you will see the initial "Downloads" menu.


Complication: After GemRB installs it's data files, it will from then on try and run an installed game every time you run it. This means that it will start up, show a black screen and then exit.

Deselect the demo. As this is the last time you will ever see this menu, if you want to customise how GemRB runs on your device select the "Show more options" item. In any case, once you exit the menus, GemRB will install it's initial data files and then exit shortly after.

Installing a game on your Android device

You need to have a game suitable for playing on GemRB. If you don't know which games are supported or buggy, go away and find out, and come back when you have a game you're happy with. Install it on your Windows PC. If you have a different kind of computer, go away and find out what non-Android GemRB users do when they're in your situation.

• Install your game of choice on your computer, paying attention to the installation directory.
• Download, install and run the Widescreen Mod to modify your game installation to support different screen resolutions than the ones it was originally created with. Like your fancy widescreen device. Keep in mind that this mod is obviously written by someone for whom English is a second language. You might wish to head down to the section "This Widescreen Mod is somewhat confusing", and then return here once you are done.

Locate the GemRB data installation directory on your device. If you haven't changed it, it will be "/mnt/sdcard/app-data/net.sourceforge.gemrb".

• Copy the contents of your game's installation directory on your computer into the GemRB data installation directory on your device. To be explicit, I select all the files and directories within my "D:\Games\Baldur's Gate" directory and copy them directly into "H:\Android\data\net.sourceforge.gemrb" on my mounted device. This may mean copying PDF manuals, executables and DLLs - but it is fine to deselect them. There are no file clashes, even if you are copying over the existing "overrides" directory.
• Within the "net.sourceforge.gemrb" data directory, rename "GemRB.cfg.sample" to "GemRB.cfg".

Edit "GemRB.cfg".

• Set the correct "GameType" value. What values are possible are clearly described in the file.
• Set the "GameName" if you are a pedant.
• Set "Width" to the value you gave the Widescreen Mod. For me this was again 1280.
• Set "Height" to the value you gave the Widescreen Mod. For me this was again 720.
• Set "Fullscreen" to 1.
• Set "GamePath", "CD1, "CD2", "CD3", "CD4" and "CD5" to correect the relative paths. See the section "Known working GemRB.cfg entries" below.

Now unmount your device, and run GemRB and watch your game start up.

Complication: If GemRB does not start your game, and instead returns you to the home screen, then the problem is likely the "Width" and "Height" you specified in "GemRB.cfg". For me I need a "Width" less than 1190 to get GemRB to work, I match this with a "Height" of 666. Why this is, I do not know.

My Android device does not allow external SD cards

You can address this when you run GemRB for the first time. At this point in time, you will need to have a good idea of where you want GemRB to put it's data, if you do not want to store it in the default "app-data" location.

Deselect the demo and select the "Show more options" in the above menu.

Select the "Data installation location" item.

Finally choose "Specify directory". At this point, you can modify the installation path to be somewhere other than "/mnt/sdcard/app-data/...". In the case of my HTC One X, I modified it to "/mnt/sdcard/Android/data/..." which appears to be the matching location for my device.

After this, return to the menu with "Data installation location" and select "Downloads". Deselect the demo and then exit the menu. At this point GemRB will proceed to install it's data in the specified directory, then shortly after exit.

You can now scroll up to the "Installing a game on your Android device" section, above.

This Widescreen Mod is somewhat confusing

What you need to have at this point:

• Your device's screen resolution. My HTC One X is supposed to be 1280 x 720.

The first menu is somewhat confusing.

Install Component [Widescreen Mod]?
[R]e-install, [N]o Change, ninstall, [Q]uit or choose one:
1] for the original Infinity Engine (CHOOSE THIS!)
2] for GemRB

Press the 2 key and then press the enter key. Then you get some unimportant text followed by the first option to configure, which is somewhat confusing.

Enter your X coordinate. It should be a number, >= 640.

This is your minimum X resolution, enter your device's screen width. Obviously, for me this is 1280.

Enter your Y coordinate. It should be a number, >= 480.

And similarly, your device's screen height.

From this point, say no to all options up to the final confirmation.

Are you sure? Y/N

Then the mod will patch files.

Known working GemRB.cfg entries

Note that the current directory is considered to be the data installation location in GemRB's settings. It is not necessary to specify the absolute "/mnt/sdcard/..." path here.

Baldur's Gate I (GOG.com):

GameType=bg1
GameName=bg1
GamePath=./
CD1=./
CD2=./
CD3=./
CD4=./
CD5=./
CD6=./

Icewind Dale (3 CD, source):

GameType=iwd
GameName=iwd
GamePath=./
CD1=./
CD2=./CD2/
CD3=./CD3/
CD4=./
CD5=./
CD6=./

Planescape Torment (4 CD, source):

GameType=pst
GamePath=./
CD1=./
CD2=./CD2/
CD3=./CD3/
CD4=./CD4/

Planescape Torment (GOG.com, source):

GameType=pst
GamePath=./
CD1=./data/
CD2=./data/
CD3=./data/
CD4=./data/

I want GemRB to start up as if I never started it for the first time

Maybe you specified a bad data installation location.

• Go into the "Apps" menu in your device's "Settings" menu.
• Select the "GemRB" app.
• Select "Force stop", if the option to do so is enabled.
• Select "Clear data".
• Exit the menus and run GemRB.

How do I compile GemRB for Android myself?

Beats me, but here are some related links:

• This post, although old, gives some vague pointers.
• Reference to a github project that can be used (sources: 1, 2, 3).

Android GemRB improvement wishlist

These were observed with the "611f141_20120617" SourceForge release.

• The initial credits, main menu and character creation are surrounded by lots of black space. It would increase usability of part of the game experience if they would automatically be scaled to occupy the empty screen space.
• General support for zooming in and out with the standard two finger gesture, along with scrolling around when zoomed in, might make the game more playable on phones.
• The hotbar in-game should appear completely on screen, rather than half on and half off the bottom of the screen.
• The application should not show a black screen and then return to the device's home screen, if "GemRB.cfg" is not configured suitably.
• The application should be able to determine non-standard "app-data" locations, like "Android/data".
• Magnifying glass SDL functionality as zoom alternative, mentioned here.
• Integrate Widescreen Mod functionality into the app.

Unresolved questions

• Why does the SourceForge download page say to download the zip files and extract them over the GemRB apk data installation location? It doesn't seem to make a difference whether you have them or not, is they really any difference?
• Is there documentation on how to compile the Android .apk? I'd like to have a go.

Modifications to this post

2012-07-07: Added "app-data" desired improvement, and related improvements to a specific SourceForge build. Added initial section on Android GemRB development. Added "magnifying glass" and "Widescreen Mod" improvements. Added "Known working GemRB.cfg entries" section. Added detail about what downloading the demo means (source). Added GOG.com PST GemRB.cfg entry.

 

[lynx]

Nice writeup. I've tried it only once before, but here are a few notes:

- the games have hardcoded resolutions and not just in the program, but in the data. That's why a widescreen mod is needed and there is no on-the-fly scaling yet. Choosing unavailable resolutions will break things fast. You may get better results with the CLEARLY PREFERED first option of the mod.

- intro movies can be disabled in the config

- if you get a black screen, check the log, it's all there.

- overwritting older data is crucial or you will get various more or less breaking bugs

[SyntaxError]

there IS on the fly scaling in our SLD 2 driver

 

of course it simply scales up proportionally and wont allow for widescreen play.

 

this same driver is also needed for multitouch input and no android dev has had much success building it unfortunately. It should be possible, but our android devs seem to be MIA.

[Avenger]

Our SDL 2.0 driver plugin just got some recent changes, so test/use it. Hopefully it already made its way into the newest apk.

[rmtew]

- overwritting older data is crucial or you will get various more or less breaking bugs

I presume you are referring to the need to download and extract the extra zip files. GUIScripts and overrides come with the apk, is there a reason the content of the zip files is different? My assumption is that they are built at the same time, and should be the same.

[SyntaxError]

GUIScripts and override may stay the same for many builds, but they do get changed every now and again, sometimes extensively.

 

Its a bad habit to not update them each new version because, while much of the time, things will break outright and it may be obvious other time lesser changes will just cause subtle bugs that may be falsely reported.

 

I do not run GemRB on my android phone so i dont know much about this process, but i do know that stagnant GUIScripts and override have caused more problems for android users then anything else.

[rmtew]

GUIScripts and override may stay the same for many builds, but they do get changed every now and again, sometimes extensively.

 

Its a bad habit to not update them each new version because, while much of the time, things will break outright and it may be obvious other time lesser changes will just cause subtle bugs that may be falsely reported.

 

I do not run GemRB on my android phone so i dont know much about this process, but i do know that stagnant GUIScripts and override have caused more problems for android users then anything else.

Right. But the key point is that the Android download page provides 3 downloads, two of which should be redundant. The apk comes with GUIScripts and overrides. They are released at the same time. I would almost bet money that if I did a diff between the two sets of files, they would be the same.

 

Now, I can understand if they have changed, and they have different dates and revisions. But clearly in this case, this is not the case.

 

There are so many hoops to jump to get GemRB working. The world is a better place if we can remove the pointless ones.

[SyntaxError]

I agree; there are a lot of hoops. We could really use an android developer on the team since android is likely to be our biggest target considering Mac and iOS will be getting BGEE and its successors. I'm actually quite surprised that we have only had one android dev working on GemRB, but he has been gone a long while.

 

There is a lot that could be done to improve the android experience. the fact that you need to mess with a configuration file is a major turn-off to most. If we could create a GUI interface for the config it would be a boon all around. If not a cross-platform CHU based GUI then maybe abstracting out our configuration setup into some kind of "context object" that could be created in ways other than via the config file (NSUserDefaults for mac/ios and other equivalents for android and windows)

 

we also should at least take data path settings from the original INI. I wrote a patch one that would convert windows paths to unix ones then intersect the path from the INI with the GamePath to determine the relative path to the CD dirs, but it was declined for some reasons i no longer recall. I'm afraid its since been lost, but I would gladly write one again if the other devs agree that it is worthwhile.

 

the way things are going with GOG and BGEE I think we maybe ought to instead get rid of CD paths as they are and come up with a single way that can locate the data for all versions instead of living in the past with distributions that are CD based. Maybe we should search GamePath for a set of known files and determine the data paths that way. could be overly complicated since there are so many games tho. I really think it would be worthwhile to develop some automatic method and you can count this as me volunteering to do the programming if we can jsut come up with a method that the team as a whole findes acceptable.

[rmtew]

There is a lot that could be done to improve the android experience. the fact that you need to mess with a configuration file is a major turn-off to most. If we could create a GUI interface for the config it would be a boon all around. If not a cross-platform CHU based GUI then maybe abstracting out our configuration setup into some kind of "context object" that could be created in ways other than via the config file (NSUserDefaults for mac/ios and other equivalents for android and windows)

I think we're on the same page. Make it just work.

 

There are two pieces of functionality that I would like to see added to GemRB application:

• Game fingerprinting. It should be possible for GemRB to look at a folder and say, hey this is Baldur's Gate, and it's the original 1 CD release. Or the GOG.com release. And then it should use the appropriate file-related settings.
  
• Calculated graphics settings. It should be possible to come up with standard settings that suit the device being run on. This should also internally do the Widescreen Mod work. If there is a need for a user to enter desired resolution, it should be done via UI and if it fails the user should get a chance to revert/retry with different values.
  

I do not think either of these need acceptance from the GemRB team. And I think both can be done, at least with respect to the Android app, by automatically updating the "GemRB.cfg file".

 

The new user experience with the application can also be enhanced. The current "Downloads" dialog is nice for an experienced device user / programmer, but not very well explained compared to what could be done. I'm not going to write out what I would like to so, as I'm going to save that energy for trying to get GemRB compiling.

[rmtew]

Our SDL 2.0 driver plugin just got some recent changes, so test/use it. Hopefully it already made its way into the newest apk.

I'd be curious about whether there is something you can share about this?

 

My assumption is that the current apk is built from the commandergenius SDL 1.2/1.3 port to Android. And that SDL 2.0 supports Android, but lacks the infrastructure that the current apk's get from commandergenius.

[SyntaxError]

• Calculated graphics settings. It should be possible to come up with standard settings that suit the device being run on. This should also internally do the Widescreen Mod work. If there is a need for a user to enter desired resolution, it should be done via UI and if it fails the user should get a chance to revert/retry with different values.
  

 

this is already available in a basic form as i mentioned above (simple proportional scaling of the entire game). Getting more complicated than that would require significant effort (I've been told) due to the nature of the original interface format (CHU). Not saying its not possible, but nobody has been willing to tackle it because of the limited return on investment.

 

I agree it would be nice, but i dont think you fully understand the hard-coded nature of the CHU format. (for what its worth neither do i)

 

I do not think either of these need acceptance from the GemRB team. And I think both can be done, at least with respect to the Android app, by automatically updating the "GemRB.cfg file".

 

I'm not sure what you are trying to say, but I definitely do need acceptance from the GemRB team; I'm not interested in forking anything. They would no better than myself how best to "fingerprint" the data sets and come up with an acceptable approach that will work for all platforms and distributions.

[Avenger]

• Calculated graphics settings. It should be possible to come up with standard settings that suit the device being run on. This should also internally do the Widescreen Mod work. If there is a need for a user to enter desired resolution, it should be done via UI and if it fails the user should get a chance to revert/retry with different values.
  

 

this is already available in a basic form as i mentioned above (simple proportional scaling of the entire game). Getting more complicated than that would require significant effort (I've been told) due to the nature of the original interface format (CHU). Not saying its not possible, but nobody has been willing to tackle it because of the limited return on investment.

 

I agree it would be nice, but i dont think you fully understand the hard-coded nature of the CHU format. (for what its worth neither do i)

 

I do not think either of these need acceptance from the GemRB team. And I think both can be done, at least with respect to the Android app, by automatically updating the "GemRB.cfg file".

 

I'm not sure what you are trying to say, but I definitely do need acceptance from the GemRB team; I'm not interested in forking anything. They would no better than myself how best to "fingerprint" the data sets and come up with an acceptable approach that will work for all platforms and distributions.

It wouldn't be a fork, if there is a solution that miraculously works (like someone spent the time and actually worked out a solution) we would obviously incorporate it in the main tree.

Sadly, the solution isn't as simple as modifying GemRB.cfg based on device parameters. That would just make a black window with some graphic in the middle (or top left corner).

[SyntaxError]

thing is that I want to work out a solution before i write any code

 

Specifically Im talking about getting rid of CD paths and friends and being able to automatically figure things out using nothing more than the GamePath.

surely lynx and yourself would have helpful insight here. You two seem to know the most about IE and the differences between distributions.

[FightCat]

Hello,

 

Could you provide similar info for IWD2 cfg please ?

 

Even though I've edited the previously 1200*800 res (widescreen mod was run so too) to 1092*728 in cfg, GemRB still exits to home after a black screen of a few seconds.

[lynx]

it's easiest to get it to work on a standard resolution first, since then you know it's not a resolution problem. But that is not possible with the widescreen mod installed unless it is done in the gemrb mode (which has some MOS scaling problems). Not that reinstalling it is hard, it just means you'd have to copy data to the gadget twice.

 

As for game distribution recognition, it's hard, since usually there are no extra files anywhere, just the paths differ — if at all (gog pst comes to mind). We can add extra search paths, but that's it.

 

Btw, the market gemrb version is preconfigured and shouldn't require any editing, save for the resolution if you have widescreen installed.