 | The Amiga RetroPie WHDLoad Packs |
- An initial installation of Amiberry to RetroPie
- Download and install the WHDLoad Booter, and Game Data files to: home/pi/retropie/roms/amiga-data/
- 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
You will require RetroPie for this project, but for the purpose of demonstration, the initial RetroPie setup is included within the guide:
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:
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
<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
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 example games, 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.
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:
/home/pi/RetroPie/BIOS/Amiga/
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.
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
/home/pi/RetroPie/roms/
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:
/home/pi/RetroPie/amiga-data/_BootWHD/
A WHDLoad Games Pack
The .uae files here should be placed directly into:
/users/pi/RetroPie/roms/amiga
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:
/home/pi/RetroPie/roms/amiga-data
Packs containing over 2000 ECS Amiga games are available in the Downloads section, and have both pre-generated .uae files and the necessary game data available.
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:
/home/pi/.uaeconfigmaker
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.
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
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.
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 www.whdload.de ... for example: http://whdload.de/games/NewZealandStory.html 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.
Trouble-shooting
If you run into trouble at this point (games not appearing to load) try removing / deleting the following file:
/home/pi/RetroPie/amiga/_WHDBoot/devs/system-configuration
This will make Amiga DOS visible again, and you can report any errors seen via the group.
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
wget https://github.com/HoraceAndTheSpider/UAEConfigMaker/archive/master.zip
unzip master.zip
rm master.zip
mv UAEConfigMaker-master .uaeconfigmaker
Updating/Running:
From Linux Command Line or via SSH, enter the following:
cd /home/pi
cd .uaeconfigmaker
python3 update_config_maker.py
python3 uae_config_maker.py
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)
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.