[Guide] Getting EmulationStation to work with FS-UAE

silver

If you're running RetroPie on something which isn't a Raspberry Pi then you might be interested in using FS-UAE as the default Amiga emulation with EmulationStation. This guide details how you can do this.

This solution isn't entirely original as it's based off a similar solution that Eirulan came up for Microsoft Windows and LaunchBox. If you're interested, you can find more details here.

How does it work?

One of the nice things about FS-UAE that it uses the data from the OpenRetro Game Database to know exactly which CPU to emulate, which disks have to be mounted and a number of other settings for all the variants of a game you have.

Each game variant is allocated its own UUID (Universally Unique IDentifier) and, if you provide that to FS-UAE, then you can start a game with all the correct settings.

To use this within EmulationStation we'll create a new file format (ending .fs-uae) which contains the games UUID. To generate those files we'll query the local FS-UAE database (using sqlite3) and ask it to list the details of the games installed and each games UUID.

The last part of the puzzle is that we'll then configure EmulationStation to treat those .fs-uae files as Amiga games (instead of the usual file formats) and, when launched, we'll direct EmulationStation to open a custom launcher which launches FS-UAE with the UUID for the game.

Advantages

Each game (even the multi-disk ones) has only one file for EmulationStation to parse, so you only get one entry in your games list.
Scraping is fully supported, so you get accurate meta-data on your games.
It works great with Amiga, CD-TV and CD32 games.

Disadvantages

If you're running a Raspberry Pi then you probably want to use Amiberry instead of FS-UAE. Itt does appear to be possible to compile FS-UAE for the Raspberry Pi but I have no idea whether or not it works and how well it runs.
You need to remember to add/remove/edit your Amiga games within FS-UAE Launcher.
When you add or remove games you need to re-run the script to generate the files that EmulationStation sees.
The script is fairly quick and dirty, there is no error handling or fancy user interface

Installation

Before you start, these installation steps assume a number of things:

You have root access through the use of sudo
You have only one account which is using EmulationStation and RetroPie
You've installed FS-UAE and EmulationStation in the default locations set by the RetroPie-Setup script
Your roms are in the default EmulationStation location set by the RetroPie-Setup script

For reference, the default locations are:

FS-UAE database: ~/Documents/FS-UAE/Data/Databases/Launcher.sqlite
Amiga rom folder: ~/RetroPie/roms/amiga

If these assumptions don't match your setup (for example, you're using a non-English installation) then you'll need to tailor the script accordingly. If you do have to do that then it's worth noting that $HOME (in the code) and ~ mean the same thing.

Copy the code below and save into a file called create-fs-uae-uuids

#!/bin/bash

# --- Configuration settings start here ---

# Location of FS-UAE Launcher.sqlite file
database="$HOME/Documents/FS-UAE/Data/Databases/Launcher.sqlite"

# Location of Amiga folder in EmulationStation. Ignore trailing /
amiga="$HOME/RetroPie/roms/amiga"

# ----- Code starts here -----

# Remove any existing .fs-uae files
rm -f $amiga/*.fs-uae

# Connect to the FS-UAE database
sqlite3 "$database" "select name,year,uuid from 'game' where have=4" | while read line ;
do
  # Extract the game name, year and UUID
  name=`echo $line | cut -d"|" -f1`
  year=`echo $line | cut -d"|" -f2`
  uuid=`echo $line | cut -d"|" -f3`

  # Tell the user what we've found
  echo "Found: $name ($year)"

  # Create a valid filename based on the game name. This is done by
  # replacing invalid characters with a space and then replacing more
  # than one consecutive space with just a single one
  file=`echo $name | sed -e "s/[^a-z0-9\._\-\&\']/ /gi" | tr -s ' '`
  file="$file ($year).fs-uae"

  # Create a file with that name containing the UUID for the game
  echo -n "$uuid" > "$amiga/$file"
done

Copy the code below and save into a file called launch-fs-uae

#!/bin/bash

# Get the UUID from the first line of the file
uuid=`head -n 1 "$1"`

# Launch FS-UAE Launcher passing it this UUID
fs-uae-launcher "$uuid"

Now make both scripts executable and install them in a better location with:

chmod a+x create-fs-uae-uuids
chmod a+x launch-fs-uae
sudo mv launch-fs-uae /usr/local/bin/
sudo mv create-fs-uae-uuids /usr/local/bin/
sudo chown root:root /usr/local/bin/launch-fs-uae
sudo chown root:root /usr/local/bin/create-fs-uae-uuids

Now install sqlite3 which is needed to access the FS-UAE database:

sudo apt-get install -y sqlite

(Note: Using sqlite here is correct, even though you're actually going to use sqlite3)

Initial setup

Run FS-UAE Launcher, set up your OpenRetro Game Database account (if you haven't done already) and import/scan your games into FS-UAE. You must do this before you run these scripts otherwise they will fail.

Configuring FS-UAE is beyond the scope of this guide.

It is worth noting that where you store your games doesn't really matter. It's possible to store them in your existing EmulationStation Amiga ROMS folder, although I tend to put them in the FS-UAE folder.

Updating EmulationStation

Make sure that FS-UAE Launcher is closed and then run:

create-fs-uae-uuids

Assuming everything works well, the amiga folder will now contain a file for every game you have configured on FS-UAE. If you open one of those files, you'll see the UUID for that game.

Every time you modify your game collection, you'll need to re-do this section.

Testing

Let's check it works! Pick out a game you like and run the following command:

launch-fs-uae <filename.fs-uae>

For example, if your game was called Test (1995).fs-uae then:

launch-fs-uae "$HOME/RetroPie/roms/amiga/Test (1995).fs-uae"

If all goes well, FS-UAE should launch along with the game.

Integration with EmulationStation

To get EmulationStation to correctly parse those files, we need to modify the configuration files. There are two ways to do this:

Modify the /etc/emulationstation/es_systems.cfg file. This is the easiest but will be overwritten whenever you add or remove systems from the RetroPie-Setup script.
Create a copy of the /etc/emulationstation/es_systems.cfg, put it in $HOME/.emulationstation/ and modify that. This won't be overwritten when you add or remove systems from the RetroPie-Setup Script but you will need to manually copy over the new system to the new location in order to keep parity.

(Personally I use the default es_systems.cfg file but that is because I'm on a single user machine and I don't need to add or remove any systems)

Either way, you need to open the es_systems.cfg files (from your preferrred location) find <name>amiga</name> and then a couple of lines below that make the following changes:

  <extension>.fs-uae</extension>
  <command>launch-fs-uae %ROM%</command>

In case you're wondering, here is how my file looks:

  <system>
    <name>amiga</name>
    <fullname>Commodore Amiga</fullname>
    <path>/home/retro/RetroPie/roms/amiga</path>
    <extension>.fs-uae</extension>
    <command>launch-fs-uae %ROM%</command>
    <platform>amiga</platform>
    <theme>amiga</theme>
  </system>

Save the file.

Note: Whilst testing, if you had to provide a full path to launch-fs-uae to get it to run, then you'll also need to supply the full path in the config file above.

Wrapping up

Launch EmulationStation and you should see your Amiga games listed. You can now scrape them as you would normally for the meta-data. During scraping, you'll notice that each game is listed as ending in .fs-uae. This is good.

When you select a game, FS-UAE should now launch with the correct game, the correct disks inserted and the correct configuration changes.

Questions, comments and feedback all welcome.

mitu

@silver said in Guide: Getting EmulationStation to work with FS-UAE:

The solution is somewhat hacky as it involves modifying your es_systems.cfg file - which will get overwritten when you add systems. There is probably a better (non-hacky) way of doing this.

The solution is to copy it in your user configuration folder /home/pi/.emulationstation and make the modifications there. It won't be overwritten by any RetroPie-Setup scripts.

silver

@mitu said in Guide: Getting EmulationStation to work with FS-UAE:

@silver said in Guide: Getting EmulationStation to work with FS-UAE:

The solution is somewhat hacky as it involves modifying your es_systems.cfg file - which will get overwritten when you add systems. There is probably a better (non-hacky) way of doing this.

The solution is to copy it in your user configuration folder /home/pi/.emulationstation and make the modifications there. It won't be overwritten by any RetroPie-Setup scripts.

Good call, thanks. When I do a 1.1 update I'll update the docs to mention that. I might include a script which copies the file and updates it to work with FS-UAE too.

youxia

I thought Amiberry solution is presently the best one regarding Amiga?

silver

@youxia said in Guide: Getting EmulationStation to work with FS-UAE:

I thought Amiberry solution is presently the best one regarding Amiga?

I've never tried it. If it works better for you, then great.

Clyde

@silver Thanks for this thread. Although I'm not currently planning to play Amiga games on my Retropie-based arcade cabinet, I'm using fs-uae on my Laptop and my PC running Kubuntu Linux.

@youxia I don't know Amiberry, but fs-uae has two outstanding features: the OpenRetro database for metadata, multiple disk mounting etc., and fs-uae's own graphical frontend fs-uae-arcade:

All of the metadata seen in the video, e.g. the boxart, screenshots etc., is scraped by fs-uae-arcade on the fly from OpenRetro while browsing if there's an internet connection. edit: Once scraped, it is stored locally for further use.

I don't know if the frontend works in Retropie, though, and @silver's guide doesn't use it either, but runs fs-uae from Emulation Station.

youxia

@silver I'm simply curious, there's no need to get prissy about it.
I suppose my fault is that I forget sometimes that people use Retropie/ES on platforms other than RPi.

@Clyde I see, though as I mentioned ^^ I'm looking from the RPi perspective. Amiberry is probably a recommended Amiga solution here, since it's constantly updated and oriented towards Raspberry and WHDLoad packs. These already solve the multi-disk and config problems.

Clyde

@youxia said in Guide: Getting EmulationStation to work with FS-UAE:

@Clyde I see, though as I mentioned ^^ I'm looking from the RPi perspective. Amiberry is probably a recommended Amiga solution here, since it's constantly updated and oriented towards Raspberry and WHDLoad packs. These already solve the multi-disk and config problems.

I see, too. It's always interesting how the same problems can be solved by different approaches. Thanks for the information.

silver

@clyde said in Guide: Getting EmulationStation to work with FS-UAE:

@silver Thanks for this thread. Although I'm not currently planning to play Amiga games on my Retropie-based arcade cabinet, I'm using fs-uae on my Laptop and my PC running Kubuntu Linux.

Not to worry :) Funnily enough, I'm using FS-UAE on an old laptop with Linux Mint and the RetroPie scripts.

I don't know if the frontend works in Retropie, though, and @silver's guide doesn't use it either, but runs fs-uae from Emulation Station.

The fs-uae frontend is pretty good.

However, to be honest, the main reason I wrote the scripts was because all my other games were being launched from EmulationStation and I wanted to keep the consistent user interface with the Amiga ones.

I don't pretend that FS-UAE will be the best for everyone (especially if you're running on a Raspberry Pi) but, for those that are running it and want a nice integration with EmulationStation, I thought it might be useful.

Clyde

@silver said in Guide: Getting EmulationStation to work with FS-UAE:

However, to be honest, the main reason I wrote the scripts was because all my other games were being launched from EmulationStation and I wanted to keep the consistent user interface with the Amiga ones.

That's what I thought. That said, do you happen to know if the frontend of fs-uae works on the Raspbian-based Retropie? Just curious, but (yet?) not curious enough to try it out myself without practical reason. 😇

I don't pretend that FS-UAE will be the best for everyone (especially if you're running on a Raspberry Pi) but, for those that are running it and want a nice integration with EmulationStation, I thought it might be useful.

"Best" is relative anyway. In most cases, it's synonym to "best for", and next to nothing is best for everyone. Well, maybe apart from air, but only if you limit "everyone" to air-breathers. But I digress. 😊

silver

@clyde said in Guide: Getting EmulationStation to work with FS-UAE:

That's what I thought. That said, do you happen to know if the frontend of fs-uae works on the Raspbian-based Retropie? Just curious, but (yet?) not curious enough to try it out myself without practical reason. 😇

No idea I'm afraid, sorry!

silver

Thanks everyone for your feedback. Changes I've made:

I've added a reference that this isn't the best solution for people using a Raspberry Pi.
I've trimmed down the code and inserted it into the post - so that you don't have to download it from another site
I've added references for modifying both the global and the local es_systems.cfg file
I've corrected some typos and spelling mistakes in the instructions
Although I've hardcoded the paths into the script, given that these are the default FS-UAE and EmulationStation paths, it should make it even easier to use

Enjoy.

Clyde

@silver Where can one find the updated script? Your opening post still shows as last edited seven days ago.

@silver said in [Guide] Getting EmulationStation to work with FS-UAE:

Although I've hardcoded the paths into the script, given that these are the default FS-UAE and EmulationStation paths, it should make it even easier to use

Since you defined them at the top of the script, I don't see a problem with that either.

silver

@clyde said in [Guide] Getting EmulationStation to work with FS-UAE:

@silver Where can one find the updated script? Your opening post still shows as last edited seven days ago.

Odd, I only just updated it now! I think that might be something to do with the forum software?

@silver said in [Guide] Getting EmulationStation to work with FS-UAE:

Although I've hardcoded the paths into the script, given that these are the default FS-UAE and EmulationStation paths, it should make it even easier to use

Since you defined them at the top of the script, I don't see a problem with that either.

I was hoping that, so good to know :) I still think the installation instructions are overly complicated as I think the majority of people will just have one account running EmulationStation with the default locations. In which case it should just be "save these files, copy to /usr/local/bin/, set permissions and you're done".

Would be good to know your thoughts?

silver

Blow it, I've updated the instructions based on those assumptions :)

I think anyone who has changed the defaults will know what to change to get it working.

Clyde

@silver Forget what I wrote, I just mistook the creation date for the editing date. The latter shows when you hover the mouse pointer over the little edited sign behind the creation date.

Your instructions are already well structured, I think, and some things can't be shortened much more without becoming unintelligible.

One thing I noticed that won't concern many common users in my opinion is the system-wide placement you describe. I usually advise less experienced users to put scripts into ~/bin for global access, because most of them only have one user account. Experienced users don't require that information anyway.

silver

Added a bunch of updates just to make things clearer, plus added some commentary to the code so people understand what it's actually doing.

werpu

Thanks for the guide it was really helpful to move my collection over to fs-uae, there are several small issues
a) The db already must exist, so fire up fs-uae-launcher first and import/scan your games
b) There is a small bug in the regexp file=echo $name | sed -e 's/[^a-z0-9\._\-&]/ /gi' | tr -s ' ' the & should be escaped aka \&
c) Third on localized machines, Documents will become something else, aka on german machines Documents now is Dokumente, they localized the paths after user home. Not sure if there is a generic way to query them.
I just wanted to drop the info.

noise

@silver said in [Guide] Getting EmulationStation to work with FS-UAE:

@youxia said in Guide: Getting EmulationStation to work with FS-UAE:

I thought Amiberry solution is presently the best one regarding Amiga?

I've never tried it. If it works better for you, then great.

that's right but Amiberry is only ARM, not possible at this time with x64.

the guide is fine, except running with my adf files.. (i need to do it manually) thanks for it. (y)

silver

@noise said in [Guide] Getting EmulationStation to work with FS-UAE:

the guide is fine, except running with my adf files.. (i need to do it manually)

Glad to hear you found the guide helpful!

Regarding the issue you have with ADF files, can you explain a little more?

If I can solve your problem by improving the script then I'm more than happy to do so.