[W] Configuration overload

A description of local configuration overloads applied to select games or entire directories.

Recalbox 6.1 and up!

Possibilities overview

​

Starting from Recalbox 6.1, 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 the directory.

​

Basically, you are going to act on:

  • Recalbox's configuration

  • Retroarch's general configuration

  • Retroarch's cores configuration

​

Incidentally, you will also have the opportunity of overloading the images and descriptions of the ROM directories as they are shown in EmulationStation, we are going to go over why just a tad later.

​

In a jumble, 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.

​

Generalities

​

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

/recalbox/share/system/recalbox.conf

Retroarch

/recalbox/share/system/configs/retroarch/retroarchcustom.cfg.origin

Cores

/recalbox/share/system/configs/retroarch/cores/retroarch-core-options.cfg

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! En effet le système permet de définir une surcharge par niveau de répertoires. Il va donc commencer par charger la configuration de base, puis appliquer successivement tous les fichiers de surcharge qu'il trouvera dans les répertoires, en commençant à la racine. Puis au final, il tentera d'appliquer la surcharge du jeu, si elle existe.

​

Prenons un exemple, si on lance le jeu /recalbox/share/roms/snes/platform/Aladdin (France).zip, le configgen cherchera à surcharger la configuration retroarch, en chargeant dans l'ordre:

  1. Base: /recalbox/share/system/configs/retroarch/retroarchcustom.cfg

  2. Path: /.retroarch.cfg

  3. Path: /recalbox/.retroarch.cfg

  4. Path: /recalbox/share/.retroarch.cfg

  5. Path: /recalbox/share/roms/.retroarch.cfg

  6. Path: /recalbox/share/roms/snes/.retroarch.cfg

  7. Path: /recalbox/share/roms/snes/platform/.retroarch.cfg

  8. File: /recalbox/share/roms/snes/platform/Aladdin (France).zip.retroarch.cfg

Bien entendu, il n'est pas vraiment conseillé de surcharger les configuration avant d'atteindre au minimum le répertoire d'un système.

Vous remarquerez que pour surcharger un répertoire, les fichiers de surcharge doivent se trouver à l’intérieur du répertoire, et commencer par un point (.), ce qui les rend invisible pour le système linux. A contrario, la surcharge d'un jeu, doit être nommé exactement comme le jeu, extension de fichier comprise, suivit du suffixe de surcharge, .retroarch.cfg dans l'exemple au dessus

Étant donné que les fichiers de surcharges se trouvent à l’intérieur de vos répertoires de roms, ils ne craignent pas un plantage de Recalbox, une mise à jour qui se serait mal passé, ou un crash de votre SD (à condition d'utiliser un support externe bien entendu

Ils sont en outre transportables: Prenez votre clef USB avec vous pour jouer chez un ami, votre configuration s'appliquera sans rien devoir toucher!

​

Overloading Recalbox

​

Surcharger la configuration Recalbox présente deux intérêts immédiats:

  • Pouvoir de sélectionner un mode vidéo particulier pour un jeu ou un ensemble de jeux. Les aficionados du pixel perfect en arcade seront ravis.

  • Pouvoir choisir un core ou un émulateur standalone pour un jeu ou un ensemble de jeux.

Il existe d'autres possibilité, et nul doute que vous en trouverez

Surcharger des clefs qui ne sont pas utilisées par le configgen n'a aucun effet! N’espérez pas modifier le comportement d'EmulationStation (en surchargeant les tris par exemple).

Rappel: Surcharge répertoire: /path/to/your/roms/.recalbox.conf Surcharge rom: /path/to/your/roms/file.zip.recalbox.conf

​

​

Example 1: Multiple versions of MAME

Pourquoi se contenter d'une seule version de MAME alors que nous pourrions toutes les avoir.

Par exemple, vous pourriez avoir MAME 2003 Plus et MAME 2010, chaque romset dans son propre répertoire: /recalbox/share/roms/mame/ ├── MAME2003Plus └── MAME2010

​

Il suffit alors d'ajouter le fichier:

/recalbox/share/roms/mame/MAME2003Plus/.recalbox.confmame.emulator=libretromame.core=mame2003_plus

​

Et le fichier:

/recalbox/share/roms/mame/MAME2010/.recalbox.confmame.emulator=libretromame.core=mame2010

And there it is! 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!

​

​

Example 2: Affect a particular core to a game

Mon jeu /recalbox/share/pcengine/1943 Kai (Japan).zip fonctionne mieux avec le core mednafen_pce_fast_libretro qu'avec le core mednafen_supergrafx_libretro par défaut (hypothèse totalement arbitraire pour l'exemple).

Jusqu'à present, il était possible de le faire via EmulationStation, en éditant les metadata du jeu. L'information est alors stockée dans le fichier gamelist.xml. Une erreur d'écriture du fichier, un scrappe malencontreux, et c'est toute la configuration qui est perdue.

Ici il suffit d'ajouter le fichier:

/recalbox/share/roms/pcengine/1943Kai(Japan).zip.recalbox.confmame.emulator=libretromame.core=mednafen_pce_fast

Cette fois, pas de risque de perte de la configuration! Bien entendu, éditer les metadata via EmulationStation fonctionne toujours. En revanche, un fichier de surcharge sera prioritaire sur ce qui est stocké dans le gamelist.xml.

​

​

Example 3: Modify the video mode for a game

Sur mon Raspberry Pi2, le mode vidéo par defaut est CEA 4 HDMI. Mais sur le jeu Blazing Stars sur FinalBurn Neo, tourne un peu lentement. Le passer en 240p aiderait certainement, en plus d'être pixel-perfect! (encore une fois, hypothèse tout à fait hypothétique, juste pour l'exemple)

/recalbox/share/roms/fba_libretro/blazstar.zip.recalbox.confglobal.videomode=CEA 8 HDMI

And voila! When I launch this particular game, my TV goes to 240p, and I can now fully enjoy Blazing Stars.

​

Overloading Retroarch

​

Les configurations Retroarch concernent Retroarch lui même (et les options de configurations sont très nombreuses!) ainsi que les différents cores, qui ont chacun des options particulières en fonction des machines qu'ils émulent.

Il existe déjà des mécanismes propres à Recalbox et a Rétroarch pour surcharger soit la ligne de commande qui lance l’émulateur (via Recalbox.conf), soit directement les configurations Retroarch/Cores (via les menus de Retroarch)

Mais aucun de ces systèmes ne permettait d'appliquer les surcharges à des répertoires entiers et/ou de conserver ces configurations spécifiques au même endroit que les roms. Ce qui est particulièrement intéressant pour les gens qui utilisent des partages réseaux pour alimenter en roms plusieurs Recalbox!

​

​

Retroarch's configuration

La configuration Retroarch elle même est extrêmement riche, et couvre énormément de domaines différents.

Il est inutile de s’étendre sur la question, le mieux est d'aller voir directement dans le fichier de RetroArch, qui est particulièrement bien documenté: https://github.com/libretro/RetroArch/blob/master/retroarch.cfg​

Les possibilités offertes par les surcharges locales sont énormes, parmi lesquelles on peut compter:

  • Configuration vidéo: Ratio, Échelle, Anti-alias, rotation d'écran, ou même sélections de shaders, etc.

  • Tuning de l'audio pour certains jeux difficiles

  • Overlays

  • Certaines option concernant les inputs: sélection souris, sensibilité, etc.

  • Forcer des configurations NetPlay particulières

  • Changer les répertoires Retroarch (sauvegarde par exemple)

  • Régler divers options: Rem-bobinage, Avance rapide, etc.

  • ...

A l'instar des surcharges de configuration Recalbox, on va pouvoir créer des fichiers .retroarch.cfg pour les répertoires et pour les roms.

Reminder : Directory overload: /path/to/your/roms/.retroarch.cfg ROM overload: /path/to/your/roms/file.zip.retroarch.cfg

Example 1: Force a video configuration

Exemple 2: Force a shader for an entire directory

​

​

Cores configuration

Surcharger les options des cores offre d'énormes possibilités, parmi lesquelles une fonctionnalité très attendues des fans "d'ordinausaures": La possibilité de définir un repertoire par sous système!

Les surcharges de cores sont ajoutées au fichier share/system/configs/retroarch/cores/retroarch-core-options.cfg au lancement du jeu concerné, cela implique que, une fois le jeu fermé, elles seront sauvegardées dans ce même fichier, pour éviter toute mauvaise surprise, nous recommandons de surcharger les clés dans le dossier avec des valeurs par défaut (par exemple fbneo-frameskip = "0") si vous tenez à surcharger un jeu en particulier avec des valeurs spécifiques (par exemple fbneo-frameskip = "2"), ainsi vous conserverez vos valeurs "de base" pour les fichiers n'ayant pas de surcharges personnalisées.

C'est particulièrement intéressants pour les cores multi-machines, comme:

  • theodore, qui couvre les Thomson MO6, MO6, et TO8 jusqu'au TO9+

  • atari800, qui couvre tous les Atari 8bits, de la première serie 800, jusqu'aux XE, en passant par les XL.

  • vice, qui émule maintenant le C64, le PET, le Vic20, le CBM2, ...

  • hatari, qui émule du premier 520ST aux derniers Falcons

  • et d'autres encore...

Reminder : Directory overload: /path/to/your/roms/.core.cfg ROM overload: /path/to/your/roms/file.zip.core.cfg

​

Example 1: Configuring Thomson sub-systems

Les Thomson, ordinateurs français 8bits des années 80, se sont scindés en 2 séries:

  • Les MO, qui ont donné le premier MO5, puis plus tard le MO6 avec son clavier mécanique et son lecteur de cassette intégré

  • Les TO, qui ont donné les premiers TO7 et TO7-70, puis plus tard les TO8 et TO8D, avec lecteurs de disquettes, et la série des TO9 et TO9+, ordinateurs aux looks plus professionnels

Les jeux MO et TO ne sont pas du tout compatibles. Au sein d'une même série, il y a compatibilité ascendante: Un MO6 fera tourner les jeux du MO5. Bien entendu, on cherchera à émuler chaque jeu avec la machine le plus proche de la machine pour laquelle il a été conçu a l'origine, afin d’éviter tout problème et maximiser les chance d'avoir une émulation parfaite.

Si l'on prends les packs TOSEC (http://www.tosec.org), les jeux Thomson on été répartis en 4 sous-systèmes:

  • MO5

  • MO6

  • TO7 (TO7-70)

  • TO8, TO8D, TO9 et TO9+

​

Nous allons donc créer une arborescence similaire:

recalbox/share/roms/thomson/ ├── MO5 ├── MO6 ├── TO7 └── TO8,TO8D,TO9,TO9+

​

Dans la racine du système, nous allons placer un fichier de surcharge core, pour forcer quelques options intéressantes pour tout le monde:

/recalbox/share/roms/thomson/.core.cfgtheodore_rom = "Auto"theodore_autorun = "enabled"theodore_floppy_write_protect = "enabled"theodore_tape_write_protect = "enabled"

Si on rajoute des jeux dans la racine, ou dans un autre repertoire, on indique à l’émulateur d'essayer de détecter la meilleure machine. On protège aussi les fichiers roms par défaut, et on enclenche la mécanique d'autorun bien pratique quand on ne connait pas trop les machines originelles.

Ensuite dans chaque sous repertoire, on va ajouter une surcharge sur le clef theodore_rom qui determine la machine.

/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+"

Pour la série TO7, la machine la plus proche a été sélectionné: le TO8 Pour la dernière série, pleinement compatibles, la machine la plus puissante a été sélectionnée: le TO9+

C'est terminé! Vous avez maintenant 4 sous systèmes Thomson. L’émulateur n'est plus en automatique et le risque de le voir choisir le mauvais système ou un système par défaut disparaît.

Bien entendu, le core Theodore peut parfois "auto-détecter" la machine, mais ce n'est pas le cas avec d'autres cores qui ont besoin d'avoir le bon sous-système au lancement.

​

Surcharger l'aspect des repertoires

​

Pour parfaire les possibilités offertes par la definitions de sous-systèmes, que ce soit en surchargeant la configuration Recalbox pour MAME par exemple, ou en surchargeant le core Théodore pour pleinement profiter des machines TO et MO de l'époque, nous avons ajouté le possibilité de surcharger l'image et la description d'un repertoire.

Ceci permet par exemple, d'avoir sur un repertoire, la photo et la description de la machine dont les roms se trouve dans le-dit repertoire.

Il suffit pour ça d'ajouter au minimum, un fichier image au format PNG, et nommé .folder.picture.png dans le repertoire dont on veut surcharger l'image dans EmulationStation La resolution importe peux, mais gardez à l'esprit qu'une resolution identique ou approchante à vos images de scrappe reste recommandée.

Optionnellement, vous pouvez ajouter une description texte, qui se glissera sous l'image, exactement comme pour les jeux scrappés. Le fichier doit être un fichier texte simple, nommé .folder.description.txt

Rappel : Surcharge image: /path/to/your/folder/.folder.picture.png Surcharge description: /path/to/your/roms/.folder.description.txt

​

​

Example 1: from MO5 to TO9

Reprenons le repertoire thomson utilisé plus haut, que nous avions découpé en 4 sous-systèmes comme l'a fait TOSEC.

/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]

​

Le fichier .folder.picture.png du repertoire /recalbox/share/roms/thomson contient une image de la machine:

MO5 Photo

​

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 mm Weight: - 1.1 kgReleased: - 1984

​

And here's how it looks in EmulationStation:

EmulationStation

​

​

Example 2: MAME

In the same way, on the 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.txt
​
MAME 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 RomSet
​
​4859 games total!

​

And there's the result:

​

Standalone emulators

​

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.