Frequently Asked Questions
General
Is Cocoon Shell an emulator?
Nope! Cocoon is a launcher — a beautiful home screen for your retro games. It organizes your game library and launches games using the emulator apps you already have installed. Think of it as the front door to your emulators.
What emulators does Cocoon work with?
Cocoon works with pretty much any Android emulator. Popular choices include RetroArch, DuckStation, AetherSX2, PPSSPP, Dolphin, Citra, DraStic, and many more. If the emulator can be launched with a game file, Cocoon can use it.
Is Cocoon free?
Check the Downloads page for the latest pricing and availability info.
Does Cocoon include any games?
No. Cocoon is just the frontend — you need to provide your own game files (ROMs). We don’t host, distribute, or link to game files.
Setup & Library
How do I add games to Cocoon?
During setup (or anytime after), point Cocoon at a folder on your device where your ROMs are stored. Sort them into subfolders by system (like snes/, gba/, psx/), and Cocoon will automatically detect them. See Getting Started for the full walkthrough.
My games don’t have box art — how do I get artwork?
Use the scraping feature! It downloads box art, logos, hero images, and metadata from online databases like SteamGridDB and ScreenScraper. You’ll just need a free account on one or both services.
Cocoon didn’t find all my games. What’s wrong?
A few things to check:
- Folder names — Make sure your ROM folders match the platform names Cocoon expects (like
snes,psx,gba). Check the Compatibility page. - File types — Your ROMs need to be in a recognized format for that platform.
- Subfolder scanning — If your ROMs are in subfolders, enable Scan Subfolders in the platform’s settings.
- Rescan — Try Settings → Library & Data → Rescan All Libraries.
Can I use ROMs from an SD card?
Yes! When selecting your ROM directory during setup, navigate to your SD card and select the folder there. Cocoon uses Android’s Storage Access Framework, so it works with internal storage, SD cards, and USB storage.
How do I add more platforms later?
Go to Settings → Library & Data, press Y to add a platform, configure its ROM folder and default emulator.
Customization
How do I change the theme?
Head to Settings → Appearance → Custom Themes to apply a theme. You can also tweak accent colors, icon styles, and more under the Appearance tab. See Themes and Customization for details.
Can I use a video as my wallpaper?
Yes! Cocoon supports video (MP4, WEBM), animated GIF, static image, and live wallpaper backgrounds. Go to Settings → Appearance → Wallpapers. See Wallpapers.
Performance note: Animated wallpapers (video and GIF) look great but use more battery and processing power than static images. If you experience any slowdown, try a lower frame rate or a static image.
How do I rearrange games on the grid?
Press Y on an empty tile → Edit Grid. Then use your controller to pick up and move tiles around. You can also drag and drop with touch.
Features
What is the “hero” view?
The hero is the large, cinematic display that shows info about whatever game you have selected — including background artwork, the game logo, platform, play time, and more. On dual-screen devices it gets its own screen; otherwise it shares the display with your grid.
Does Cocoon track my play time?
Yes! Every time you launch a game and come back to Cocoon, it records how long you played. You can see total play time and last played date for each game.
How do smart folders work?
Smart folders automatically fill themselves based on a rule — like “all favorites” or “recently played” or “all SNES games.” Create one by making a new folder and choosing a smart folder type. See Folders.
Troubleshooting
Cocoon keeps crashing on startup
If Cocoon crashes repeatedly (3 times in quick succession), it automatically resets wallpapers to prevent a crash loop. If problems persist, try Settings → System & Advanced → Reset App Data as a last resort.
A game won’t launch
- Make sure the emulator for that platform is installed.
- Check that the emulator supports the ROM’s file format.
- Try a different emulator as a per-game override.
- See Emulator Setup for more troubleshooting tips.
How do I completely start over?
Settings → System & Advanced → Reset App Data will do a full factory reset of Cocoon. This clears everything — library, settings, artwork, all of it. Make sure you back up first if there’s anything you want to keep.
Where does Cocoon store its data?
All of Cocoon’s downloaded artwork, themes, sounds, music, and backups are stored in the data folder you chose during setup. Game files stay wherever you put them.