Frequently Asked Questions (FAQ)

 

Organizing games

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

Click to see answer

(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?

Click to see answer

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?

Click to see answer

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. In the Stock Miyoo OS, rom refreshes are performed by pressing the MENU button.

 

How do I add game cheats?

Click to see answer

(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. Download the whole repository as a ZIP file (Code -> Download ZIP), Extract it and go into the cht directory (you will see cheats sorted by console), 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), 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"), 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), 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), Select one of them, then toggle the Enabled switch to enable it.

 

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

Click to see answer

(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 or rearrange consoles or systems?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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. 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?

Click to see answer

Charging Indicators The left most LED on the top of the Mini will turn blue when a full charge is reached. Miyoo recommends 5V 1A and it must be USB-A to USB-C (USB-C to USB-C charging is not supported). 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 tech and draws a lot of power. Lowering display brightness increases 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?

Click to see answer

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

 

How do I enable logging in RetroArch?

Click to see answer

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.

 

 

Saves

How do I add game saves?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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?

Click to see answer

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.

 

 
 
 
 
 
Next up: Advanced