Icon Overlays

Icon overlays let you dress up your game tiles with platform-specific frames. Cartridge shapes for SNES games, disc textures for PlayStation, or custom borders that make each system’s tiles look distinct.

How They Work

Each overlay consists of up to two images that work together:

Both are optional. You can use just a mask (for shape only), just an overlay (for a border/frame), or both together for the full effect.

The rendering order

1. Your game’s box art is drawn at full size
2. The mask clips it to shape (using alpha compositing, only the white parts of the mask remain visible)
3. The overlay is drawn on top of everything

The result is a game tile that looks like a physical cartridge, disc, or whatever creative shape the overlay designer imagined.

Getting Overlays

From Themes

The easiest way to get overlays is through themes or Silk Pod. Many community themes and asset packs include platform-specific overlays. When you open the Theme Picker in Settings → Appearance, you’ll see an Icon Overlays row with its own dropdown. Pick whichever overlay pack you want independently of your colour theme, sounds, or anything else.

Adding Your Own

You can create or download overlays and place them in your Cocoon data directory:

Cocoon/
└── icon_overlays/
    ├── snes/
    │   ├── mask.png
    │   └── overlay.png
    ├── psx/
    │   ├── mask.png
    │   └── overlay.png
    ├── gb/
    │   ├── mask.png
    │   └── overlay.png
    └── (any platform ID)/
        ├── mask.png
        └── overlay.png

Name each subfolder after the platform’s folder ID (the same ones listed on the Compatibility page, like snes, psx, gb, n64, etc.).

Your personal overlays always take priority over theme overlays, so you can mix a theme’s overlays for most platforms with your own custom ones for specific systems.

Supported Formats

Overlay and mask images can be PNG, JPG, or WEBP. PNG is recommended since it supports transparency, which you’ll need for proper masking and overlay effects.

Which Platforms Can Have Overlays?

Any platform! There’s no fixed list. If a platform has a folder ID, it can have overlays. You could make overlays for common systems like SNES and PlayStation, or get creative with overlays for Game Boy, N64, Dreamcast, or even fantasy consoles like PICO-8.

Creating Your Own Overlays

Want to make custom overlays? Here are some tips:

Making a Mask

• Use a white silhouette on a transparent background
• White pixels = visible game art, transparent/black pixels = cut away
• Match the aspect ratio of your game tiles (usually close to square)
• Common shapes: rounded rectangles, cartridge outlines, disc circles, handheld screen shapes

Making an Overlay

• Use a transparent PNG with your frame/border artwork
• The overlay is drawn at the full tile size, so make it the same dimensions as your mask
• Keep the center mostly transparent so the game art shows through
• Add details like: cartridge label areas, disc center holes, plastic textures, reflections, console branding

Size Recommendations

There’s no strict size requirement, but 512×512 pixels or larger is a good target. Cocoon will scale them to fit the tile size. Larger images look sharper on high-resolution screens.

Tips

• Overlays are cached in memory per-platform, so they don’t slow down scrolling.
• When overlays are active, Cocoon skips the default tile background styling (gradients and inner shadows) to let the overlay shine.
• If you want to remove all overlays and go back to plain tiles, just delete your icon_overlays/ folder or uncheck the option when applying a theme.
• You can preview how overlays look by applying them and scrolling through your grid. Changes take effect immediately.