Backup & Restore

Spent time arranging your grid just right, setting up folders, scraping all your artwork, and organizing everything? Cocoon has several ways to save your work so you can restore it later — great for when you reset your device, switch to a new phone, or just want a safety net.

Cocoon has three main backup/restore systems, each protecting a different part of your setup:

Export Layout (Grid Backup)

This saves your entire grid arrangement — where every game and folder is positioned, all your folder structures, and folder artwork.

What Gets Saved

• ✅ Grid positions — Where every game and folder sits on your grid
• ✅ All folders — Both regular and smart folders, including their color, overlay icon, sort order, and smart folder rules
• ✅ Folder artwork — Custom icons, logos, and hero images you’ve set for folders
• ✅ Android app tiles — Any Android apps you’ve added to your grid
• ✅ Nested folder structures — Parent-child relationships between folders (up to 5 levels deep)

Creating a Layout Backup

1. Go to Settings → System & Advanced → Backup Layout.
2. Cocoon saves a timestamped backup to your data directory under backups/.

Restoring a Layout Backup

From Settings:

1. Go to Settings → System & Advanced → Restore Layout.
2. Pick the backup you want to restore.

During first-time setup: If Cocoon finds a layout backup in your data directory during setup, it’ll ask if you want to restore it (Step 5 of the setup wizard). The backup date is shown on the button so you know which one you’re restoring.

Heads up: Restoring a layout backup is a clean-slate operation — it clears your current grid positions and folders, then rebuilds everything from the backup. Your games and scraped artwork aren’t affected.

How Game Matching Works

Layout backups store game positions using portable paths (like snes/Super Mario World.sfc instead of a full device path). This means backups work even if your ROMs have moved to a different folder or device — as long as the filenames and platform folder names are the same.

Export Gamelists (Metadata Backup)

This saves all your game metadata in ES-DE compatible gamelist.xml files — one per platform.

What Gets Saved

• ✅ Game info — Titles, descriptions, ratings, release dates, developers, publishers, genres, player count
• ✅ Play data — Play count, play time, last played date, favorites, hidden status
• ✅ Cocoon-specific data — RetroAchievements IDs, emulator assignments, folder assignments, region info

Exporting Gamelists

Settings → Library & Data → Export Metadata

Cocoon creates gamelist.xml files in your data directory under gamelists/{platform}/. These files follow the ES-DE format, so they’re also compatible with other frontends like EmulationStation.

How Gamelists Are Restored

Here’s the clever part — you don’t need to manually import gamelists. During first-time setup, after Cocoon scans your ROM folders, it automatically checks for existing gamelists/ in your data directory and imports any matching metadata. Games are matched by their relative file path.

So the workflow is:

1. Export Metadata before resetting or switching devices.
2. During setup, pick the same data directory (or copy the gamelists/ folder to your new data directory).
3. After the ROM scan, Cocoon automatically applies all your saved metadata — titles, descriptions, play times, favorites, everything.

Downloaded Media (Artwork)

Your scraped artwork (box art, logos, hero images) is stored in your data directory under downloaded_media/. This folder is organized by platform and media type:

Cocoon/
└── downloaded_media/
    ├── snes/
    │   ├── covers/
    │   ├── logos/
    │   └── heroes/
    ├── gba/
    │   ├── covers/
    │   └── ...
    └── ...

How It’s Restored

If you choose the same Cocoon data directory during a fresh setup, all your previously downloaded artwork is automatically available — no re-scraping needed. Cocoon’s scanner recognizes the existing media files and links them to the matching games.

This means the fastest way to get back to exactly where you were is:

1. Export Metadata and Backup Layout before resetting.
2. During fresh setup, point to the same data directory.
3. Your artwork is already there, metadata imports automatically, and you can restore your layout.

Tip: If you’re switching to a new device, copy your entire Cocoon data directory over. As long as the folder structure is intact, everything will be picked up automatically.

Export as Theme

Want to share your entire visual setup with others? Cocoon can bundle your current customizations into a theme package:

This exports your colors, sounds, wallpapers, music, smart folder assets, icon overlays, and other visual settings into a .cocoon theme file in your themes/ folder. Share it with friends or the community!

Resetting Your Grid

If things have gotten messy and you want a fresh start without using a backup:

Settings → System & Advanced → Reset Grid Layout

This clears all grid positions and puts everything back in default order. Your games, folders, and metadata are all safe — only the arrangement changes.

Full Factory Reset

If you want to start completely from scratch:

Settings → System & Advanced → Reset App Data

This clears everything — library, settings, artwork, all of it. Make sure you’ve exported your layout and metadata first if there’s anything you want to keep.

Tips

• It’s a good idea to export metadata and backup layout before big changes — like reorganizing your entire library, doing a fresh scrape, or resetting your device.
• The Export Metadata + same data directory combo is the most complete backup strategy — it preserves metadata, artwork, and (with a layout backup) your entire grid arrangement.
• Backups are small — layout backups are just JSON files with folder assets, and gamelists are XML. The big data is in downloaded_media/, which you handle by keeping the same data directory.
• When restoring a layout, Cocoon recreates smart folders and re-links games to the correct positions. Parent folders are always created before their children, so nested structures come back properly.