Frequently Asked Questions (FAQ)

Organizing games

How can I add box art or screenshot images for my games?

^{(Credit: Julian)}

The file format is PNG with a max size of 250×360. The images need to be placed into the Roms/<gamesystem>/Imgs folder.

The Imgs folder name is case sensitive (must have a capital I). Examples would be like the following:
Roms/FC/Imgs
Roms/SFC/Imgs
Roms/GB/Imgs

You can scrape your box art or screenshots automatically by following the below process:

• Use https://www.skraper.net/
• Log in and select "Recalbox"
• Check "Include non-Recalbox rom folders"

  (Some systems aren't recognized because their folder-names are non-standard. To add those systems, press the + symbol on the bottom left, select the systems that are missing & hit "OK". Then click the added systems in the bar on the left, and correct the system's folders in the "Games/Roms folder" bar or by clicking the file-icon to the right of it. You can find a list of all Rom folder names here

• Go to the "media" tab -> Enable & set "Resize width to" to 250 and enable "Keep Image Ratio"
• Select the image type you don't want in the "Fetched Media List" and press the "minus" button, so there's only one picture.

  You can change how the image mix looks with the two buttons under "Media type", I recommend changing "4 IMAGES MIX" to "Screenscraper's Recalbox Mix V2", but use whatever you prefer. If you choose a picture that's taller than it's wide, like the boxart, set "Resize height to" to 360 and disable "Keep Image Ratio"

• Change "Output folder" to %ROMROOTFOLDER%\Imgs, with a capital I.
• Under 'Gamelist Link' ensure that "Link from node '<thumbnail>'" is ticked as well as 'Optimize media storage' (these are important if you wish to use the generated gamelist.xml to create a miyoogamelist.xml for use in Onion (more info on this below on this page).
• Now click the system you want to scrape for on the left side, or "all system", and press the play button in the bottom right corner.

This will automatically scrape images to the correct folders for Miyoo Mini.

How can I use a miyoogamelist.xml to customise game names?

Onion uses a 'miyoogamelist.xml' (in the same format as the more common 'gamelist.xml'). To create a miyoogamelist, review the guide here.

Troubleshooting: After adding the miyoogamelist.xml to your rom folder you will need to Refresh all roms from the Games tab (press SELECT to open the context menu). If the list is still not being loaded, ensure that the extlist in the Emu/<systemname>/config.json is populated with all appropriate rom extensions for your games (i.e. "extlist":"zip|ZIP")

Important: The guide includes a "cleanup" script for use with xmlstarlet but an issue with viewing PDF files in a browser means the script does not copy well. Either open the PDF in a reader application (i.e. Adobe Acrobat) or use this batch file to run the script

I have added new roms to my SD card, why are the games not showing up?

Any time you add more roms you will need to refresh your roms. From the Games tab, highlight the system and press the SELECT button to evoke the 'Refresh All Roms' option and press A. If your newly added games are still not appearing, ensure that you have placed your roms in the correct rom folders. Rom folders for each system must be named in capitals and they will differ from those on the stock Miyoo Mini SD card.

How do I add game cheats?

^{(Credit: Erazemk)}

This guide will teach you how to add cheats for your RetroArch emulators.

Your first task is to find cheat files for your games (usually provided in .cht format). You can find them fairly easily online, but the recommended source is LibRetro database, which has up-to-date cheats for most LibRetro supported emulators.

1. Download the whole repository as a ZIP file (Code -> Download ZIP),
2. Extract it and go into the cht directory (you will see cheats sorted by console),
3. Copy directories for consoles you want to your Miyoo Mini's SD card, into the RetroArch/.retroarch/cheats directory (you might have to enable showing hidden directories if you can't see the .retroarch directory),
4. Inside the .retroarch directory there will be a retroarch.cfg file, which you need to open in a text editor. Find the line with the option quick_menu_show_cheats and set it to "true" (so the whole line should be quick_menu_show_cheats = "true"),
5. Eject your SD card from your computer and plug it into the Miyoo Mini, then open up your favourite game (for which you have downloaded cheats),
6. Enter the RetroArch menu (press Menu, hold it, then press Select) and find the Cheats -> Load Cheat File (Replace) option. There you can find the cheat file in one of the directories. After choosing it you will be returned back to the cheats menu, but now you should see a number of cheats at the bottom (e.g. Cheat #0),
7. Select one of them, then toggle the Enabled switch to enable it.

What is the optimal way to organize multi-disk games?

^{(Credit: Dwmccoy)}

My solution for multi-disc games was to store the Roms in a different folder.

Example: Driver 2

Copy the bin/cue files for the multi-disc game Driver 2 into the following folder of Roms/PSX/Driver 2

I had two disc files to copy into the Roms/PSX/Driver 2 folder Driver 2 (Disc 1) (v1.1) and Driver 2 (Disc 2) (v1.1) I then created an m3u file named Driver 2 (v1.1).m3u with the following content and placed it into the /Roms/PS folder

../../Roms/PSX/Driver 2/Driver 2 (Disc 1) (v1.1).cue
../../Roms/PSX/Driver 2/Driver 2 (Disc 2) (v1.1).cue

Launch the PlayStation Emulator and the only file you should see for the "Driver 2" game is the m3u file since the disc(s) for the game reside in a different folder.

You can store the files in whatever folder you want as long as the path to the cue file is correct. I created the folder PSX to store the multi-disc images in for simplicity. It's a bit of a hassle but it does work.

How can I rename consoles or systems?

The name of each console or system is defined in Emu/[systemname]/config.json You can edit this file with a text editor on your PC and apply a new name by updating the 'label' field.

To easily make bulk changes to your console or system names you can use the excellent python scripts below by Andrea922. Visit the onionos-console-renamer github to download and follow the instructions detailed there.

Troubleshooting

I just installed Onion, why do some games no longer launch?

There can be a few reasons why you may find a specific system does not launch games after installing Onion:

• If you have added games post installation, you may need to update your rom caches, from the Games tab press the SELECT button to open the context menu and choose the Refresh all roms option.
• Ensure you are using supported rom extensions and that both your rom folder and Bios file(s) are named exactly as detailed in our Emulators Section.
• Save states can, on occasion, be incompatible between core versions/updates. Delete the Saves/CurrentProfile/states/[system] folder for the given system.
• If none of the above points have resolved your issue, it is recommended to source and test with alternative roms (those that come with the Mini are of very poor quality).

Notes:
Rom folder and Bios filenames are case sensitive.
It is strongly recommended not to use the Miyoo provided SD card or USB Card Reader as both are very prone to data corruption and failure and will cause issues.

I have upgraded to a newer version of Onion and some games are running slower or too fast?

If you experience slower (or faster) gameplay than usual for some games following an Onion upgrade, we recommend that you create an in-game Save and then delete your Save States. Save States are stored inside Saves/CurrentProfile/states/[CORENAME]/

Please see other solutions here within this FAQ with regards to managing Save States and Saves.

I am stuck in a black screen boot-loop, how can I get back into Onion?

If you launched a rom or a file that is incompatible with the core, it can cause a black screen. Onion's auto-resume feature can mean you returning to this same black screen on each boot.

You can hold down POWER for 10+ seconds to break out of this behaviour and return you to MainUI

If this still does not work for you, you can disable the next auto-resume by inserting your SD card into your PC and deleting the file cmd_to_run.sh inside the .tmp_update folder

Why is my battery percentage fluctuating and how do I know if the device is fully charged?

Charging Indicators
The left most LED on the top of the Mini will turn blue when a full charge is reached.

Battery Percentage Fluctuations
The Mini has no Battery Management System so Onion calculates the remaining battery percentage based on the voltage.
Environment changes and power draw will affect the determined percentage which can fluctuate greatly.

This may appear jarring but is perfectly normal. If you go from playing a resource hungry system (PS1), to playing something less intensive (GB) then you will likely see an increase in percentage. Depending on the health (and thus voltage output) of your battery, it may not reach 100% in Onion when fully charged.

The Onion battery capacity estimation is constantly pooling in the background for more precise results over time. This is the best method that is possible on this device, improved over stock and the same method used by the RA build and in MiniUI.

Reducing Battery Usage
The display in the Mini is old technology and draws a lot of power. Lowering display brightness will increase battery life.
The below testing output demonstrates GBA running at 50% display brightness for almost 8hrs of play time.

I just downloaded an app or a standalone emulator and the sound seems broken?

It is likely due to a lack of compatibility with the Miyoo audio server. To cope with this, just rename the launch.sh file in your app folder to launch2.sh, then extract this file to the app folder: launch.zip

Saves

How do I add game saves?

You can copy game save files from another device or emulator for use in OnionOS.

• In most cases, Save files should be in .srm format, named identically to the rom and are case sensitive. Note that .sav files can be renamed to .srm, other formats may require a conversion tool.
• To add your saves to OnionOS just copy your individual save files into the correct emulator folder in: Saves/CurrentProfile/saves/[CORENAME]
• If you have already launched the game prior to adding your saves then you will also need to go to the Saves/CurrentProfile/states/[CORENAME] folder ...and delete any Save States here for the same game(s) in order for your newly added game saves to be recognised.

[CORENAME] = the folder with name of the core for the particular emulator or system 'core', the save file(s) relates to
If copying saves from your Miyoo stock SD card, you will find them in RetroArch/.retroarch/saves/[CORENAME]

How do I delete save states?

Save States are stored inside Saves/CurrentProfile/states/[CORENAME]/

Notes: [CORENAME] = the folder with name of the core for the particular emulator or system 'core', the save state file(s) relates to

How do I disable auto-load save states?

• Launch the game and press MENU+SELECT to go into the RetroArch menu.
• Press B to go back one level.
• Go to Setting › Saving › Load State Automatically (and turn it off).
• Press B twice to go back to the main menu.
• Then go to Quick Menu › Overrides and select one of the following:

  - `Save Game Overrides` - for just this game.  
  - `Save Core Overrides` - for everything the core plays.  
  - `Save Content Overrides` - for everything in the same Rom folder.  

Notes:
Content Overrides are recommended over Core Overrides since some cores serve multiple systems. For more information regarding RetroArch overrides please review the libretro documentation here.

Why does my state slot number get so high? Does it take up a lot of space on my SD?

Onion enables a feature that retains your old Save States.

In case of manipulation error, file corruption, or simply because you want to return to an earlier section of the game, it is possible to go back in time to select an earlier Save State. This takes up very little space on your SD as even if your Save State slot number is high, RetroArch will only retain the last 10 files.

To manage your current Save State slot:

• Launch the game and press MENU+SELECT to go into the RetroArch menu.
• Go to Save States > State Slot and change the slot number with Dpad Left or Dpad Right
  (Tip: Pressing Y here will show a full screen image capture for the Save State)
• You can alternatively manage the slot number 'in-game' by pressing MENU+Dpad Left or MENU+Dpad Right and then pressing either:
  • MENU+L2 to load from the slot you selected
  • MENU+R2 to save to (and overwrite) the slot you selected

Emulator settings

How can I change a game's scaling or make it fullscreen?

• Launch the game and press MENU+SELECT to go into the RetroArch menu.
• Press B to go back one level in the RA menu and select Settings › Video › Scaling
• Here you can toggle:

  - `Integer Scale` - show the game in its original resolution (scale only in whole pixels).  
  - `Keep Aspect Ratio` - **enabled:** fit to screen, **disabled:** stretch.  

Notes:
You will need to save overrides to commit this change, see 'How do I save RetroArch settings?' below for instructions.

How do I save RetroArch settings?

When you make changes in RetroArch you must apply these using "Overrides" for them to take effect.

• Launch the game and press MENU+SELECT to go into the RetroArch menu.
• Make your desired changes.
• Then go to Quick Menu › Overrides and select one of the following:

  - `Save Game Overrides` - for just this game.  
  - `Save Core Overrides` - for everything the core plays.  
  - `Save Content Overrides` - for everything in the same Rom folder.  

Notes:
Content Overrides are recommended over Core Overrides since some cores serve multiple systems. For more information regarding RetroArch overrides please review the libretro documentation here.

How do I reset RetroArch settings to the Onion defaults?

Resetting your global configuration from within RA itself will break Onion functionality as this restores 'out of the box' RA defaults. Instead:

• Go to your Apps section and open Tweaks.
• Scroll to Advanced and choose Reset Settings... › Reset RetroArch main configuration

Notes:
You should always in the first instance, save your changes to Retroarch settings as "Overrides" rather than saving changes to the main (global) configuration (see other questions in this FAQ re saving RetroArch settings). This will make it far easier to revert a change by deleting the overrides from within the RA Overrides menu.

How do I bind Fast Forward to a single button?

To do this, launch a game from the system to want to change.

• Press MENU+SELECT to go into the RetroArch quick menu
• Choose Controls › Port 1 Controls.
• Navigate to the key you wish to assign and press A to view a list of the various available functions (i.e. Fast Forward)
• Confirm your selection with A.
• The changes are saved automatically, just go back two levels and choose Resume.

Notes:
This only works for certain systems (e.g. GB, GBC, GBA, etc.), and you have to hold the button to fast forward, whereas the global shortcut MENU+R is "press to toggle".
For more information regarding RetroArch inputs and controls please review the libretro documentation here.

How do I remap in-game controls?

To do this, launch a game from the system to want to change.

• Press MENU+SELECT to go into the RetroArch quick menu
• Choose Controls › Port 1 Controls.
• Navigate to the key you wish to reassign and press A to view a list of the various in-game controls available.
• Confirm your selection with A.
• The changes are saved automatically when exiting the menu.

Saving individual game, core, or content remaps

• After making the changes as above, press B to go back one level.
• Then go to Manage Remap Files and choose one of the following:
  • Save Game Remap File - for just this game.
  • Save Core Remap File - for everything the core plays.
  • Save Content Remap File - for everything in the same Rom folder.

Notes:
Content Remap File is recommended over Core Remap File since some cores serve multiple systems.
For more information regarding RetroArch inputs and controls please review the libretro documentation here.