Differences

This shows you the differences between two versions of the page.

--- batocera_conf_syntax [2022/01/02 10:34] – 'global' actually is required atari
+++ batocera_conf_syntax [2022/09/06 11:28] (current) – SSH command too atari
@@ Line 3: / Line 3: @@
 Most settings (including RetroArch-specific settings) can be adjusted from within the menus in EmulationStation. This includes per system and per game settings, access per system settings by pressing ''[SELECT]'' while in the system list and scrolling to **ADVANCED SYSTEM SETTINGS** and access per game settings by holding {{:wiki:south.png?nolink&20|South button (B SNES)}} while the game in question is selected (in Batocera **v31** and lower, this is instead tapping {{:wiki:north.png?nolink&20|North button (X SNES)}}).
-However, there are a couple of (usually very recently implemented) settings that can only be set by manually editing files. This includes RetroArch's //core-specific// options which **are not** available in the per system settings.
+However, there are a couple of (usually very recently implemented) settings that can only be set by manually editing files. This includes RetroArch's //core-specific// options which **are not** already available in the per system settings.
 <WRAP center round tip>
 If you were looking for how to activate the official Nvidia drivers, check out [[:supported_pc_hardware#nvidia_graphics_cards|its specific page]] instead.
-If you were looking on how to change ''batocera-boot.conf'' settings, check out [[:edit_boot_partition|its specific page]] instead.
+If you were looking on how to change ''batocera-boot.conf'' settings, check out [[:edit_boot_partition|the boot partition editing page]] instead.
 </WRAP>
-===== batocera.conf =====
+===== batocera.conf option keys and values =====
-''/userdata/system/batocera.conf'' is the main user-configuration file in Batocera. This will contain all the settings you may have set in **GAME SETTINGS**, **ADVANCED PER SYSTEM OPTIONS** and a few other places.
+''/userdata/system/batocera.conf'' is the main user-configuration file in Batocera, it can be [[:add_games_bios#while_batocera_is_running|accessed from the network share or the file manager]] or [[:access_the_batocera_via_ssh|via SSH]] with the following:
+<code bash>
+nano /userdata/system/batocera.conf
+</code>
+This will contain all the settings you may have set in **GAME SETTINGS**, **ADVANCED PER SYSTEM OPTIONS** and a few other places.
 <WRAP center round info>
@@ Line 19: / Line 25: @@
 </WRAP>
-''batocera.conf'' uses the following syntax (reminder, objects in ''<''''>'' are required and have to be replaced, including the ''<''''>'' symbols themselves, and objects in ''['''']'' are optional, with escaped characters ''\['' and ''\]'' indicating that an actual ''['' or '']'' is used in the syntax respectively):
+<WRAP center round tip>
+The default ''batocera.conf'' can be found [[https://raw.githubusercontent.com/batocera-linux/batocera.linux/master/package/batocera/core/batocera-system/batocera.conf|here on the Github]].
+</WRAP>
-<code>
+''batocera.conf'' uses the following syntax (objects in ''<''''>'' are required and have to be replaced, including the ''<''''>'' symbols themselves, objects in ''('''')'' are optional and objects separated by a pipe ''|'' indicate exclusive or):
-[<system>][\["<ROM filename>.<ROM extension>"\].]<key name>[.<subkey 1 name> ...]=<value>
+<code bash>
+(<system>(["<ROM filename>.<ROM extension>"].)|folder["<path>"].)<key name>(.<subkey 1 name> ...)=<value>
 </code>
 which can be boiled down in its simplest form to:
-<code>
+<code bash>
 <option>=<value>
 </code>
@@ Line 33: / Line 43: @@
 **Batocera option**
-It can be a bit confusing seeing all the possibilities laid out like above so here's a simple example:
+It can be a bit confusing seeing all the possibilities laid out like above so here's a simple example for a Batocera option:
-<code>
+<code bash>
 audio.bgmusic=0
 </code>
@@ Line 45: / Line 55: @@
 Here's an example of changing a setting for every game of a specific system:
-<code>
+<code bash>
 nes.bezel=none
 </code>
@@ Line 55: / Line 65: @@
 Here's an example of changing a setting for a specific game of a system:
-<code>
+<code bash>
 c64["Arkanoid - Revenge of Doh (USA, Europe).zip"].external_palette=vice
 </code>
@@ Line 61: / Line 71: @@
 This will change the **EXTERNAL PALETTE** option for the [[systems:c64|Commodore 64]] game "Arkanoid - Revenge of Doh" to use the "vice" palette. Here, the system is "c64", the ROM filename and extension is "Arkanoid - Revenge of Doh (USA, Europe).zip", the key name is "external_palette" and the value is "vice". No ''<subkey # name>'' is used.
-Key names, systems and values are not locale-specific, they will be the same regardless of which language you are using. The option names themselves are only translated on ES itself when in the menu, the key names stay the same.
+**Folder-specific option** (introduced in **v34**)
+Here's an example of setting an option for games launched from a certain folder:
+<code bash>
+nes.folder["/userdata/roms/nes/Japan/"].shaderset=Mega-Bezel-Community-JP-Night
+</code>
+This will set the shader set used for all NES games in the ''/userdata/roms/nes/Japan'' folder to use the night variant of the Famicom decoration (''Mega-Bezel-Community-JP-Night'').
+<WRAP center round important>
+Game-specific and folder-specific setting syntaxes conflict with one another. A key using both at the same time will be invalid and ignored.
+</WRAP>
+Key names, systems and values are not locale-specific, they will be the same regardless of which language you are using. The option names themselves are only translated on ES itself when in the menu, the internal key names stay the same.
 The absence of a key/value will imply its [[#"auto"_setting_behavior|default "AUTO" setting]] will be used. In fact, this is the only way to use the "AUTO" setting.
@@ Line 69: / Line 93: @@
 Comments are treated a bit special with ''batocera.conf''. A general comment that exists to explain what an option might do (a few of these are already included by default) is indicated by two hash symbols opening the line. For example:
-<code>
+<code bash>
 ## Set the audio device
 </code>
@@ Line 77: / Line 101: @@
 Then there are special "disable setting" comments, which are indicated by a single hash opening the line. For example:
-<code>
+<code bash>
 #wifi.key=new key
 </code>
@@ Line 89: / Line 113: @@
 However, if you'd like to find the keys manually, you have to change your approach depending on which keys you are after:
-  * To find the global keys (ones that can be applied to //most// systems) manually, look through the code and figure out its logic in the launcher script (in the ''/usr/lib/python3.9/site-packages/configgen/'' folder).
+  * To find the global keys (ones that can be applied to //most// systems) manually, look through the code and figure out its logic in the launcher script (in the ''/usr/lib/python#.#/site-packages/configgen/'' folder).
-  * To find the emulator keys (of which apply to all systems that emulator supports, usually) manually, look through the code and figure out its logic in its [[modify_the_system_while_it_s_running#editing_system_files|configuration generator]] (most of which are in ''/usr/lib/python3.9/site-packages/configgen/generators/'').
+  * To find the emulator keys (of which apply to all systems that emulator supports, usually) manually, look through the code and figure out its logic in its [[modify_the_system_while_it_s_running#editing_system_files|configuration generator]] (most of which are in ''/usr/lib/python#.#/site-packages/configgen/generators/'').
   * To see system-specific keys, look at the ''/usr/share/emulationstation/es_features.cfg'' file. The ''features'' tag shows which "global" keys can be applied to your system, while the rest of the system-specific keys are specified in their own core option section.
@@ Line 119: / Line 143: @@
 The subkey name for RetroArch's settings is ''retroarch'' and the subkey after that is usually identical to RetroArch's key for the respective setting. Unlike RetroArch, no double quotes are required for the setting's value, however including them won't break anything. Here is the syntax:
-<code>
+<code bash>
-<system>[\["<ROM filename>.<ROM extension>"\].]retroarch.<RetroArch setting name>=<value>
+<system>(["<ROM filename>.<ROM extension>"]|folder["<path>"]).retroarch.<RetroArch setting name>=<value>
 </code>
 which can be boiled down to (if desiring to apply it to all systems):
-<code>
+<code bash>
 <system>.retroarch.<RetroArch setting name>=<value>
 </code>
@@ Line 131: / Line 155: @@
 For example:
-<code>
+<code bash>
 global.retroarch.video_hard_sync=true
 </code>
@@ Line 138: / Line 162: @@
 RetroArch settings can also be applied to only a specific system. For example:
-<code>
+<code bash>
 saturn.retroarch.video_hard_sync=true
 </code>
@@ Line 149: / Line 173: @@
 In addition to RetroArch's general settings, each libretro core has its own set of settings that can be configured as well. Unlike with RetroArch general settings, here any core setting can be set irrelevant of whether Batocera knows about it yet or not. The syntax is as follows:
-<code>
+<code bash>
-<system>[\["<ROM filename>.<ROM extension>"\].]retroarchcore.<core option>=<value>
+<system>(["<ROM filename>.<ROM extension>"].)retroarchcore.<core option>=<value>
 </code>
 which can be boiled down to:
-<code>
+<code bash>
 <system>.retroarchcore.<core option>=<value>
 </code>
@@ Line 161: / Line 185: @@
 For example:
-<code>
+<code bash>
 global.retroarchcore.vice_external_palette=vice
 </code>
@@ Line 168: / Line 192: @@
 Yes, this does mean you can set core options per system (some cores are capable of emulating multiple systems as well, maybe a setting doesn't need to be applied to all of them). For example:
-<code>
+<code bash>
 c64.retroarchcore.vice_external_palette=vice
 </code>