You can override the configuration of a game or of an entire directory.
This means that by adding specific files in your roms directories, you will be able to modify the behavior of Recalbox, RetroArch or the emulator for a particular game or for all the games in a directory.
Concretely, you will be able to act on:
Incidentally, you will also have the possibility of overridding the images and the descriptions of the roms directories as they are displayed in EmulationStation, we will see how a little later.
For now, we will be able, for a game or a set of games:
The overrides will apply to a base file. These files are the files that are first loaded when you are launching a game:
Override file | Target | Configuration file |
---|---|---|
.recalbox.conf |
Recalbox | /recalbox/share/system/recalbox.conf |
.retroarch.conf |
RetroArch without core options | /recalbox/share/system/configs/retroarch/retroarchcustom.cfg.origin |
.core.cfg |
Core options | /recalbox/share/system/configs/retroarch/cores/retroarch-core-options.cfg |
All the configuration files that can be overrided are keys / values type files. We will therefore be able to modify the value of a key of the basic configuration, or define a non-existent key.
We can even override the overrides! Indeed, the system makes it possible to define an override per directory level.
It will therefore start by loading the basic configuration, then successively apply all the override files that it finds in the directories, starting at the root. Then in the end, it will try to apply the game override, if it exists.
Let's take an example, if we run the game /recalbox/share/roms/snes/platform/Aladdin (France).zip
, the configgen will try to override the RetroArch configuration, loading in order:
Base: /recalbox/share/system/configs/retroarch/retroarchcustom.cfg
Path: /.retroarch.cfg
Path: /recalbox/.retroarch.cfg
Path: /recalbox/share/.retroarch.cfg
Path: /recalbox/share/roms/.retroarch.cfg
Path: /recalbox/share/roms/snes/.retroarch.cfg
Path: /recalbox/share/roms/snes/platform/.retroarch.cfg
File: /recalbox/share/roms/snes/platform/Aladdin (France).zip.retroarch.cfg
Of course, it is not really advisable to override the configuration before reaching at least the directory of a system.
You will notice that in order to override a directory, the override files must be inside the directory, and start with a period (.).
Conversely, the override of a game, must be named exactly like the game, including the file extension, followed by the override suffix, .retroarch.cfg
in the example above.
Since the override files are located inside your roms directories, they won't be deleted or edited in case of a crash, a broken update, a reset factory or a crash of the SD card (assuming you are using an external drive for your data).
They are also portable: take your USB key with you to play at a friend's house, your configuration will apply without having to touch anything!
Overriding the Recalbox configuration has two immediate advantages:
There are other possibilities, and no doubt you will find some 😉
Overriding keys that are not used by the configgen will have no effect! Do not expect to modify the behavior of EmulationStation (by overriding sorts for example).
Directory override:
/path/to/your/roms/.recalbox.conf
Rom override:/path/to/your/roms/game.zip.recalbox.conf
Why settle for just one version of MAME when we could have them all?
For example, you could have MAME 2003 Plus and MAME 2010, each romset in its own directory:
┣ 📁 recalbox
┃ ┣ 📁 share
┃ ┃ ┣ 📁 roms
┃ ┃ ┃ ┣ 📁 mame
┃ ┃ ┃ ┃ ┣ 📁 MAME2003Plus
┃ ┃ ┃ ┃ ┣ 📁 MAME2010
Then just add the file /recalbox/share/roms/mame/MAME2003Plus/.recalbox.conf
with this content:
mame.emulator=libretro
mame.core=mame2003_plus
And the file /recalbox/share/roms/mame/MAME2010/.recalbox.conf
with this content:
mame.emulator=libretro
mame.core=mame2010
And there you go ! From now on, all the games in the MAME2003Plus directory will launch with the libretro-mame2003_plus core, and those in the MAME2010 directory with the libretro-mame2010 core.
My game /recalbox/share/pcengine/1943 Kai (Japan).zip
works better with core libretro-mednafen_pce_fast
core than libretro-mednafen_supergrafx
default core (totally arbitrary assumption for the example).
Until now, it was possible to do this via EmulationStation, by modifying the game's metadata. The information is stored in the gamelist.xml
file. A file write error, an unfortunate scrape, and the entire configuration is lost.
Here you just have to add the file /recalbox/share/roms/pcengine/1943 Kai (Japan).zip.recalbox.conf
with the following content:
global.emulator=libretro
global.core=mednafen_pce_fast
This time, no risk of losing the configuration! Of course, editing metadata via EmulationStation still works. On the other hand, an override file will have priority over what is stored in the gamelist.xml
file.
On Raspberry Pi2, the default video mode is CEA 4 HDMI. But on the game Blazing Stars
on FinalBurn Neo, it runs a bit slow. Switching it to 240p would certainly help, besides being Pixel Perfect (again, completely hypothetical, just for the example)!
We add in the file /recalbox/share/roms/fba_libretro/blazstar.zip.recalbox.conf
with the following content:
global.videomode=CEA 8 HDMI
When I run this game, my TV switches to 240p, and I can fully enjoy Blazing Stars
.
RetroArch configurations concern RetroArch itself (and the configuration options are very numerous!) As well as the different cores, which each have specific options depending on the machines they emulate.
There are already mechanisms specific to Recalbox and RetroArch to override either the command line which launches the emulator (via recalbox.conf), or directly the RetroArch / Cores configurations (via the RetroArch menus).
But none of these systems made it possible to apply the overrides to entire directories and / or to keep these specific configurations in the same place as the roms. This is particularly interesting for people who use network shares to supply roms to several Recalbox!
The Retroarch configuration itself is extremely rich, and covers a lot of different areas.
There is no need to dwell on the question, the best is to look directly in the RetroArch file, which is particularly well documented.
The possibilities offered by local overrides are enormous, among which we can count:
Like the Recalbox configuration overrides, we will be able to create .retroarch.cfg
files for the directories and for the roms.
Some N64 games like GoldenEye 007 or Perfect Dark as well as Palm games must have the Analog to Digital
option disabled.
You just need to add the file /recalbox/share/roms/n64/.retroarch.cfg
:
input_player1_analog_dpad_mode = "0"
input_player2_analog_dpad_mode = "0"
input_player3_analog_dpad_mode = "0"
input_player4_analog_dpad_mode = "0"
For a game, name the file like this: gamename.ext.retroarch.cfg
. For a whole system, .retroarch.cfg
is sufficient.
Overrideing the options of the cores offers enormous possibilities, among which a feature eagerly awaited by computer fans: the possibility of defining a directory per subsystem!
The cores overrides are added to the file
/recalbox/share/system/configs/retroarch/cores/retroarch-core-options.cfg
when the game in question is launched, this implies that, once the game is closed, they will be saved in this same file. To avoid any unpleasant surprises, we recommend overriding the keys in the directory with default values (for examplefbneo-frameskip = "0"
) if you want to override a particular game with specific values (for examplefbneo-frameskip = "2"
), so you'll keep your" base "values for files that don't have custom overrides.
This is particularly interesting for multi-machine cores, like:
You can find a list of available options for each core in the core page in the
Emulators
section of this wiki.
The Thomsons, 8-bit French computers from the 80s, were split into 2 series:
MO and TO games are not compatible at all. Within the same series, there is backward compatibility: An MO6 will (in general) run the games of the MO5.
Of course, we will try to emulate each game with the machine closest to the machine for which it was originally designed, in order to avoid any problems and maximize the chances of having a perfect emulation.
If we take the TOSEC packs(http://www.tosec.org), Thomson games have been divided into 4 subsystems:
We will therefore create a similar tree structure:
┣ 📁 recalbox
┃ ┣ 📁 share
┃ ┃ ┣ 📁 roms
┃ ┃ ┃ ┣ 📁 thomson
┃ ┃ ┃ ┃ ┣ 📁 MO5
┃ ┃ ┃ ┃ ┣ 📁 MO6
┃ ┃ ┃ ┃ ┣ 📁 T07
┃ ┃ ┃ ┃ ┣ 📁 TO8,T08D,T09,T09+
In the system root, we are going to place a core override file, to force some interesting options for everyone:
We will put in the file /recalbox/share/roms/thomson/.core.cfg
this content:
theodore_rom = "Auto"
theodore_autorun = "enabled"
theodore_floppy_write_protect = "enabled"
theodore_tape_write_protect = "enabled"
If we add games to the root, or to another directory, we tell the emulator to try to find the best machine (based on the name of the file).
We also protect the roms files by default, and we engage the mechanics of autorun, very practical when we do not know too much about the original machines.
Then in each sub-directory, we will add an override on the key theodore_rom
which determines the machine.
File /recalbox/share/roms/thomson/MO5/.core.cfg
:
theodore_rom = "MO5"
File /recalbox/share/roms/thomson/MO6/.core.cfg
:
theodore_rom = "MO6"
File /recalbox/share/roms/thomson/TO7/.core.cfg
:
theodore_rom = "TO7"
File /recalbox/share/roms/thomson/TO8,TO8D,TO9,TO9+.core.cfg
:
theodore_rom = "TO9+"
For the last series, the most powerful machine was selected: the TO9+.
It's over! You now have 4 Thomson subsystems. The emulator is no longer in automatic mode and the risk of it choosing the wrong system or a default system disappears.
Of course, the Theodore core can sometimes "auto-detect" the machine, but this is not the case with other cores which need to have the correct subsystem at launch.
To perfect the possibilities offered by the definition of subsystems, whether by overrideing the Recalbox configuration for MAME for example, or by overriding the Theodore core to take full advantage of the TO and MO machines of the time, we added the possibility to override the image and the description of a directory.
This allows for example, to have on a directory, the photo and the description of the machine whose roms are in said directory.
All you have to do is add at least an image file in PNG format, named .folder.picture.png
in the directory whose image you want to override in EmulationStation. The resolution does not matter, but keep in mind that the same or similar resolution to your scrape images is still recommended.
Optionally, you can add a text description, which will slip under the image, exactly like for scraped games. The file should be a simple text file, named .folder.description.txt
.
Let's go back to the thomson
directory used above, which we had split into 4 subsystems as TOSEC did.
┣ 📁 recalbox
┃ ┣ 📁 share
┃ ┃ ┣ 📁 roms
┃ ┃ ┃ ┣ 📁 thomson
┃ ┃ ┃ ┃ ┣ 🗒 .core.cfg
┃ ┃ ┃ ┃ ┣ 🗒 gamelist.xml
┃ ┃ ┃ ┃ ┣ 📁 media
┃ ┃ ┃ ┃ ┃ ┣ 📁 box3d
┃ ┃ ┃ ┃ ┃ ┣ 📁 images
┃ ┃ ┃ ┃ ┃ ┣ 📁 videos
┃ ┃ ┃ ┃ ┣ 📁 MO5
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .core.cfg
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .folder.description.txt
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .folder.picture.png
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [FD]
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [K7]
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [M5]
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [QD]
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [SAP]
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [WAV]
┃ ┃ ┃ ┃ ┣ 📁 MO6
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .core.cfg
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .folder.description.txt
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .folder.picture.png
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [K7]
┃ ┃ ┃ ┃ ┣ 📁 TO7
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .core.cfg
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .folder.description.txt
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .folder.picture.png
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [K7]
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [M7]
┃ ┃ ┃ ┃ ┣ 📁 TO8,TO8D,TO9,TO9+
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .core.cfg
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .folder.description.txt
┃ ┃ ┃ ┃ ┃ ┣ 🗒 .folder.picture.png
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [FD]
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [K7]
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [QD]
┃ ┃ ┃ ┃ ┃ ┣ 🗒 [SAP]
The .folder.picture.png
file in the /recalbox/share/roms/thomson
directory contains an image of the machine:
And the file /recalbox/share/roms/thomson/MO5/.folder.description.txt
contains:
Brand:
- Thomson (France)
CPU:
- Motorola 6809E running at 1 MHz
RAM:
- 48Kb (extensible)
ROM:
- 16Kb
Graphics:
- Text mode : 40 columns x 25 lines
- Graphic mode: 320 x 200, 16 colors (proximity constraint)
Sound:
- 1bit generator (6bit DAC module extention possible)
Input devices:
- 57 keys integrated keyboard
- Optical pen
- Joysticks
Interfaces:
- External power supply
- DIN Connector (optical pen)
- DIN Connector (tape drive)
- Peritel (RGB)
- Extension port
Software:
- BASIC 1.0 Integrated
Standard devices:
- Cartridge port (Mémo5)
- External tape drive (MO5 specific model)
- External disk drive
Dimensions:
- 51 x 291 x 190 mm
Weight:
- 1.1 kg
Released:
- 1984
And here is the result in EmulationStation:
In the same way, on the first example which shows how to have several versions of MAME in the MAME directory, we could imagine having a nice logo MAME 2003 Plus and MAME 2010, followed by a small text which gives the number of games, and the corresponding MAME romset version.
A small logo:
A short text in the file /recalbox/share/roms/mame/MAME2003Plus/.folder.description.txt
:
MAME 2003 Plus is an improved version of MAME2003, with huge bug fixes and hundreds of new games.
Romset Special based on the MAME 0.78 romset
4859 games in total!
And here is the result:
Currently, we cannot override the configuration of standalone emulators, except partially those of Amiberry, the Amiga emulator for ARM systems and Hatari which have its own overriding system in .hatari.cfg
files and works the same way.
There are no plans to add these overrides, as they require special code and tests. It is also not necessarily feasible for all emulators, but in all cases, it will require more or less time.
However, depending on the requests and their relevance, we may possibly see it on a case-by-case basis.