FAQ

Organizing games

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

Onion has a built-in scraper (MMP only):

1. When inside a game list, press Y to access GLO
2. Scroll down and find the "Scraper" option

If you have a regular Mini, or just want to scrape images off-device, follow this guide:

• Scraping artwork for games

How can I add manuals for my games?

Just add a Manuals folder containing pdf files named with the same names as the roms.

For example :

• 📁Roms/GB/
  • 📄Tetris.gb
  • 📁Manuals/
    • 📄Tetris.pdf

1. When inside a game list, select a rom and press Y to access GLO menu
2. Scroll down and find the "Game manual" option

It will run Green pdf reader with the manual of the selected rom.

note

The Game manual option is not displayed in GLO menu if the pdf file doesn't exist or if it is not wall named (the files names are key sensitive).

How can I use a miyoogamelist.xml to customize 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

Note: There is an alternate method of creating the 'miyoogamelist.xml' file using a simple PowerShell script which does not have any 3rd party dependencies other than Windows and PowerShell itself. There are two versions of the script which are , depending on your preferences:

• More human readable, less efficient.
• Less human readable, more efficient.

The more efficient version of the script strips out all formatting and indenting and produces a considerably smaller file size, which theoretically allows Onion to parse and process the data faster.

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

Any time you add rom files to your SD card you will need to 'refresh your roms' to rebuild game list cache files:

• From the Games tab in the main menu, press the SELECT button.
• This will evoke the 'Refresh All Roms' menu option, press A to confirm.

Please review our Rom Files section for some additional guidance and tips.
If newly added games are still not appearing, ensure that you have placed them in the correct rom folders.
Rom folder names for each system must be capitalized and may differ from those on the stock Miyoo SD card.
Also review the Emulators Section to ensure you are using supported rom formats, as documented per system.

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 folder_zipdatabase repository as a ZIP file,
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: Schmurtz)}

PSX multidisc roms require to create a playslist file (.m3u). It allows to have only one entry for each multidisc game and one unique save file for each game. Since Onion 4.3.0 you can use Tweaks app to generate automatically the m3u playlist files which will group your multidisk games.

The tool is available from Tweaks -> Tools section. By default the script is systematically applied to PS, SEGACD, NEOCD, PCE, PCFX and AMIGA rom folders.

The supported multidisc file names are numerous (not key sensitive and support "disc" or "disk"), for example :

• MyGame (Disc 1).chd or MyGame (disc 1).chd or MyGame (DISC 1).chd or MyGame (Disk 1).chd
• MyGame (USA) (Disc 1).bin + MyGame (USA) (Disc 1).cue
• MyGame (USA) (Disc 1) (Rev 1).chd
• MyGame (Disc 1 of .2).chd ...

When you run multidisc playlist (.m3u) generator from Tweaks app, it will propose you 2 solutions to hide the multidisk roms files (and keep only the playlist visible).

• Multiple directories (.Game_Name) ---> One directory for each game: ".Game_Name".
• Single directory (.multi-disc) ---> One single directory ".multi-disc" will contains all multi-disc files.

note

This choice has no impact on the daily use experience: it's up to you to choose the file storage that suits you best.

Example: With "Driver 2" and "Metal Gear Solid"

Copy the bin/cue or chd files for the multi-disc games Driver 2 and Metal Gear Solid into the following folder of Roms/PS. You'll obtain :

📁Roms/PS/ 📄Driver 2 (Disc 1) (v1.1).cue 📄Driver 2 (Disc 1) (v1.1).bin 📄Driver 2 (Disc 2) (v1.1).cue 📄Driver 2 (Disc 2) (v1.1).bin 📄Metal Gear Solid (USA) (Disc 1) (Rev 1).chd 📄Metal Gear Solid (USA) (Disc 2) (Rev 1).chd

Result after running multidisc playlist (.m3u) generator from Tweaks app :

• if you choose Multiple directories (.Game_Name)

📁Roms/PS/ 📄Driver 2 (v1.1).m3u 📄Metal Gear Solid (USA) (Rev 1).m3u 📁.Driver 2 (v1.1)/ 📄Driver 2 (Disc 1) (v1.1).cue 📄Driver 2 (Disc 1) (v1.1).bin 📄Driver 2 (Disc 2) (v1.1).cue 📄Driver 2 (Disc 2) (v1.1).bin 📁.Metal Gear Solid (USA) (Rev 1)/ 📄Metal Gear Solid (USA) (Disc 1) (Rev 1).chd 📄Metal Gear Solid (USA) (Disc 2) (Rev 1).chd

• if you choose Single directory (.multi-disc)

📁Roms/PS/ 📄Driver 2 (v1.1).m3u 📄Metal Gear Solid (USA) (Rev 1).m3u 📁.multi-disc/ 📄Driver 2 (Disc 1) (v1.1).cue 📄Driver 2 (Disc 1) (v1.1).bin 📄Driver 2 (Disc 2) (v1.1).cue 📄Driver 2 (Disc 2) (v1.1).bin 📄Metal Gear Solid (USA) (Disc 1) (Rev 1).chd 📄Metal Gear Solid (USA) (Disc 2) (Rev 1).chd

How can I rename or rearrange 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 also use the excellent python scripts below by Andrea922. Visit the onionos-console-renamer github to download and follow the instructions detailed there.

Notes:
Systems in Onion OS are displayed in alphabetical order so the name will determine where in your list it sits.
An alternative method to order the systems is by adding an equal number of spaces both sides of the label name.
The number of spaces determines the position it is displayed on the Mini, with the most spaces being first.
For example, “ Arcade “ will appear before “Arcade”.

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 folders and Bios filenames are case sensitive.
It is strongly advised 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 (wait for 2nd rumble) 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 are my favorites deleted or missing thumbnails?

There is a known bug in the Miyoo binaries which can cause the favorites list to become corrupted.
It appears to most commonly occur if duplicate game names (even roms from different consoles) are added to your favouites so care should be taken to avoid this.

Since Miyoo have not shared their source code, the Onion team are unable to fix the cause.
Onion does include a Tweaks tool which can repair the corruption. This tool is located in:
Apps › Tweaks › Tools › Favorites: Fix thumbnails and duplicates.

My play activity is lost or corrupted, how can I recover it?

If a RetroArch core fails abruptly or has memory leak issues, it can sometimes cause a game to freeze.
Exiting the game with the MENU button during this failure, may on rare occasions, corrupt the play activity database.

FIX 1 (Mainly for 4.2 beta users)
If you have a playActivityTMP.db file in /mnt/SDCARD/Saves/CurrentProfile/saves/, just rename it to playActivity.db

FIX 2
Onion keeps versioned backups of your play activity in case of such corruption:

• Versioned backups are created and stored in /mnt/SDCARD/Saves/CurrentProfile/saves/PlayActivityBackup/.
• Your current play times are stored in /mnt/SDCARD/Saves/CurrentProfile/saves/playActivity.db.

To restore from a backup:

• Navigate to /Saves/CurrentProfile/saves/PlayActivityBackup/ and find the database file that has a size of 0KB.
• The the highest numbered version just before it will be the most recent good backup.
• Make a copy and rename it (from playActivity[nn].db to playActivity.db).
• Copy it to /Saves/CurrentProfile/saves/, replacing the one located there.

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. The blue LED on the MMP is unfortunately non-functional, the red LED will turn off when fully charged.

MM: Miyoo recommends 5V 1A and it must be USB-A to USB-C (USB-C to USB-C charging is not supported).
MMP: Supports USB-C to USB-C charging (the support is limited, and some chargers will not be accepted / start charging)

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

1. Lowering display brightness (preferably below 70%)
2. Use headphones - the speaker is the most battery-hungry component!
3. Disable Wi-Fi when not in use (the Wi-Fi chip is a major power draw as well)

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: folder_ziplaunch.zip

How do I enable logging in RetroArch?

In order to troubleshoot a particular game or emulator failure or issue, you may wish to enable RetroArch logging:

• Go to Apps › RetroArch › Settings › Logging and enable Log to File.
• Back out to the main RetroArch menu, and go to Configuration File and choose Save Current Configuration.
• Launch the game(s), or perform the action you are trying to troubleshoot.
• The output log file will be written to .tmp_update/logs/retroarch.log.

My Wi-Fi won't connect as it contains special characters, what do I do?

There's currently an issue in MainUI that prevents Wi-Fi from associating when it contains special characters.

Currently, there's no fix due to MainUI being closed source however there are various workarounds:

• Edit your wpa_supplicant.conf file via the File Explorer (file found in /appconfigs/wpa_supplicant.conf)
• Use third-party apps such as: open_in_newXK9274/better-wifi-miyoo, which supports most special characters
• Use Onion's built in WPS function (if your router supports pinless WPS). You can find this in Tweaks › Network › WPS.

How to make the audio with headphones louder?

START + L2 / R2 Adjust volume boost (see shortcuts)

Saves

How do I add game saves?

You can copy in-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 RA core for the particular emulator or system the save file(s) relates to.
If copying saves from your Miyoo stock SD card, or an early version of Onion, you will find your saves 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

Save state slot -1 is reserved for Onion's Auto-Save feature.
Manual save states start counting from slot 0 upward. If your slot has reached a particularly high number and you would like to reduce it, you can manually change the slot in the RA Quick Menu menu. Switching back to slot '0' and making a manual save will mean it starts counting again incrementally from there.

If you wish to forgo the advantages of incremental Save States mentioned above, you may disable them as follows:

• Launch a game and press MENU+SELECT to go into the RetroArch Quick Menu
• Press B once, to go to RA Main Menu
• Go to Settings > Saving > Increment Save State Index Automatically (and toggle this off)
• Press B twice and go to Quick Menu > Overrides to save the RA settings

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:
Highlighting a mapped key and pressing Y will clear/disable it.
Content Remap File saving is recommended over Core Remap File as some cores serve multiple systems.
For more information regarding RetroArch inputs and controls please review the libretro documentation here.

How do I set the in game time or RTC, for games like Pokemon?

Games such as the Pokemon and Zelda series, included a crystal oscillator in the cartridge to keep an accurate clock.
This ‘Real Time Clock’ allowed the game to track time of day and day of the week, to trigger certain in-game events.

The Miyoo Mini does not have a built-in clock and so cannot measure the progress of time when powered off.
Onion features two ways in which you can manage the emulated in-game time (or RTC).

• Automatically: By default, 4hrs will be added to the clock every time you boot your device.
  You can adjust this amount in Apps > Tweaks > System > Startup.
• Manually: You can specify the date and time in the Clock App, installed via Apps > Package Manager.

Notes:
In-game time will advance normally during gameplay and only stops when the device is shutdown.

Various

Why Onion is not a CFW (custom firmware)?

Onion doesn't modify the firmware of your Miyoo Mini so this is not a CFW. It can be considered more as an OS. The way how your Miyoo Mini is booting will not change and it is a good thing because :

• it avoids the risk of bad flash.
• the original firmware of the Miyoo Mini starts up really fast ! After the boot, the first binary launched from the SD card by the firmware is the Onion scripts directly, making the boot of Onion OS fast and safe.

Notes:
The community is working on a real alternative firmware. It's currently not usable with Onion. The objective is to obtain a better control of the hardware part and a more recent linux kernel which could simplify the compilation of additional apps.

How to overclock my Miyoo Mini?

Since Onion 4.2.0, overclock is possible. The speed improvement can be very noticeable (up to 20%).

For now the overclock feature is manual.

Onion's overclock works with cpuclock.txt text files. Retroarch will check the presence of this file in the core config folder first, then the RA root folder. The content of cpuclock.txt is simply a 4-digit number(MHz).

The max speed overclock speed are :

For the Miyoo Mini : 1700Mhz (1600 recommended for optimal stability)
For the Miyoo Mini Plus : 1900Mhz (1800 recommended for optimal stability)

For example, if you want to improve the PSX speed with PCSX-ReARMed (which can allow to enable enhanced resolution on many additional games) you can create a cpuclock.txt file in Saves/CurrentProfile/config/PCSX-ReARMed folder with the value 1600 inside.

Notes:
Do not use values above the recommend ones. It could impact the stability of your device or damage your device.