Theme JSON Reference

This page documents every field in theme.json and the full folder structure of a Cocoon theme. Use this if you’re building themes by hand or want to understand what the Theme Builder generates.

Folder Structure

A theme lives in a single folder inside your Cocoon/themes/ directory:

my-theme/
├── theme.json            # Theme definition (required)
├── preview.png           # Thumbnail for the picker (recommended)
├── wallpaper.png         # Main wallpaper (top screen)
├── wallpaper_ext.png     # External wallpaper (bottom screen)
├── sounds/
│   ├── navigate.wav
│   ├── select.wav
│   ├── back.wav
│   └── ...               # One file per sound slot
├── icon_overlays/
│   └── {platform}/
│       ├── overlay.png
│       └── mask.png
├── smart/
│   ├── {folder-type}/
│   │   ├── icon.png
│   │   ├── hero.png
│   │   └── logo.png
│   └── {folder-type}/{platform}/
│       ├── icon.png
│       ├── hero.png
│       └── logo.png
└── music/
    └── ...               # Audio files

Asset packs use a simpler structure since they only contain one category.

theme.json

The root object in theme.json has these top-level fields:

{
  "name": "My Theme",
  "author": "YourName",
  "version": "1.0",
  "description": "A short description of the theme.",
  "theme_mode": "DARK",
  "color_scheme": { ... },
  "wallpaper": "wallpaper.png",
  "wallpaper_external": "wallpaper_ext.png",
  "music": [ ... ],
  "settings": { ... },
  "volume": { ... },
  "asset_refs": [ ... ]
}

All fields except name are optional.

Metadata

Theme Mode

Sets the base color mode. Custom colors in color_scheme are applied on top of this base.

Color Scheme

The color_scheme object controls every color in the UI. All fields are optional — omitted fields keep the user’s existing value.

Every value is a hex color string ("#RRGGBB" or "#AARRGGBB").

Example:

"color_scheme": {
  "background_gradient_start": "#1a1a2e",
  "background_gradient_end": "#16213e",
  "text_primary": "#ffffff",
  "text_secondary": "#a0a0b0",
  "accent_gradient_start": "#e94560",
  "accent_gradient_end": "#c81d4e"
}

Wallpapers

Supports PNG, JPG, WEBP, GIF, MP4, and WEBM. Video files loop automatically.

Music

The music field is an array of track objects for background music:

"music": [
  {
    "file": "music/morning.mp3",
    "time_start": "06:00",
    "time_end": "12:00"
  },
  {
    "file": "music/afternoon.mp3",
    "time_start": "12:00",
    "time_end": "18:00"
  }
]

Tracks can be time-scheduled (plays during a time window) or used in playlist mode.

Settings

The settings object controls display behavior. All fields are optional.

Example:

"settings": {
  "iconRoundness": 0.15,
  "iconScale": 0.9,
  "heroDisplayStyle": "FULLSCREEN",
  "heroGradientStyle": "BLACK_GRADIENT"
}

Volume

Asset References

The asset_refs array lets a theme reference external asset packs. When someone downloads the theme from Silk Pod, referenced packs are automatically downloaded too.

"asset_refs": [
  {
    "id": "pack-unique-id",
    "name": "Cool Icon Pack",
    "category": "icon_overlays",
    "version": "1.0"
  }
]

Sound Effect Files

Place sound files in the sounds/ subfolder. Cocoon maps files by name (without extension). Use underscores in filenames.

Supported formats: WAV, MP3, OGG, FLAC.

Icon Overlays

Icon overlays live in icon_overlays/{platform}/:

icon_overlays/
├── gba/
│   ├── overlay.png     # Drawn on top of game art
│   └── mask.png        # White = visible, black = hidden
├── nds/
│   ├── overlay.png
│   └── mask.png
└── ...

Platform names match Cocoon’s internal platform identifiers (e.g. gba, nds, n64, psx, snes, etc.).

Smart Folder Assets

Smart folder assets live in smart/:

smart/
├── favorites/
│   ├── icon.png        # Folder icon on the grid
│   ├── hero.png        # Hero background (top screen)
│   └── logo.png        # Logo/wordmark (top screen)
├── recent/
│   └── ...
├── most_played/
│   └── ...
└── favorites/gba/      # Per-platform override
    ├── icon.png
    ├── hero.png
    └── logo.png

Folder type names match Cocoon’s smart folder identifiers. Per-platform subdirectories let you provide different art for each console within a folder.