Differences

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

--- user:rion [2026/06/10 07:15] – rion
+++ user:rion [2026/06/10 14:45] (current) – rion
@@ Line 1: / Line 1: @@
-====== Use External Storage ======
+====== Storage Manager ======
 {{toc>}}
@@ Line 5: / Line 5: @@
 > Introduced in **Batocera v43**.
-Batocera's Storage Manager allows you to expand your ROM storage across multiple drives while keeping a single unified game library. USB drives, external hard drives, SSDs, SD cards, and additional internal drives can all be used.
+Batocera's **Storage Manager** allows you to expand your ROM storage across multiple drives while keeping a single unified game library.
+USB drives, external hard drives, SSDs, SD cards, and additional internal drives can all be used.
+<WRAP tip>
+The Storage Manager introduced in Batocera v43 allows multiple drives to be combined into a single ROM library without requiring symbolic links, manual mounts, or custom scripts.
+</WRAP>
+{{wiki:use_external_storage_system_settings.png?nolink&576|Storage Manager location in System Settings}}
-{{ :use_external_storage_system_settings.png |Storage Manager location in System Settings}}
 ===== Overview =====
-{{ :use_external_storage_storage_overview_diagram.png |Storage Manager overview}}
 The Storage Manager can:
@@ Line 19: / Line 26: @@
   * Format and prepare new drives
   * Use multiple drives simultaneously
-  * Present all ROMs as a single library under `/userdata/roms`
+  * Present all ROMs as a single library under ''/userdata/roms''
   * Safely eject drives
   * Automatically refresh game lists
+From the user's point of view, there is still only one ROM folder:
+<code>
+/userdata/roms
+</code>
+Batocera handles the storage pool in the background.
+{{wiki:use_external_storage_storage_overview_diagram.png?nolink&576|Storage Manager overview}}
+A simplified overview:
+<code>
+Internal ROMs
+     │
+Drive 1 /roms
+     │
+Drive 2 /roms
+     │
+  MergerFS
+     │
+/userdata/roms
+</code>
 ===== Requirements =====
@@ Line 48: / Line 79: @@
     └── roms
 </code>
+Not supported:
+<code>
+Drive
+├── nes
+├── snes
+└── psx
+</code>
+The Storage Manager currently expects the ''roms'' folder to exist directly in the root of the mounted drive.
 ===== Using Existing Drives =====
-{{ :use_external_storage_merge_existing_drive_prompt.png |Merge existing drive prompt}}
+When Batocera detects a mounted drive containing a compatible root-level ''roms'' folder, it offers to merge the drive into the Storage Manager.
+{{wiki:use_external_storage_merge_existing_drive_prompt.png?nolink&576|Merge existing drive prompt}}
-When Batocera detects a mounted drive containing a compatible `roms` folder, it offers to merge the drive into the Storage Manager.
+After accepting the prompt, Batocera adds the drive to the storage pool.
-{{ :use_external_storage_merge_existing_drive_complete.png |Merge complete}}
+{{wiki:use_external_storage_merge_existing_drive_complete.png?nolink&576|Merge complete}}
-After the merge completes, the ROMs become available alongside your existing collection.
+After the merge completes, the ROMs stored on the drive become available alongside your existing collection.
 ===== Formatting a New Drive =====
-{{ :use_external_storage_format_new_drive_prompt.png |Format and merge prompt}}
 If a blank drive is detected, Batocera can automatically prepare it for game storage.
-{{ :use_external_storage_format_confirmation.png |Format confirmation}}
+{{wiki:use_external_storage_format_new_drive_prompt.png?nolink&576|Format and merge prompt}}
-Selecting **Format & Merge** will erase all existing data on the drive.
+<WRAP important>
+Formatting a drive will permanently erase all existing data stored on that drive. Make sure any important files have been backed up before proceeding.
+</WRAP>
-{{ :use_external_storage_formatting_drive.png |Formatting drive}}
+Selecting **Format & Merge** will format the drive and add it to the Storage Manager.
+{{wiki:use_external_storage_format_confirmation.png?nolink&576|Format confirmation}}
 Batocera will:
   * Format the drive
-  * Create a `roms` folder
+  * Create a root-level ''roms'' folder
   * Generate the standard ROM directory structure
   * Merge the drive into the Storage Manager
+  * Refresh the game lists
+{{wiki:use_external_storage_formatting_drive.png?nolink&576|Formatting drive}}
 ===== Using Multiple Drives =====
@@ Line 93: / Line 149: @@
 /userdata/roms
 </code>
+Games can be distributed across multiple drives while still appearing as one collection inside EmulationStation.
 ===== Internal Drives =====
@@ Line 98: / Line 156: @@
 The Storage Manager is not limited to removable USB devices.
-Additional internal SATA and NVMe drives can also be used, provided they are mounted and contain a root-level `roms` folder.
+Additional internal drives can also be used.
+For example:
+<code>
+/media/roms1/roms
+/media/roms2/roms
+</code>
+As long as the drive is mounted by Batocera and contains a root-level ''roms'' folder, it can be merged into the Storage Manager.
+This includes:
+  * SATA hard drives
+  * SATA SSDs
+  * NVMe SSDs
+  * USB storage devices
+  * SD cards
+<WRAP info>
+The drive name does not matter. What matters is that the mounted drive contains a root-level ''roms'' folder.
+</WRAP>
 ===== Safe Drive Removal =====
-{{ :use_external_storage_safe_eject_menu.png |Safe eject menu}}
 Drives can be safely removed from:
-  * Main Menu
+  * **Main Menu**
-  * System Settings
+  * **System Settings**
-  * Eject an External Disk
+  * **Eject an Extra Disk**
-{{ :use_external_storage_safe_eject_confirmation.png |Eject confirmation}}
+{{wiki:use_external_storage_safe_eject_menu.png?nolink&576|Safe eject menu}}
-{{ :use_external_storage_drive_ejected.png |Drive ejected}}
+After selecting the drive, Batocera asks for confirmation before removing it from the storage pool.
-Batocera automatically updates the storage pool and refreshes game lists.
+{{wiki:use_external_storage_safe_eject_confirmation.png?nolink&576|Eject confirmation}}
+Batocera automatically updates the storage pool and refreshes the game lists.
+{{wiki:use_external_storage_drive_ejected.png?nolink&576|Drive ejected}}
+Games stored only on the removed drive will disappear from the library until that drive is connected and merged again.
 ===== What Gets Merged? =====
-Only:
+Only the ROM library is merged:
 <code>
 /userdata/roms
 </code>
-is merged.
 Folders such as:
@@ Line 132: / Line 215: @@
 /userdata/saves
 /userdata/screenshots
+/userdata/themes
+/userdata/music
 </code>
 remain on internal storage.
+The Storage Manager does not merge BIOS files, save files, screenshots, themes, or music.
+===== Internal ROM Preservation =====
+When the first additional ROM drive is merged, Batocera preserves the existing internal ROM collection.
+Internally, existing ROMs stored in:
+<code>
+/userdata/roms
+</code>
+are moved into:
+<code>
+/userdata/.roms_base
+</code>
+This allows internal ROMs to remain visible alongside ROMs stored on merged drives.
+If all merged drives are later removed, Batocera restores the internal ROM library back to the normal ''/userdata/roms'' location.
+===== Limitations =====
+The Storage Manager currently requires this layout:
+<code>
+<drive>/roms
+</code>
+Nested ROM folders are not detected automatically.
+Example:
+<code>
+<drive>/Batocera/roms
+</code>
+is not automatically merged.
+Only the ROM library is merged. Other userdata folders remain independent.
 ===== Advanced Technical Details =====
-Batocera uses **MergerFS** to combine ROM folders from multiple drives.
+Batocera uses **MergerFS** to combine ROM folders from multiple drives into a single virtual directory.
-Current policy:
+The merged library is presented at:
+<code>
+/userdata/roms
+</code>
+Internally, Batocera maintains a storage pool containing:
+<code>
+/userdata/.roms_base
+</code>
+plus any merged ROM folders.
+Example:
+<code>
+/userdata/.roms_base
+/media/roms1/roms
+/media/roms2/roms
+</code>
+These locations are combined into:
+<code>
+/userdata/roms
+</code>
+==== MergerFS File Placement Policy ====
+Batocera currently uses the following MergerFS create policy:
 <code>
@@ Line 148: / Line 305: @@
 </code>
-**eplfs** means **Existing Path, Least Free Space**.
+**eplfs** means:
+<code>
+Existing Path, Least Free Space
+</code>
 When writing a new file:
-  * A branch containing the target folder is selected
+  * MergerFS looks for branches where the target folder already exists
-  * The branch with the least free space is preferred
+  * Among those branches, the branch with the least free space is preferred
   * Branches with less than 4 GB free are ignored
-  * Files can move automatically if a drive becomes full
+  * If a drive becomes full during a write operation, the file can automatically move to another branch
+Example:
+<code>
+/media/roms1/roms/nes   900 GB free
+/media/roms2/roms/nes   200 GB free
+</code>
+A new ROM copied into:
+<code>
+/userdata/roms/nes
+</code>
+would be stored on:
+<code>
+/media/roms2/roms/nes
+</code>
+because it has the least free space while still meeting the minimum free space requirement.
+<WRAP important>
+The MergerFS implementation and file placement policy may change between Batocera releases. This section reflects the behavior introduced with Batocera v43.
+</WRAP>
+===== Frequently Asked Questions =====
+==== Can I use internal drives? ====
+Yes. Any drive mounted by Batocera containing a root-level ''roms'' folder can be merged into the Storage Manager.
+Example:
+<code>
+/media/roms1/roms
+/media/roms2/roms
+</code>
+==== What happens if I unplug a merged drive? ====
+Batocera updates the storage pool and refreshes the game lists.
+Games stored only on the disconnected drive will temporarily disappear until the drive is connected again.
+==== Are BIOS files merged? ====
+No.
+Only:
+<code>
+/userdata/roms
+</code>
+is merged.
+BIOS files remain stored in:
+<code>
+/userdata/bios
+</code>
+==== Are saves merged? ====
+No.
+Save files remain stored in the normal userdata location, for example:
+<code>
+/userdata/saves
+</code>
+==== Can I store ROMs in a different folder? ====
+No.
+The Storage Manager currently expects a root-level folder named:
+<code>
+roms
+</code>
+==== Does the drive name matter? ====
+No.
+For example, both of these are valid if they contain a root-level ''roms'' folder:
+<code>
+/media/roms1/roms
+/media/MyGamesDrive/roms
+</code>
 ===== References =====
-Batocera TV – ''Batocera 43 - Episode II''
+  * Batocera TV — ''Batocera 43 - Episode II''
+    * Storage Manager demonstration:
+      * https://youtu.be/XpH27Yswe38?t=143
-https://youtu.be/XpH27Yswe38?t=143
+  * Batocera Storage Manager source code:
+    * https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-scripts/scripts/batocera-storage-manager