User Tools
This is an old revision of the document!
Table of Contents
RetroFE documentation project
Welcome to the RetroFE documentation project. The purpose of this project is to provide documentation regarding the usage of the RetroFE front-end, and all its features.
RetroFE is a front-end, which can be used as a graphical user interface to display, select and launch your games, videos, and programs. Its most common usage is for game emulation. RetroFE allows you to define collections, which can be displayed using a menu structure with additional artwork like video, box art, screenshots, etc.
Basic Setup Instructions
- Download RetroFE either from : http://retrofe.nl/download (current and previous versions)
- Ordered List ItemExtract compressed image
- Edit the global settings.conf
- Edit controls.conf
- Run to verify the frontend loads (and exit)
- Edit or delete existing collections
- Move artwork and ROMs (if needed)
- Re-run RetroFE
Detailed Setup Guide
Installation
(Note for linux users: Since Linux comes in many shapes and sizes, RetroFE users need to compile and install their own RetroFE setup using bitbucket. The instructions for this can be found here.)
After copying the RetroFE system to the directory of your choice, you're set to give your installation a first test by running the retrofe executable in that directory. RetroFE comes with a pre-installed Sega Genesis system with one game so you can check if the installation went according to plan.
Configuration
The first configuration step is editing the RetroFE system configuration file RetroFE/settings.conf. In here you configure the screen settings, global theme, base paths, etc.
The second configuration step is editing the RetroFE controls file RetroFE/controls.conf. In here you configure the keys used to control the RetroFE front-end. Note that the default select key is space, and not enter as some people expected.
Adding collections
RetroFE starts with two (almost empty) collections, but more can be added easily. As an example, let's set up the Nintendo Entertainment System collection. First, enter the RetroFE/collections directory, and create an empty collection using the following command: ../retrofe -createcollection “Nintendo Entertainment System”
Next we add the roms and artwork:
Download a NES romset from your favourite source, and place the roms in the RetroFE/collections/Nintendo Entertainment System/roms directory. Download a device image, logo, and video for the system, and place the device.png, logo.png, and video.mp4 files in the RetroFE/collections/Nintendo Entertainment System/system_artwork directory. Download games artwork (artwork_front, logo's, screenshots, titleshots, videos, etc.) from your favourite art source, and place them in the RetroFE/collections/Nintendo Entertainment System/medium_artwork directory.
Now we configure the new system by editing RetroFE/collections/Nintendo Entertainment System/settings.conf. If you stick to the default directory structure, this file can be extremely simple:
list.extensions = nes
launcher = NES
The first line defines the ROM file extention as .nes; this should match the file extentions in your RetroFE/collections/Nintendo Entertainment System/roms directory. The second line defines the name of the launcher used for this collection. Before the collection can be used, this launcher needs to be configured:
Edit the RetroFE/launchers/NES.conf (matching the launcher name defined in the settings.conf) file. I'm currently using MAME 0.162 for this purpose, so the launcher can be simple:
executable = mame
arguments = nes -cart "%ITEM_FILEPATH%"
As an example: if RetroFE starts th game Willow (USA).nes, this launcher will execute the command:
mame nes -cart "RetroFE/collections/Nintendo Entertainment System/roms/Willow (USA).nes".
The last step is to add the newly created collection to the main menu by editing RetroFE/collections/Main/menu.txt, and add the following line:
Nintendo Entertainment System
When this is done, your newly added collection is ready for testing by running the retrofe executable RetroFE/retrofe.
Directory structure
Root folder
| File / Folder | Description |
|---|---|
| controls.conf | Controller configuration (up, down, select, back, etc) |
| log.txt | Log output |
| meta.db | Game information database (year, manufacturer, genre, #players, etc) |
| RetroFE.lnk | Windows link to core / retrofe.exe |
| settings.conf | Global frontend settings (display options, layout to use, base paths, etc) |
| /collections/ | Game lists, menus, artwork and ROMs |
| /core/ | Windows specific libraries needed for retrofe to run (also includes retrofe.exe) |
| /launchers/ | Configuration files for launchers (emulators) |
| /layouts/ | Layouts / themes to use or display for the frontend |
| /meta/ | Files to import into meta.db (for scraping) |
Collection folder
| File / Folder | Description |
|---|---|
| info.conf | This file can be used to add additional system information, such as manufacturer, year, generation, etc. that can be displayed from the theme layouts. This same information can also be defined within settings.conf, but this extra file allows for a clean separation of settings and system information. |
| include.txt | If not empty, include only those files to show on the list, if empty, all files in ROM folder will be included. This file must contain one game per line (without the file extension). |
| exclude.txt | List of ROMs to exclude from showing up on the menu (if you want this collection to be a menu of collections). This file must contain one game per line (without the file extension). |
| settings.conf | Set ROM file extensions, launcher (emulator to execute), override default media paths, etc |
| <collectionname>.sub | Imports a list of games from another collection. (i.e. Your collection is named “Mario”. You would have an “Nintendo Entertainment System.sub” and “Super Nintendo Entertainment System.sub”. Each sub file would contain a list of all mario games for that system. The .sub file contains one game per line (without the file extension).If the file is blank, the list settings defined for the subcollection will be used. |
Default collection artwork and ROM paths (can be overridden by editing your settings.conf)
| File / Folder | Description |
|---|---|
| roms | Default location to search for ROM files |
| medium_artwork/ | Artwork for individual games |
| medium_artwork/artwork_back | Default location to search for flyer, box and case backs |
| medium_artwork/artwork_front | Default location to search for flyer, box and case fronts |
| medium_artwork/medium_back | Default location to search for disc and cartridge backs |
| medium_artwork/medium_front | Default location to search for disc and cartridge fronts |
| medium_artwork/screenshot | Default location to search for screenshots for each individual game |
| medium_artwork/screentitle | Default location to search for screentitles for each individual game |
| medium_artwork/logo | Default location to search for logos for each individual game |
| medium_artwork/video | Default location to search for videos for each individual game |
| medium_artwork/story | Default location to search for game information story txt files for scrolling text display. |
| system_artwork/ | Artwork for the system collection. i.e. a picture of a Nintendo Entertainment System, its logo, or a “best of” video. |
| system_artwork/device.png | Picture of the system device |
| system_artwork/logo.png | Picture of the systems logo |
| system_artwork/video.mp4 | Video to play for this particular system |
| system_artwork/story.txt | Text file containing system information for scrolling text display. |
Collections
About Collections
A collection defines a set of games or menu level that generally have a common purpose, e.g. “Nintendo Entertainment System” or “Consoles”. RetroFE generally supports 3 types of collections:
- (Sub-)Menu collections
- ItemGames collections
- ItemSub/Merged collections
These types can be combined in one collection though, by simply having the required elements of more types in one collection.
(Sub-)Menu collections
A (sub-)menu collection is used to create a hierarchical level within your menu structure, e.g. Main→Consoles→Nintendo Entertainment System. It is defined by the menu.txt file as described in Menus. Since older versions of RetroFE supported a menu.xml file in stead, such legacy support still exists within RetroFE, but using a menu.txt file is easier.
Games collections
Games collections are collections consisting of the games, e.g. for a certain system like “Nintendo Entertainment System”. It uses the contents of the rom directory in combination with the include.txt and exclude.txt file in the following manner:
If list.includeMissingItems in the settings.conf is false:
- Read the contents of the rom directory.
- Keep only the names defined in include.txt.
- Remove the names defined in exclude.txt.
If list.includeMissingItems in the settings.conf is true:
- Use the names defined in include.txt.
- Remove the names defined in exclude.txt.
Sub/Merged collections
Sub collections contain a subset of other collections, e.g. Capcom Play System I can be set up as a sub-set of MAME. The sub-collection is defined by a <collection>.sub file, e.g. “Nintendo Entertainment System.sub”.
By using multiple .sub files you can also create a merged collection, e.g. all Contra games from different systems. You could have a “Nintendo Entertainment System.sub” file containing all the Contra games from the NES, and a “Super Nintendo Entertainment System.sub” file containing all the Contra games from the SNES. RetroFE will merge these collections into one.
A .sub file is simply a text file containing a list of game names, similar to the include.txt file, but rom file, art files, etc. will be pulled from the collection it refers to.
Example: You have a MAME collection, and wish to add a “Capcom Play System III” sub-collection.
- Create the “collections/Capcom Play System III” directory.
- Add a settings.conf file; this file can be empty or just contain some system information.
- Add your system_artwork.
- Create a MAME.sub text file containing:
jojo jojoba redearth sfiii sfiii2 sfiii3
- Add the “Capcom Play System III” to your Main's menu.txt like you would with any other collection. Enjoy your new sub collection. :)
PS: If a .sub file is empty, it will use merge that entire collection according to the rules defined above for Games collections.
Playlists
RetroFE currently supports one type of playlist: A list of your favorite games. This file is located in playlists/favorites.txt, and will be automatically created when you add your first game to the list. The controls configuration allows you to assign keys to add games to this list, remove them from this list, and switch between the full list and this playlist. A setting in the general settings.conf allows you to automatically switch to your favorite games if this list exists. Support for more playlists is planned in a future release.
