Themes

Themes let you completely transform how Cocoon looks and sounds. A single theme can change your colors, replace every sound effect, set custom wallpapers, add background music, and even put decorative frames on your game icons. You can also mix and match pieces from different themes to build your perfect setup.

Using a Theme

Installing a Theme

Themes are folders you drop into your Cocoon data directory:

1. Find or download a theme (check the Cocoon community for shared themes).
2. Copy the theme folder into your Cocoon folder → themes/:

Cocoon/
└── themes/
    └── retro-neon/
        ├── theme.json
        ├── preview.png
        └── (other theme files)

3. Open Cocoon and go to Settings → Appearance → Custom Themes.
4. You’ll see your theme in the picker — select it to apply!

What Can a Theme Change?

Mix and Match

Here’s where it gets fun — you don’t have to use everything from one theme. Cocoon lets you cherry-pick components from different themes:

• Colors from “Pink” 🎨
• Sound effects from “Zelda” 🔊
• Wallpaper from “Persona 5” 🌆
• Music from “Awesome Cocoon Remix” 🎵

When you apply a theme, you’ll see checkboxes for which parts you want to use. Your choices are saved and remembered.

Creating Your Own Theme

Want to make a theme? It’s just a folder with a theme.json file and your assets. Here’s what the folder looks like:

my-theme/
├── theme.json          ← Required
├── preview.png         ← Shows up in the theme picker
├── sounds/             ← Custom sound effects
│   ├── select.ogg
│   ├── navigate.ogg
│   └── ...
├── music/              ← Background tracks
│   ├── morning.mp3
│   └── night.mp3
├── wallpapers/         ← Background images or videos
│   ├── main.png
│   └── external.png
├── smart_folders/      ← Artwork for smart folder types
│   └── favorites/
│       └── icon.png
└── icon_overlays/      ← Per-platform icon frames
    └── snes/
        ├── mask.png
        └── overlay.png

Everything except theme.json is optional — include only what you want to customize.

The theme.json File

At minimum, you just need a name:

{
  "name": "Theme Example",
  "author": "YourName",
  "version": "1.0",
  "description": "A theme for Cocoon"
}

You can also include a custom color scheme:

{
  "color_scheme": {
    "background": "#1a1a2e",
    "surface": "#16213e",
    "primary": "#e94560",
    "onPrimary": "#ffffff",
    "selectionHighlightGlow": "#e94560"
  }
}

And music settings:

{
  "music": {
    "mode": "TIME_BASED",
    "schedule": [
      { "hour": 6, "track": "music/morning.mp3" },
      { "hour": 18, "track": "music/evening.mp3" },
      { "hour": 22, "track": "music/night.mp3" }
    ]
  }
}

Sound Effect Names

Name your sound files after the action they go with:

select, back, navigate, folder_open, game_launch, screen_swap, grid_resize, reorder, edit_mode, saving, context_menu, slider

Any common audio format works (OGG, MP3, WAV).

Icon Overlays

These let you add platform-specific frames to your game tiles:

• mask.png — Controls which parts of the game art are visible (white = visible, black = hidden)
• overlay.png — Drawn on top of the artwork (great for console-shaped frames or decorative borders)

Put them in icon_overlays/{platformId}/ — for example, icon_overlays/snes/ or icon_overlays/psx/.

Exporting Your Setup

Happy with how Cocoon looks? You can export your current customizations as a theme folder to share with others. The export bundles up your wallpapers, sounds, music, colors, and other assets into a ready-to-share package.

Good to Know

• Restart Cocoon after adding a new theme folder so it gets picked up.
• A preview.png in the theme folder shows up as its thumbnail in the picker.
• If a wallpaper causes issues, don’t worry — Cocoon auto-resets wallpapers after 3 rapid crashes.