The Ultimate Amiga WHDLoad for RetroPie Project

About | Guide | FAQ | Downloads | Contact

Installation and Setup Guide

How It Works:

- An initial installation of Amiberry to RetroPie

- Download and install the WHDLoad Booter, and Game Data files to: home/pi/retropie/roms/amiga-data/ (you will need to source game-data files externally from this web page.)

- EITHER: Install pre-packaged .uae config files to home/pi/retropie/roms/amiga-data/

- OR: Use the Config Maker to generate the .uae config files to home/pi/retropie/roms/amiga/

A video guide has been compiled which can also be followed along with this written guide:

Video: The Amiga WHDLoad Pack (For RetroPie) Install Tutorial

Step 1: Install the Emulator (UAE4Arm/Amiberry)

You will require RetroPie for this project, but for the purpose of demonstration, the initial RetroPie setup is included within the guide:

Video: Installing RetroPie

If you plan on using UAEArm for this project, this may already be installed within RetroPie, but you should be sure to carry out the latter part of Step 2 below.

However, it is recommended you instead use Amiberry for this project, and to do so,simply update your RetroPie scripts and install Amiberry as as additional package *from source* and set it as your default Amiga emulator, and you can then skip the rest of this step. This is shown in the pictures below.

> >

And again, demonstrated in the video guide:

Video: Installing Amiberry

Step 2: Setup RetroPie and the Emulator

If you are using Amiberry for this project, then the update to your RetroPie scripts and Amiberry install as your default Amiga emulator, means you can then skip the rest of this step and move directly to Step 3..

For older setups , using UAE4Arm, you can do the following....

Using SSH or the Terminal directly from your Pi, relocate your es_systems.cfg file to preserve changes after RetroPie updates.

  sudo cp /etc/emulationstation/es_systems.cfg /home/pi/.emulationstation/es_systems.cfg

- This file tells RetroPie what emulators you want available, and how they should behave. By relocating it to the /.emulationstation folder, it is unaffected by updates to the RetroPie script

Backup your es_systems.cfg file!

  sudo cp /home/pi/.emulationstation/es_systems.cfg /home/pi/.emulationstation/es_systems-backup.cfg

Always wise to do this before making edits to the file (as we are about to do)

Change the Emulator to recognise the uae configuration file '.uae' as a game entry ** This will allow the configurations to be listed on the main menu

- Edit the es_systems.cfg file we have just copied, with;

  sudo nano /home/pi/.emulationstation/es_systems.cfg

- Scroll through to the Amiga section and change the line to read the following:

  <extension>.sh .SH .uae .UAE</extension>

** if you want to know why we don't refer to game files as 'roms', please refer to the FAQ section.

Change the UAE4Arm launch command to allow launching of .uae configuration files

- Open emulators.cfg for editing;

  sudo nano /opt/retropie/configs/amiga/emulators.cfg

- Change the line reading 'uae4arm' to the following;

  uae4arm="pushd /opt/retropie/emulators/uae4arm/; ./uae4arm -config=%ROM%"am

Step 3: Obtain UAE Configuration Files from Downloads and Install

Using the 'Easy' Auto-Setup

You can use the easy Auto-Setup tool to create all the necessary folders / directory structure for the project, the UAE Config Maker and copy onto the system some examples, meaning that it is much easier to simply add new game data and .uae files to the working setup and some of the other elements of this step can be skipped.

No files used by this setup process are included for download from this website; this setup tool will point you to other available potential sources.

This comes in the form of a Python Script which can run directly from the RetroPie menu with very little user input needed.

Instructions for how to install this are included on the GitHub page.

There is a separate Video Guide for this here:

Video: Amiga WHDLoad Auto-Setup (For RetroPie) Install Tutorial

Kickstart Roms (aka Amiga BIOS files - Essential)

Firstly you must obtain and install a copy of the Amiga Kickstart Rom 3.1 (A1200 version) , which is the required amiga 'BIOS" (this is the more correct definition for 'rom' and should not be confused with game-data we will cover below.) This file must be named 'kick31.rom' (all lowercase) and copied to:


You can use your usual method to transfer files for this, with the BIOS folder being available via FTP/SMB etc

Due to existing copyright on the Amiga Kickstart files we cannot provide a download link for this. However, Google is your friend. Please note that I have also been advised that the sold Amiga Forever kickstart files are encrypted and will not work with uae4arm or Amiberry.

Some games also require certain kickstart roms (Kickstart 1.3 and Kickstart 3.1 in particular) to be copied to the DEVS: section of the booting drive.

You should therefore copy kickstart files, as per the below table, to the following locations


Known As
Name in DEVS/Kickstarts
kick31.rom Kickstart v3.1 rev 40.68 (1993)(Commodore)(A1200).rom kick40068.A1200
kick13.rom Kickstart v1.3 rev 34.5 (1987)(Commodore)(A500-A1000-A2000-CDTV).rom kick34005.A500
kick12.rom Kickstart v1.2 rev 33.166 (1986)(Commodore)(A1000).rom kick33180.A500

You should also ensure your 'System ROMS' folder path in Amiberry is set to the correct location, as shown in the following picture, and follow the setting of this by clicking the 'Scan' button.

Game Data & Associated Files

You are going to need several items for this process which you should place primarily in the roms section of RetroPie


The WHDLoad Boot Program

This has a self-contained called _BootWHD, and is the part that loads actual game data / WHDLoad packs. You will need to have this copies as the following location:


A WHDLoad Games Pack

The .uae files here should be placed directly into:


Additionally you will need a folder containing the game data, with sub-folders such as Games_WHDLoad or Games_WHDLoad_AGA (depending on the pack supplied.) In the newest releases we advise to keep game data in a new sub-folder called:


A packs containing over 2000 pre-generated .uae files for ECS Amiga games is available in the Downloads section. These have been built using the 'RetroPlay' WHDLoad packages, which we do not make available via this website.

Video: File Transfer and Setup (Downloads)

Video: File Transfer and Setup (Prepare and Transfer Files)

The UAE Config Maker

This can be installed anywhere, but we recommend as:


It is a Python based program which presently runs from command line only. This part is not essential, but does allow you to scan the   home/pi/RetroPie/roms/amiga-data folder for new WHDLoad game folders. It is worthwhile investing time into how this process works, as this will enable you to take advantage of any future developments of this project. Elsewhere it is described how this is used.

You may use the Config Maker to scan your own games folders, provided you use the sub-folder 'Games_WHDLoad' for the game content. (and similar sub-folders). You can specify scanning (input) and .uae save (output) locations through the command line. More detail is supplied on the GitHub page for the UAE Config Maker.

A word of Note:

When copying across files like this, it is recommended to ensure the ownership permissions have been retained. RetroPie itself includes an option for this in it's own settings/config menus called "Restore Ownership of /pi/roms" or similar.

You can do this manually from the command line with the following;

  sudo chown -hR pi:pi /home/pi/RetroPie

Video: Reset Ownership Permissions

Step 4: Tips and Trick on Running (Using the WHDLoad AutoBooter)

The WHDLoad AutoBooter is a program that has been created for 'seeking out' a WHDLoad Slave file, and generating a script from which to automatically load the game on future loading of the same game. This system is designed to work without any user input being required.

Video: Running the Games

Additional Information

On first load, you will see a display whilst it 'hunts' the slave file and path. If it is found OK, then an 'AutoBoot' file will be generated for future use. This allows the .slave file to be pre-selected, and as a result you will not see the booter on next load.

Following this scan you will see the standard WHDLoad file information. So you know who to thank for this game now running from HardDrive. From this point you can just wait, and expect the game to load.

However, during waiting, you may have noticed a line at the bottom about additional options. These are only present on some games , but can be used to change WHDLoad configuration options where they are available. You can tell this from looking at the game's page on ... for example: and under the section; "WHDLoad Slave information: Configuration" - can can see if there is information there, which the WHDLoad booter will pick up automatically.

If there are options available (e.g. trainers) but they are not under the "WHDLoad Slave information: Configuration", let me know, as they can be added manually.


If you run into trouble at this point (games not appearing to load) try removing / deleting the following file:


This will make Amiga DOS visible again, and you can report any errors seen via the group.

Step 5: Downloading and Running the Config Maker for Updates

The UAE Config Maker program can be used to build .uae config files for UAE4Arm/Amiberry from a template file. Pre-defined paths are 'scanned' and various scanning modes used to recognise different file setups.

Pre-defined paths are 'scanned' and various scanning modes used to recognise different file setups.

This is the tool used to create the pre-packaged Configuration packs, but is available to be used by all, and is recommended to keep updated with project improvements.

Video: Using the UAE Config Maker

Installation / Setup

From Linux Command Line or via SSH, enter the following:

  cd /home/pi




  mv UAEConfigMaker-master .uaeconfigmaker


From Linux Command Line or via SSH, enter the following:

  cd /home/pi

  cd .uaeconfigmaker



Full Instructions are available via the Project's GitHub page.

Setting Host Options:

Some specific options can be set in the file hostconfig.uaetemp which will be inherited by all generated configurations, and exist to be set by the user in order to tailor the generated .uae configurations to the user's requirements. These include options such as "button_for_quit" which decides the input/controller button to be used to exit the emulator.

The details of available options included in the README file linked above.

Video: Using the UAE Config Maker (hostconfig options)

Step 6: Feedback and Improvements

With games up-and-running, the project can only improve with your feedback, and by giving the right feedback, we can improve the playing experience for everyone involved. There are a number of areas where you can assist;

Erroneous Game Names

The easiest of these, to contribute to. The UAE Config Maker has to try and be a little 'smart' with the naming of games, sometimes expanding shortened folder name back into 'real' names that *might* be correctly picked up by the RetroPie scraper (if we are lucky.)

Unfortunately, trying to code a system that expands 2600+ shortened game names back into something correct isn't wholly reliable, so occasionally a manual input/modification is required. This is achieved through a 'list' system of 'bad names' and 'corrected names' which can be contributed to, through the following files:

You can add a name directly onto the list on GitHub, and submit a 'pull' request for your addition to be implemented. This will immediately be reflected in updated files generated from the UAE Config Maker.

Individual Game Settings

You will notice that the default screen size setting might not be the optimal (200px tall)... it would be great if every Amiga game used the same screen size, but they dont, and some will have too much 'black border' if the setting is too big, and some will get cropped if the setting is too low.

Thankfully, the UAE Config Maker is designed to read from a list of games, in individual text files, that can overwrite the default values.

So if you identify a bunch of games that need 256 pixel screens, just feed back the name of the WHDLoad game folder and post them to me. Your feedback will then be reflected on the next UAE Config Maker and Game Pack distributions.

Similarly, let me know any games that don't work, or need game-specific configuration changes.

WHDLoad Configuration Settings

One for those users already familiar with WHDLoad.... if you spot a game that doesn't allow you to change settings (for trainers, controls etc) , but yet you know the WHDLoad slave supports it, let us know. (See above - Tips and Trick on Running - Additional Information.)

'Host' options not available

Where .uae options are available, but cannot currently be selected from hostconfig.uaetemp but are deemed 'suitable' , please raise an issue /request on GitHub for it's inclusion. The UAE Config Maker does not currently allow all options to be selected in this way, but we will try to include any that are deemed suitable.