Configuration overload
Recalbox 7.0 and higher!
Starting from Recalbox 7.0, you can overload the configuration of a game or an entire directory.
That means that by adding certain files in your ROMs directories, you will be able to modify the way Recalbox, Retroarch or the emulator behaves for a given game, or all the games in that directory.
Basically, you'll be able to modify:
The Recalbox's configuration
The Retroarch's general configuration
The Retroarch's cores configuration
You will also have the possibility of overloading the images and descriptions of the rom directories as they are displayed in EmulationStation, we will see why just a tad later.
We'll be able to, for a game or a group of games:
Define a particular emulator or core
Define a particular video resolution
Modify Retroarch's video configuration
Modify core options
etc
The overloads are going to apply on a base file. Those files are the files loaded first in the python launcher (called configgen) when we launch a game:
Target | Configuration file |
Recalbox |
|
Retroarch |
|
Cores |
|
All the config files that we can overload are of type key/value. We'll then be able to modify the value of a key from the base file, or define a non-existent key.
We will even be able to overload overloads ! Indeed, the system allows you to define an overload per directory level.
So it starts by loading the basic configuration, then apply successively all the overload files it will find in the directories, starting at the root and finishing with the game overload, if it exists.
Let's take an example, if we launch the game /recalbox/share/roms/snes/platform/Aladdin (France).zip, configgen will try to overload the retroarch configuration, loading in order:
Base: /recalbox/share/system/configs/retroarch/retroarchcustom.cfgPath: /.retroarch.cfgPath: /recalbox/.retroarch.cfgPath: /recalbox/share/.retroarch.cfgPath: /recalbox/share/roms/.retroarch.cfgPath: /recalbox/share/roms/snes/.retroarch.cfgPath: /recalbox/share/roms/snes/platform/.retroarch.cfgFile: /recalbox/share/roms/snes/platform/Aladdin (France).zip.retroarch.cfg
Of course, it's not really advisable to overload the configuration before reaching at least the directory of a system.
You will notice that to overload a directory, the overload files must be found inside the directory, starting with a dot (.), which makes them invisible to the linux system.
Conversely, the overload of a game must be named exactly like the game, including the file extension, followed by the overload suffix, .retroarch.cfg in the example above.
Since the overload files are inside your roms directories, they don't risk a Recalbox crash, an update that went wrong, or a crash of your SD-card (provided you use external support of course).
They are also portable : Take your USB-drive with you to play at a friend's house, your configuration will apply automaticaly !
Overloading the Recalbox configuration has two immediate benefits :
Be able to select a particular video mode for a game or set of games. Aficionados of the arcade pixel perfect will be delighted.
Be able to choose a core or a standalone emulator for a game or a set of games.
There are other possibilities and no doubt you will find some.😉
Overloading keys that aren't used by the configgen has no impact ! Don't expect to change the behavior of EmulationStation (overloading the sorts for example).
Reminder :
Directory overload : /path/to/your/roms/.recalbox.conf
Rom overload : /path/to/your/roms/file.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
Simply add the file :
/recalbox/share/roms/mame/MAME2003Plus/.recalbox.confmame.emulator=libretromame.core=mame2003_plus
And the file :
/recalbox/share/roms/mame/MAME2010/.recalbox.confmame.emulator=libretromame.core=mame2010
And there it's ! That's all.
Now, all the games in the MAME2003Plus directory will launch with the mame2003_plus-libretro core, and those in the MAME2010 directory will launch with the mame2010-libretro core !
Let's say for the sake of our example that my game /recalbox/share/pcengine/1943 Kai (Japan).zip works better with the core mednafen_pce_fast_libretro than with the default one mednafen_supergrafx_libretro .
Until now, it was possible to do it via EmulationStation, by editing the game's metadata. The information is then stored in the gamelist.xml file. But with one error in writing the file, an unfortunate scrap and it's all the configuration that is lost.
Here, simply add the file :
/recalbox/share/roms/pcengine/1943Kai(Japan).zip.recalbox.confglobal.emulator=libretroglobal.core=mednafen_pce_fast
This time, there's no risk of losing configuration ! Of course, editing metadata via EmulationStation still works. On the other hand, an overload file will have higher priority than what is stored in the gamelist.xml.
Once again let's take an example !
On my Raspberry Pi2, the default video mode is CEA 4 HDMI.
But on the Blazing Stars game on FinalBurn Neo, it runs a bit slowly. Turning it to 240p would certainly help, in addition to being pixel-perfect.
/recalbox/share/roms/fba_libretro/blazstar.zip.recalbox.confglobal.videomode=CEA 8 HDMI
And voila ! Next time I launch this particular game, my TV will to adjust to 240p, and I can now fully enjoy Blazing Stars.
The Retroarch configurations concern Retroarch itself (and the configuration options are very large !) as well as the different cores, which each have specific options depending on the hardware they emulate.
There are already specific mechanisms in Recalbox and Retroarch to overload either the command line that launches the emulator (via Recalbox.conf), or directly the Retroarch/Cores configurations (via Retroarch menus).
But none of these systems allowed to apply the overloads to entire directories and/or to keep these specific configurations in the same place as the roms. Which is especially interesting for people who use network shares to supply roms to several Recalboxes
The Retroarch configuration itself is extremely rich and covers a lot of different fields.
There's no need to expand more on this, if you have any question simply go directly to the RetroArch file, which is particularly well documented : https://github.com/libretro/RetroArch/blob/master/retroarch.cfg
The possibilities offered by local overloads are huge ; among them are :
Video setup : Ratio, Scale, Anti-aliasing, screen rotation or even shader selections, etc.
Audio tuning for some tricky games
Overlays
Some options concerning the inputs : mouse selection, sensitivity, etc.
Forcing specific NetPlay configurations
Change Retroarch directories (e.g. backup)
Setup various options : Rewind, Fast Forward, etc.
...
Like the Recalbox configuration overloads, we will be able to create .retroarch.cfg files for directories and for roms.
Reminder :
Directory overload : /path/to/your/roms/.retroarch.cfg
Rom overload : /path/to/your/roms/file.zip.retroarch.cfg
Overloading the cores options offers huge possibilities, among which a feature highly expected by fans of "outdated computers" : the ability to specify a directory per sub-system !
Overloads of cores are added to the file share/system/configs/retroarch/cores/retroarch-core-options.cfg at the launch of the concerned game, which means that once the game is closed, they will be saved in this same file.
In order to avoid unpleasant surprises, we recommend overloading the keys in the folder with default values (e.g. fbneo-frameskip = "0") if you want to overload a particular game with specific values (e.g. fbneo-frameskip = "2").
This way, you will keep your "base" values for files that don't have custom overloads.
It's especially interesting for multi-hardware cores, such as :
theodore, which includes Thomson MO6, and TO8 up to TO9+.
atari800, which includes all the Atari 8bits, from the first 800 series, to the XE, through the XL, up to the XE.
vice, which now emulates C64, PET, Vic20, CBM2, ...
hatari, which emulates from the first 520ST to the last Falcons...
and many more...
Reminder :
Directory overload : /path/to/your/roms/.core.cfg
Rom overload : /path/to/your/roms/file.zip.core.cfg
The Thomsons, French 8bits computers of the 80s, have split into 2 series:
The MOs, which gave the first MO5, then later the MO6 with its mechanical keyboard and integrated tape player,
The TO, which gave the first TO7 and TO7-70, then later the TO8 and TO8D, with floppy disk drives, and the TO9 and TO9+ series, more professional-looking computers.
MO and TO games aren't compatible at all. Within the same series, there is upward compatibility : a MO6 will run the games of the MO5.
Of course, we will try to emulate each game with the hardware closest to the original machine it was designed for, 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), the Thomson games have been divided into 4 subsystems :
MO5
MO6
TO7 (TO7-70)
TO8, TO8D, TO9 et TO9+
We will therefore create a similar tree structure :
recalbox/share/roms/thomson/
├── MO5
├── MO6
├── TO7
└── TO8,TO8D,TO9,TO9+
In the root of the system, we will place a core overload file, to force some very cool options for everyone :
/recalbox/share/roms/thomson/.core.cfgtheodore_rom = "Auto"theodore_autorun = "enabled"theodore_floppy_write_protect = "enabled"theodore_tape_write_protect = "enabled"
If we add games in the root or in another directory, we indicate to the emulator to try to detect the best hardware.
We also protect the default roms files by default and we start the autorun mechanism which is very useful when we don't know the original hardware very well.
Then in each sub-directory, we will add an overload on the theodore_rom key which determines the hardware.
/recalbox/share/roms/thomson/MO5/.core.cfgtheodore_rom = "MO5"
/recalbox/share/thomson/MO6/.core.cfgtheodore_rom = "MO6"
/recalbox/share/thomson/TO7/.core.cfgtheodore_rom = "TO8"
/recalbox/share/thomson/TO8,TO8D,TO9,TO9+.core.cfgtheodore_rom = "TO9+"
For the TO7 series, the closest hardware has been selected : the TO8. For the last series (fully compatible), the most powerful hardware has been selected : the TO9+.
That's all ! You now have four Thomson subsystems. The emulator is no longer in automatic mode and the risk of choosing the wrong system or a default system vanishes.
Of course, the Theodore core can sometimes "auto-detect" the hardware, but this isn't the case with some other cores that need to have the right subsystem at launch.
To improve the possibilities offered by the subsystem settings, for instance by overloading the Recalbox configuration for MAME or overloading the Theodore core to fully take advantage of the TO and MO hardware of that time, we have added the possibility to overload the image and description of a directory.
This allows for example, to have on a directory, the picture and the description of the hardware whose roms are in the directory.
To do this, we just need to add at least one image file in PNG format and named .folder.picture.png in the directory whose image we want to overload in EmulationStation.
The resolution doesn't matter, but keep in mind that a resolution similar or close to your scrap images is still recommended.
You may add an optional text description that will slide underneath the image, just like for scraped games. The file must be a simple text file, named .folder.description.txt
Reminder :
Directory overload : /path/to/your/folder/.folder.picture.png
Rom overload : /path/to/your/roms/.folder.description.txt
Let's go back to the thomson directory used earlier, which we had divided into 4 sub-systems 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.picture.png
│ ├── .folder.description.txt
│ └── [K7]
├── TO7
│ ├── .core.cfg
│ ├── .folder.picture.png
│ ├── .folder.description.txt
│ ├── [K7]
│ └── [M7]
└── TO8, TO8D, TO9, TO9+
├── .core.cfg
├── .folder.picture.png
├── .folder.description.txt
├── [FD]
├── [K7]
├── [QD]
└── [SAP]
The .folder.picture.png file in the /recalbox/share/roms/thomson directory contains an image of the hardware :
And the file .folder.description.txt contains :
/recalbox/share/roms/thomson/MO5/.folder.description.txtBrand:- Thomson (France)CPU:- Motorola 6809E running at 1 MHzRAM:- 48Kb (extensible)ROM:- 16KbGraphics:- 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- JoysticksInterfaces:- External power supply- DIN Connector (optical pen)- DIN Connector (tape drive)- Peritel (RGB)- Extension portSoftware:- BASIC 1.0 IntegratedStandard devices:- Cartridge port (Mémo5)- External tape drive (MO5 specific model)- External disk driveDimensions:- 51 x 291 x 190 mmWeight:- 1.1 kgReleased:- 1984
And here's how it looks in EmulationStation :
In the same way, let's go back to our first example that shows how to get multiple versions of MAME in the MAME directory, we could imagine having nice MAME 2003 Plus and MAME 2010 logos, followed by a short text giving the amount of games, and the version of the corresponding MAME RomSet.
A little logo :
/recalbox/share/roms/mame/MAME2003Plus/.folder.description.txt
A little text :
/recalbox/share/roms/mame/MAME2003Plus/.folder.description.txtMAME 2003 Plus is an improved version of MAME 2003, with a whole lot of bug fixes and hundreds of new games.Special RomSet based on the MAME 0.78 RomSet4859 games total!
And there's the result :
We can't currently overload the configuration of standalone emulators except for Amiberry's and Amiga for ARM's, partially.
Adding these overloads isn't on the calendar, since they require code and specific tests. This more or less isn't doable for every emulator, but in any case, this will require a rather substantial amount of work time.
However, depending on the demand and its relevancy, we could eventually work on a per-case basis.
