Icon Overlays

Icon overlays let you dress up your game tiles with platform-specific frames — think cartridge shapes for SNES games, disc textures for PlayStation, or custom borders that make each system’s tiles look distinct. They’re one of the coolest visual touches you can add to your grid.

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. Many community themes include platform-specific overlays as part of the package. When you apply a theme, you’ll see an “Icon Overlays” checkbox — toggle it on to use the theme’s overlays.

You also get to choose how the overlays are applied:

• Use from theme — Overlays stay in the theme folder. If you switch themes later, these overlays go away.
• Copy to my library — Overlays are copied to your personal overlay folder. They’ll stick around even if you change themes.

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.