retrokit provides software automation for the management of retro-gaming systems with RetroPie / Raspberry Pi 4 using currently known best practices as I understand them.
Specifically, it can set up:
- Cases (e.g. Argon, NESPi, GPi 2), including safe reset/shutdown
- Controllers (including autoconfig for advmame, drastic, hypseus, mupen64plus, ppsspp, redream, and ir)
- IR configuration
- VNC
- Splash screens (async loading process, reduces load time by 2s)
- Scraping (via skyscraper) with automated fallback queries
- Retroarch configuration
- EmulationStation configuration
- Overlays / Bezels (with lightgun-compatible auto-generation)
- Cheats (pre-selected for RetroArch, MAME, NDS, etc.)
- HiScores for MAME
- Multi-Tap devices
- Port selection based on input (libretro cores, drastic, ppsspp, redream, mupen64plus, and hypseus)
- ROM Playlist (m3u) auto-generation for multi-disc games
- In-game manuals
- System controller reference guides
- Printable gamelists
- Launch images
- Emulator installation
- EmulationStation Collections (including lightguns)
- Sinden lightgun autoconfiguration
- Playstation GunCon patches (PPF)
- Xbox bluetooth support + customizations
- Game state (import/export)
- Autoconfig overrides
- Unified safe reset (quit) hotkeys across all emulators via joystick/keyboard
- Bluetooth
- SSH + AutoSSH for remote management
- Themes
- Display settings
- Wifi
- Overclocking
- Localization
- Custom Retropie modules
- Profile-based overrides
- Various fixes / workarounds for many common issues
It also provides ROM management capabilities, including:
- Advanced filtering
- Clone mappings for redump DATs
- Emulator assignment / compatibility ratings
- Core options overrides
- Retroarch overrides
- Remapping overrides
- Non-merged ROM building (via split / merged / non-merged sources)
- Installation via public rom sets (using individual ROM downloads)
- Installation via public bios sets
- Simple sub-directory management based on filters
- High-performance multi-threaded downloads
- Automatic resolution of name differences between DATs and public rom sets
Additionally, it provides Game Manual management capabilities, including:
- Installation via public manual sets
- In-game viewing and control of manuals via keyboard and joysticks
- OCR'd / Searchable PDFs
This is all supported for the following systems:
- Arcade
- Atari - 2600
- Atari - 7800
- Atari - Jaguar
- Atari - Lynx
- Coleco - ColecoVision
- Commodore - 64
- Daphne
- GCE - Vectrex
- Mattel - Intellivision
- NEC - PC Engine / TurboGrafx-16
- Nintendo - DS
- Nintendo - Game Boy
- Nintendo - Game Boy Advanced
- Nintendo - Game Boy Color
- Nintendo - Nintendo 64
- Nintendo - Nintendo Entertainment System
- Nintendo - Super Nintendo Entertainment System
- Panasonic - 3DO
- PC - DOS
- Philips - Videopac
- Sega - 32X
- Sega - CD
- Sega - Dreamcast
- Sega - Game Gear
- Sega - Genesis / MegaDrive
- Sega - Mastersystem
- Sega - Saturn
- Sega - SG-1000
- SNK - Neo Geo Pocket
- Sony - PlayStation
- Sony - PlayStation Portable
There are also system-specific features, including:
- Automatic joystick selection for Commodore 64 via C64 Dreams project
- Automatic integration of eXoDOS configurations for PC games
- Automatic selection of the best emulator per-game for Arcade, Atari Jaguar, and N64
- Automatic filtering of runnable games for 3DO, PSP, Sega Saturn, and more
- Automatic multi-tap support for NES, SNES, MegaDrive, and Playstation
- Automatic per-game port selection based on predetermined input types
- Optimized settings per-game for Arcade, Atari Jaguar, C64, N64, and more
- Conversion of ISO-based ROMs to CHD for Dreamcast, PCEngine, PSX, and SegaCD
- Conversion of ISO-based ROMS to CSO for PSP
- DLC support for PSP (PSN) ROMs
All of this means you can set up your system from scratch to feature-complete with less than a few hours worth of work. The automated scripts could take days to complete depending on the size of your game collection.
This is built for RetroPie / Raspberry Pi 4. You must customize it to your own needs.
NOTE This repository does not contain ROMs or URLs to websites that provide ROMs. To utilize any download functionality in retrokit, you must provide the configurations yourself. Please familiarize yourself with the law in your country before attempting to download ROMs.
When I started creating my own RetroPie system, I wanted to build it in such a way that I could re-create the exact same setup steps each time. As it turns out, there's a lot involved in building out the perfect Raspberry Pi 4 system.
retrokit, romkit, manualkit, powerkit, launchkit, sindenkit, and all of the supporting tools represent the work I did to build a configuration management system for my personal setup.
For a demo of what the end result looks like, see here.
You can use this just for romkit or you can use it for retrokit and romkit.
You will need to provide a .env
file with the appropriate details filled out.
In order to not encourage improper use of the ROM downloader (via romkit), you
must provide the source rom set URLs yourself.
Go through the settings and setup modules and become familiar with what this does.
If you have a proper .env
file, you can get a fully working system with very
little effort. However, understand that this is opinionated software. It uses
the default settings that I prefer and is configured by default for my hardware
setup.
The default hardware setup assumes:
- Raspberry Pi 4
You can have complete control over what parts of retrokit get used via everything
in the config/
folder, particularly config/settings.json
.
I strongly recommend using profiles to customize your configuration. That being said, feel free to fork this repo and use your fork to update and track all of your personal preferences.
- Override settings in
profiles/mykit/
to match your personal preferences and hardware requirements - Create a
.env
file based on env.template to provide the required configuration settings - Flash new image (Note this will also expand the main partition and copy retrokit
onto the sd card):
bin/sd.sh create /path/to/device # e.g. /dev/mmcblk0
- Insert sd card into Pi
- Start up Pi
- Quit EmulationStation (F4)
- Update Raspbian
retrokit/bin/update.sh system
- Reboot
sudo reboot
- Update RetroPie-Setup and its packages
retrokit/bin/update.sh retropie
- Run retrokit
retrokit/bin/setup.sh install
- Reboot
sudo reboot
- Have fun!
To access via VNC:
- Open in VNC client:
<ip address of rpi>:5900
Alternatively, you can run the retrokit setup script via the RetroPie EmulationStation menu.
- Clone repo
cd $HOME git clone https://github.com/obrie/retrokit
- Follow steps from base image install
- Download scriptmodule
curl https://github.com/obrie/retrokit/raw/main/bin/scriptmodules/supplementary/retrokit.sh --create-dirs -o $HOME/RetroPie-Setup/ext/retrokit/supplementary/retrokit.sh curl https://github.com/obrie/retrokit/raw/main/bin/scriptmodules/supplementary/retrokit/icon.png --create-dirs -o $HOME/RetroPie-Setup/ext/retrokit/supplementary/retrokit/icon.png
- Install script module via UI or:
sudo /home/pi/RetroPie-Setup/retropie_packages.sh retrokit _source_
- Follow steps from base image install
setup:
bin/setup.sh <action> <module> <args>
# Install all setup modules
bin/setup.sh install
# Install specific setup module
bin/setup.sh install splashscreen
# Install a range of setup modules (from splashscreen onward)
bin/setup.sh install splashscreen~
# Install a range of setup modules (based on order in config/settings.json)
bin/setup.sh install splashscreen~runcommand
# Install all system-specific setup modules for all systems
bin/setup.sh install system
# Install all system-specific setup modules for single system
bin/setup.sh install system n64
# Install all rom-specific setup modules for single system
bin/setup.sh install system-roms n64
# Install specific rom setup module for all systems
bin/setup.sh install system-roms-download
# Uninstall all setup modules
bin/setup.sh uninstall system
# Uninstall specific setup module
bin/setup.sh uninstall splashscreen
# Run specific function in a setup module
bin/setup.sh configure system-retroarch n64
# Add (very) verbose output
DEBUG=true bin/setup.sh install splashscreen
romkit:
bin/romkit.sh <action> <system> <options>
# List filtered ROMs for all systems
bin/romkit.sh list
# List filtered ROMs for specific system
bin/romkit.sh list n64
# Set verbose mode
bin/romkit.sh list n64 --log-level DEBUG
# Download/Install ROMs
bin/romkit.sh install <system>
# Re-build the ROM folder structure
bin/romkit.sh organize <system>
# Print which ROM files are no longer needed according to system settings
bin/romkit.sh vacuum <system>
update:
# Update RetroPie-Setup, RetroPie packages, and the OS
bin/update.sh
# Update RetroPie-Setup and its packages
bin/update.sh retropie
# Update just RetroPie-Setup
bin/update.sh retropie_setup
# Update just RetroPie packages
bin/update.sh packages
# Update just the OS
bin/update.sh system
# Update emulator configurations (after emulator package updates)
bin/update.sh emulator_configs
cache:
# Delete everything in the tmp/ folder
bin/cache.sh delete
# Update no-intro DATs based on Love Pack P/C zip
bin/cache.sh sync_nointro_dats /path/to/love_pack_pc.zip
sd:
# Create new SD card with RetroPie on it
bin/sd.sh create /path/to/device
# Back up SD card
bin/sd.sh backup /path/to/device /path/to/backup/folder
# Restore SD card
bin/sd.sh restore /path/to/device /path/to/backup/folder
# RSync files from the retropie partition to another directory
# (recommend sudo for long-running ops)
sudo bin/sd.sh sync_full /path/to/mounted_retropie_source /path/to/retropie_target
# RSync media files only from the retropie partition to another directory
# (recommend sudo for long-running ops)
sudo bin/sd.sh sync_media /path/to/mounted_retropie_source /path/to/retropie_target
vacuum:
# Vacuum ROM files no longer needed
bin/vacuum.sh roms | bash
# Vacuum manuals for ROMs no longer installed
bin/vacuum.sh manuals | bash
# Vacuum scraper cache for ROMs no longer installed
bin/vacuum.sh media_cache | bash
# Vacuum scraped media for ROMs no longer installed
bin/vacuum.sh media | bash
# Vacuum overlays for ROMs no longer installed
bin/vacuum.sh overlays | bash
# Vacuum game state for ROMs no longer installed
bin/vacuum.sh gamestate | bash
migrate:
# Migrate filenames after updating to newer system DAT files
bin/migrate.sh
# Migrate a specific system
bin/migrate.sh nes
Common commands:
# Update RetroPie and configs
bin/update.sh retropie
bin/update.sh emulator_configs
# Update system
bin/update.sh system
# Update retrokit
bin/update.sh retrokit
# Install/Update system
bin/setup.sh install <system>
# Update custom scriptmodules
bin/setup.sh install retropie-scriptmodules
# Re-do everything
bin/update.sh system
bin/update.sh retropie
bin/update.sh emulator_configs
bin/setup.sh install
# Re-create reference documentation
bin/setup.sh update system-docs
bin/setup.sh update system-roms-docs
To override any configuration settings, you have two options:
- Modify the settings directly in retrokit's
config/
directory - Create a profile that defines overrides which will be merged into
or overwrite retrokit's
config/
settings.
Profiles are a way of overlaying retrokit's default configuration settings with your own custom settings. It does this by either merging your settings on top of the default settings or completely overwriting the default settings, depending on what makes most sense.
The default profile is called mykit
as defined in the PROFILES
environment
variable in .env.template
.
The profile directory is structured like so:
profiles/
profiles/{profile_name}
profiles/{profile_name}/{config_file}
profiles/{profile_name}/{config_dir}/{config_file}
The directory structure is meant to mirror that of the folder at the
root of this project. For example, suppose you wanted to change which systems
were installed. To do so, you would define a settings.json
override:
profiles/mykit/config/settings.json:
{
"systems": [
"nes",
"snes"
]
}
These settings will be merged into config/settings.json
and then used throughout the project.
You can even define multiple profiles. For example, support you wanted to define
a "base" profile and then layer customizations for different systems on top of that.
To do that, add something like this to your .env
:
PROFILES=mykit/base,mykit/crt
# PROFILES=mykit/base,mykit/hd
In the examples above, a mykit/base
profile defines overrides that you want to use for
all of your profiles. A mykit/crt
or mykit/hd
profile then defines overrides that you want
to use for specific hardware configurations.
In general, anything under config/
can be overridden by a profile. The following
types of files will be merged into the defaults provided by retrokit:
- env
- ini
- json
The following specific configurations will be overwritten entirely by profiles:
config/controllers/inputs/*.cfg
config/localization/locale
config/localization/locale.gen
config/localization/timezone
config/skyscraper/videoconvert.sh
config/systems/mame/default.cfg
config/systems/mame2016/default.cfg
config/themes/*
config/vnc/*
config/wifi/*
In addition to overriding configuration settings, you can also override binaries that are related to configuration settings. This includes:
- Retrokit setup scripts
- Custom RetroPie scriptmodules
- RetroPie controller autoconfig scripts
- Sinden controller scripts
These scripts are expected to be located in a bin/
path under your profile's
directory with the same structure as retrokit's. For example, to add a new setup
script for your profile, you can configure it like so:
profiles/mykit/config/settings.json:
{
"setup": [
"...",
"mycustomscript"
]
}
You would then create your setup script under profiles/mykit/bin/setup/mycustomscript.sh
to match the same structure as retrokit's bin/
folder.
Environment variables can be defined in 3 places:
- Current shell environment
- .env at the root of this project
- .env at the root of profiles/{name}/
Which environment variables take priority largely depends on how you've defined
your environment variables. If your .env
is configured like so:
export PROFILES=filter-demo
...then PROFILES
will always be "filter-demo"
regardless of the current shell
environment. To instead respect the current environment, you can change the format
to:
export PROFILES=${PROFILES:-filter-demo}
Beyond building profiles for your own personalized systems, profiles could also pave the path for adapting retrokit to systems beyond the Raspberry Pi 4. If you have a profile that you'd like to share for others to use, please let me know and I'd be happy to add it to the documentation in this repo.
Since the standalone emulators are always going to work slightly differently than libretro cores, I have a cheat sheet to remind me how to use the system:
System | Keyboard | Controller |
---|---|---|
advmame | Hotkey + Start (once) | Hotkey + Start (once) |
dreamcast | ESC | Select (to Menu) |
n64 (mupen64plus) | ESC | Hotkey + Start |
pc | CTRL+F9 | None |
nds | ESC | Right Analog Left (to Menu) |
psp | ESC | Right Analog Left (to Menu) |
manuals | Hotkey + Up | Hotkey + Up |
* | Hotkey + Start (twice) | Hotkey + Start (twice) |
It's too easy to accidentally hit a single button during gameplay, so instead of exiting when pressing Right Analog Left, the emulator will always go to its native menu.
System | Controller setup |
---|---|
c64 | Switch Port 1 / 2 controller with virtual keyboard (Select) |
intellivision | Switch Left / Right controller with Select |
nds | Only the last configured joystick will be set up |
psp | Only the last configured joystick will be set up |
videopac | Requires 2 controllers (Left / Right controller is game-specific) |
Please note that due to limitations in how controllers are set up in NDS (Nintendo DS)
and PSP (PlayStation Portable), retrokit can only automatically configure one
controller. The last configured controller input under .hardware.controllers.inputs
in config/settings.json will be used.
Other controllers can still be used, but you must either manually configure it in the emulator's UI or use the same button mappings for all controllers.
System | Keyboard | Controller |
---|---|---|
arcade - rgui | Hotkey + X | Hotkey + X |
arcade - mame | Tab | L2 |
dreamcast | Select | Select |
nds | Tab | Right Analog Left |
psp | N/A | Right Analog Left |
* | Hotkey + X | Hotkey + X |
The following libretro MAME emulators support viewing the menu with a controller:
- lr-mame2015
System | Emulator | How to Cheat |
---|---|---|
arcade | lr-fbneo | Options menu in Retroarch GUI |
arcade | lr-mame* | Cheats menu in MAME GUI |
dreamcast | redream | Cheats menu in Redream GUI |
nds | drastic | Cheats menu in Drastic GUI |
psp | ppsspp | Cheats menu in PPSSPP GUI ("Import from cheat db") |
* | lr-* | Cheats menu in Retroarch GUI |
Cheats are not supported on the following systems / emulators:
- 3do
- arcade - lr-mame2010
- atarijaguar
- c64
- intellivision
- n64 - mupen64plus standalone
- sg-1000
- vectrex
- videopac
Please note that this process has only been tested with an Ubuntu-based laptop for flashing the sd card.
In addition to installing tools for managing hardware like fan speed within cases, retrokit also includes a service called powerkit which manages safe shutdown of your system.
There are 2 buttons that powerkit understands: reset and shutdown. The function of reset varies depending on the context in which the system is running:
- If an emulator is running,
reset
will terminate the emulator - If EmulationStation is running,
reset
will restart EmulationStation - If neither an emulator nor EmulationStation is running,
reset
will restart the OS
On the other hand, shutdown
will always be interpreted as a request to gracefully
turn off the system.
Keep in mind that the actual buttons that trigger a reset
or shutdown
will vary
based on case:
Case | Function | How to trigger |
---|---|---|
nespi | reset | Press the "Reset" button |
nespi | shutdown | Press the "Power" button |
argon1 | reset | Double tap the Power button |
argon1 | shutdown | Hold the Power button for 3+ seconds |
gpi2 | shutdown | Switch power to off |
To identify your controller names and ids, there's unfortunately no easy way out of the box that I'm aware of. However, you can follow the instructions here: https://askubuntu.com/a/368711
Here's a simplified version you can run:
cat > sdl2-joystick.c <<EOF
#include <SDL.h>
int main() {
SDL_Init(SDL_INIT_JOYSTICK);
for (int i = 0; i < SDL_NumJoysticks(); ++i) {
SDL_Joystick* js = SDL_JoystickOpen(i);
SDL_JoystickGUID guid = SDL_JoystickGetGUID(js);
char guid_str[1024];
SDL_JoystickGetGUIDString(guid, guid_str, sizeof(guid_str));
const char* name = SDL_JoystickName(js);
printf("%s \"%s\"\n", guid_str, name);
SDL_JoystickClose(js);
}
SDL_Quit();
}
EOF
gcc -o sdl2-joystick sdl2-joystick.c `pkg-config --libs --cflags sdl2`
./sdl2-joystick
Alternatively, you can either:
- Find your controller in the SDL controller database or
- Set up your controllers through EmulationStation
If you're not familiar with SDL GUIDs, setting up your controllers through EmulationStation is probably the best way.
You can configure your controllers through config/settings.json
like so:
{
"hardware": {
"controllers": {
"inputs": [
{
"name": "Keyboard"
},
{
"name": "Xbox 360 Controller",
"id": "030000005e0400008e02000014010000",
"description": "8Bitdo X-Input, Wired, Triggers to Buttons, Xbox layout (Arcade Stick)",
"swap_buttons": false
},
{
"name": "Xbox One Controller",
"id": "050000005e040000fd02000030110000",
"description": "8Bitdo X-Input, Bluetooth, Triggers to Buttons, Xbox layout (Arcade Stick)",
"swap_buttons": false
},
{
"name": "8Bitdo SN30 Pro",
"id": "05000000c82d00000161000000010000",
"description": "8Bitdo D-Input, Bluetooth, Nintendo Layout",
"swap_buttons": true,
"axis": {
"ABS_X": 128,
"ABS_Y": 128,
"ABS_Z": 128,
"ABS_RZ": 128
}
}
]
}
}
}
RetroPad Button | Key |
---|---|
A | X |
B | Y |
X | S |
Y | A |
Start | Enter |
Select | Space |
LS (L) | Q |
RS (R) | W |
LT (L2) | 1 |
RT (R2) | 2 |
Hotkey: Select
References:
In some cases, you may want to prioritize the order in which specific controllers are chosen as Player 1, Player 2, etc. For example, you may have:
- Controllers for specific systems
- Lightgun controllers for lightgun games
- Trackball inputs for trackball games
- etc.
To support this, you can use a feature built into retrokit called autoport
. Autoport uses
pre-configured profiles to determine the priority order of joystick and mouse devices when
starting up a game. You will find these configurations located here:
Scope | retrokit path | RetroPie path |
---|---|---|
Global | config/autoport/autoport.cfg | /opt/retropie/config/systems/all/autoport.cfg |
System | config/systems/{system}/autoport.cfg | /opt/retropie/config/systems/{system}/autoport.cfg |
Game | config/systems/{system}/autoport/{name | title}.cfg |
See config/autoport/autoport.cfg
for the examples and documentation on how to use this.
These configurations will be processed during the runcommand onlaunch
hook. It will prioritize
each of the above configurations like so (highest to lowest):
- Game
- System
- Global
When looping through the set of devices, autoport
will attempt to match as many inputs
of a particular name before it moves onto the next input name. If an input can't be found,
then it will move onto the next input.
This feature is supported on the following emulators:
- libretro cores
- drastic
- hypseus
- ppsspp
- redream
Game metadata comes from a variety of sources. When possible, retrokit caches those those sources instead of pulling from them directly. An overview of metadata and where it comes from is described below.
If possible, the preference would always be that retrokit/romkit is pulling from the source for all of the above metadata. However, some sources either aren't in a format that can be parsed (e.g. they're a forum post), don't allow direct downloads (e.g. dat-o-matic), or require an excessively large download to access a small file (e.g. pc dosbox configurations).
There are important differences between what's considered the parent and what's considered the clone between different systems.
No-Intro DAT files generally sort games based on the rules laid out here:
- Final/Complete > Proto/Beta/Demo
- Games containing En language > Other languages
- World > Continent/Multi Country > Country
- Old "main" console regions (EUR/USA/JPN) > Other countries (so i.e. Japan > Spain)
- Country with earlier dump available
- Highest revision
On the other hand, Redump DAT files are sorted chronologically based on the order in which they were dumped. Additionally, Redump does not provide clone metadata for its ROMs.
In order to (a) provide some consistency, (b) provide some stability in the metadata, and (c) make it easier to work with, the same general rules are applied to the custom clonelists generated for Redump DAT files.
The manuals used by this project were all hand-sourced from a variety of public websites. Only manuals that have been defined in the DAT files used by retrokit are included. All manuals are installed in PDF format, but they can be sourced from a variety of formats. Details about the process are described below.
The specific website used to source manuals largely depends on the system and the community based around it. Manuals often exist on many different websites and in different forms. In general, the follow priorities are used when determining which source to use:
- Quality: Higher quality > lower quality
- Resolution: Higher resolution > lower resolution (unless it's 600+ dpi)
- Color: Color > Black and White
- Watermark: Non-watermarked manuals > watermarked manuals
- Language: Single language > multi-language (unless it's just truncated)
- Archives: Archive.org sources > other sources
- Ownership: Community-owned websites > individually-owned websites
As you can see, there are a large number of considerations to keep in mind when identifying the appropriate source for each individual manual.
The following source formats are supported:
- cbz / zip
- cb7 / 7z
- cbr / rar
- html
- txt
- doc / docx / wri / rtf
- jpg / jpeg / png / gif / bmp / tif
Once downloaded, these formats will all be converted into PDF, maintaining the quality of the original manual when possible.
In order to support the long-term archival of manuals, all manuals referenced in this project have been archived on archive.org. This not only ensures that the manuals live beyond the life of their source projects, but also provides a more stable source to download manuals from. Over time, this archive will be updated to reflect additional manuals made available or new systems supported.
To generate archives:
PROFILES=manualkit-original bin/setup.sh install system-roms-manuals
PROFILES=manualkit-compressed bin/setup.sh install system-roms-manuals
Reference: https://archive.org/details/retrokit-manuals
For many manuals, the quality of the manual from the original source is higher than necessary for use in a typical retro gaming console. While using the original manuals can sometimes be useful, there is a significant disk usage overhead associated with that. For this reason, the default configuration is to enable post-processing on manuals to reduce overall filesize.
The archive.org archives provide 2 already post-processed versions of manuals:
- Original quality
- Medium/High quality
If you want to configure your own post-processing configuration, you can still use the archive.org manuals by using a configuration like so:
config/settings.json:
{
"manuals": {
"archive": {
"url": "https://archive.org/download/romkit-manualkit/{system}/original.zip/{parent_title} ({languages}).pdf",
"processed": false
},
...
}
}
All manuals have been organized by system and categorized by language. Every manual has been
reviewed to identify which languages are included. The ISO 639-1 standard is used for
identifying languages. In general, regional identifiers are not included in the language
code unless it is significant for differentiating manuals. For example, en
generally refers
to US-based English manuals while en-gb
generally refers to non-US based English manuals.
The titles given to manuals are based on the parent title. There are, therefore, 2 main pieces of information for identifying a manual:
- Parent title (no modifier details)
- Comma-delimited list of languages
The logic for determining which manual to use for a specific ROM is largely based on language preference for the user, not the country identifiers in the ROM filename. The relevant retrokit configuration is:
"metadata": {
"manual": {
"languages": {
"priority": [
"en",
"en-gb"
],
"prioritize_region_languages": false,
"only_region_languages": false
}
}
},
By default, retrokit will prefer languages based on the priority order defined in the system's configuration. However, two additional settings are available to adjust this behavior:
prioritize_region_languages
- If set totrue
, this will prioritize languages according to the regions from the ROM name rather than the order defined in the configurationonly_region_languages
- If set totrue
, then this will only use manuals in languages associated with the region defined for the RM
manualkit
can be controlled by keyboard or controller. These settings can be modified in
config/manualkit/manualkit.cfg
. It's expected that the keyboard / joystick toggle
buttons will be pressed in combination with retroarch's configured hotkey
button. For
example, the default configuration expects that select
+ up
will be used to toggle the
display of the manual on the screen.
As far as I've been able to find, there doesn't exist any form of player instruction manuals for arcade games. You can attempt to cut out instructions from bezel artwork, but that's a very time consuming process that I haven't undertaken. There do exist owner manuals for the arcade cabinets themselves, but that's not helpful to most players.
As an alternative, I've built manuals based on several sources:
- Cabinets from https://www.progettosnaps.net/cabinets/
- Flyers from https://www.progettosnaps.net/flyers/
- Select artwork from https://www.progettosnaps.net/artworks/
- Game initialization data from https://www.progettosnaps.net/gameinit/
The generated manuals aren't perfect, but I felt having some form of instructions was better than nothing. You can see how these manuals are generated in the generate_arcade_manuals.sh script.
If anyone has better sources or wants to build better manuals, I'd fully support that effort.
In addition to the game manuals themselves, reference "cheat" sheets have been created for each individual system with documentation on what controls / hotkeys are available for the system and how they map between the original controller and your controller.
The intention behind these reference guides is to make it easy to look up what controls are available rather than having to look up the controls in RetroPie or RetroArch documentation.
These guides include:
- System features available (e.g. cheats, netplay, etc.)
- Keyboard controls
- Hotkey configurations
- Images of the system's original controller
- Images of RetroArch's controller configuration
- Game-specific controller overrides
The guides are dynamically generated from your current configuration in RetroArch and additional system-specific configurations for:
- c64
- daphne
- n64
- nes
- pc
- pcengine
Additionally, there are ROM-specific guides available with special features, including:
- arcade: Joystick layout and button actions
With the Arcade reference guides, you can quickly pull up which buttons map to which actions within the game and have it drawn on the screen to match your own control panel layout.
All guides can be viewed by loading the manual via manualkit's configured hotkey and scrolling to the end of the manual (you can just go in reverse if you're on the first page of the manual). If the game has no manual, an image will be displayed saying "No Manual". However, you'll still be able to scroll forward to the reference guide.
In addition to manuals and reference sheets available per-game, printable documentation can also be generated. This documentation currently includes:
- Introduction to the system
- Game lists
In particiular, game lists are useful if you want others to be able to look through which games to play while someone is playing a game or controlling the system. Think of it like a karaoke playlist.
To generate the documentation, you can use the following command(s):
bin/docs.sh build [/path/to/output_dir/]
bin/docs.sh build_intro [/path/to/output.pdf]
This will generate PDF files in the docs/build
folder.
The filter-1tb
profile assumes that there is 1TB of capacity available for installing
ROMs. These filters generally have the following rules:
- 1G1R (one game per region)
- Excluded categories: Adult, Board games, Casino, Educational
- For CD-based systems, 1G1F (one game per franchise, e.g. sports franchies)
The approximate capacity required per system is broken down below:
System | Capacity |
---|---|
3do | 40GB |
arcade | 13GB |
atari2600 | 6MB |
atari7800 | 3MB |
atarijaguar | 125MB |
atarilynx | 11MB |
c64 | 135MB |
coleco | 3MB |
daphne | 23GB |
dreamcast | 113GB |
gamegear | 51MB |
gb | 61MB |
gba | 3.3GB |
gbc | 226MB |
intellivision | 2MB |
mastersystem | 41MB |
megadrive | 515MB |
n64 | 3.5GB |
nds | 36GB |
nes | 72MB |
ngpc | 17MB |
pc | 13GB |
pcengine | 11GB |
ports | 114MB |
psp | 230GB |
psx | 266GB |
saturn | 13GB |
sega32x | 64MB |
segacd | 35GB |
sg-1000 | 2MB |
snes | 633MB |
vectrex | 280KB |
videopac | 748KB |
Note that this does not include other data such as BIOS files / scraped media. It also only includes a selection of PC games.
If you wanted to include the entire PC collection, you would need another 500GB or so (so a 2TB drive).
Additional files:
Extra | Capacity |
---|---|
Covers | 2GB |
Manuals | 19GB |
Screenshots | 3GB |
Videos | 20GB |
Wheels | 660MB |
The following emulators / cores are built from source:
- lr-swanstation (unofficial, no binaries available yet)
- lr-yabasanshiro (unofficial, no binaries available yet)
Not all systems perform well on the Pi 4. Those with performance issues on some games include:
- 3do
- atarijaguar
- n64
- pc
- psp
- saturn
To the best of my ability, I've attempted to capture compatibility ratings and emulator selections for these systems to find the games that work pretty well. For these reasons, you'll find that these systems have fewer games installed than others.
For emulators that can experience poor performance on the Pi 4, there are ratings that have been gathered from various sources to identify which games work well and which games don't.
The ratings are roughly categorized like so:
Rating | Description |
---|---|
5 | Near perfection or perfection (no noticeable issues) |
4 | 1 or 2 minor issues |
3 | 1 or 2 major issues, but still playable |
2 | 3 or more major issues, not fun to play |
1 | Unplayable |
Some of this is subjective. For the most part, the defaults in retrokit avoid filtering for games that have major issues.
Game state can be quickly exported / imported using the system-roms-gamestate
setup module. Additionally, you can vacuum (i.e. remove unused game state) and
delete all game state using this module as well.
The export / import functionality currently supports either generating a single export ZIP file per system or a shared export file across all systems.
Below is some example usage:
# Remove unused game state for all systems (only prints commands, does not execute them)
bin/setup.sh vacuum system-roms-gamestate
# Remove unused game state for specific system
bin/setup.sh vacuum system-roms-gamestate nes
# Remove all game state (only prints commands, does not execute them)
bin/setup.sh remove system-roms-gamestate nes
# Generates a per-system export file to tmp/<system>/export.zip
bin/setup.sh export system-roms-gamestate
# Generates an export file to the given path
bin/setup.sh export system-roms-gamestate nes /path/to/export.zip
# Generates a single export file for all systems to the given path
bin/setup.sh export system-roms-gamestate /path/to/export.zip merge=true
# Imports, without ovewriting, game state for all systems
bin/setup.sh import system-roms-gamestate
# Imports game state for a specific system from the given path, without overwriting
bin/setup.sh import system-roms-gamestate nes /path/to/export.zip
# Imports *and* overwrites game state for a specific system / export path
bin/setup.sh import system-roms-gamestate nes /path/to/export.zip overwrite=true
This functionality could be enhanced in a large number of ways, or you can build some form of backup on top of this feature. The implementation is fairly straightforward since all of the work to identify the relevant game state files is already done.
There are so many people / resources that I've pulled over time to make retrokit what it is. That includes:
- Roslof's compatibility list for Arcade and Nintendo 64 emulator / configuration
- Progretto-Snaps for filtering arcade roms via categories, ratings, and languages
- C64 Dreams for Commodore 64 gamelists and configuration settings
- Abdessamad Derraz
- The Bezel Project for overlays
- ehettervik for the pixel theme
- TMNTturtleguy for the ComicBook theme
- DTEAM for Atari Jaguar settings
- valerino for lr-mess integration
- zerojay for lr-mess-jaguar scriptmodule
- Joshua Rancel for the default splash screen (Retro History)
- unexpectedpanda for clonelists
- ScreenScraper for game metadata
- Steven Cozart for arcade control maps (including Kevin Jonas, Howard Casto and yo1dog)
- Dan Patric for console logos
- Mark Davis for controller images
- Wikimedia for conroller images
- louiehummv for axis calibration fixes
- crcerror for alternate NesPi safe shutdown design
- meleu for joystick selection reference implementation
- lightgun.tech for lightgun configuration overrides
- eXo for Dosbox game configuration settings
- RetroPie forums
- Reddit forums
- ...and everyone who has put so much work in over the years to help make all of this even possible
There are too many improvements to count here, but some ideas are:
- Unify system metadata into a single file per system
- Move manualkit to sdl2
- Support for more systems (Amiga, Apple II, etc.)
- Support for non-Raspbian platforms
- Support different frontends (attractmode, pegasus)
- More comprehensive compatibility ratings
- Support axis controls in manualkit
If you want to make changes for your own specific setup, feel free to. I'll accept contributions for anything that will make it easier for you to customize this to your own setup.
Also, if you have improvements that will help everyone (e.g. perhaps there are better ways of doing autconfig for controllers), I'll happily review those.
- Wouldn't it be easier to just distribute an image?
This would be illegal. I'm not in the business of distributing ROMs illegally, only providing an system that makes it easier for you to legally manage your RetroPie.