Skins & Tilesets

Using Skins

Select a skin via Extras > Appearance > Skin. The active skin is stored in the active_skin setting and persists across sessions.

If a skin has variants (e.g., light/dark), you can switch variants from the same menu under the skin's submenu.

Creating a Skin

A skin is a folder inside the skins/ directory containing at minimum a skin.json and a tileset image.

Quick Start

1. Create a folder in skins/ (e.g., skins/my_skin/)
2. Create a tileset.png — a sprite sheet with 64×64 pixel tiles
3. Create a skin.json with metadata and asset references
4. Restart the game and select your skin from the menu

Folder Structure

skins/
└── my_skin/
    ├── skin.json          ← Required: metadata and asset paths
    ├── tileset.png        ← Required: main sprite sheet
    ├── preview.png        ← Optional: thumbnail for skin selector
    ├── tilesets/           ← Optional: variant tilesets
    ├── animations/         ← Optional: animation sprite strips
    ├── sounds/             ← Optional: custom sound effects
    └── fonts/              ← Optional: custom fonts

skin.json Structure

{
  "api_version": "1.0",
  "metadata": {
    "name": "My Custom Skin",
    "author": "YourName",
    "description": "A short description",
    "version": "1.0"
  },
  "assets": {
    "tileset": "tileset.png"
  }
}

Fields

Tileset Layout

The tileset is a sprite sheet of 64×64 pixel tiles arranged in a grid. Each tile position has a defined role:

• Numbers 1-8 — the number tiles (top rows, left side)
• Covered tile — unrevealed tile appearance
• Blank revealed — empty tile after reveal
• Flag — flagged tile
• Mine — mine tile (revealed on loss)
• Exploded mine — the mine that was clicked
• Wrong flag — flag on a non-mine (shown on loss)
• Question mark — question mark tile (if enabled)
• Border/chrome — optional border tiles

Use the included tileset_template.png as a reference for exact positions. Each tile must be exactly 64×64 pixels. Save as PNG with transparency.

Variants

Offer multiple color schemes in a single skin by adding a variants section to skin.json:

"variants": {
  "default": {
    "name": "Classic",
    "tileset": "tilesets/default.png"
  },
  "dark": {
    "name": "Dark Mode",
    "tileset": "tilesets/dark.png"
  }
}

Players switch variants via Extras > Appearance > Skin > [Your Skin] > Variant.

Animations

Animations use horizontal sprite strips — multiple frames arranged left to right in a single image.

Animatable elements: mine explosions, tile reveals, smiley faces, flag placement.

"animations": {
  "mine_explode": {
    "file": "animations/explosion.png",
    "frames": 8,
    "duration_ms": 400,
    "loop": false
  }
}

Sounds

Add custom sounds by placing audio files in a sounds/ folder and referencing them in skin.json. Supported formats: WAV, OGG.

Common sound events: tile click, flag place, flag remove, chord, mine hit, win, lose.

Packaging & Sharing

• Zip the entire skin folder for sharing.
• Recipients extract it into their skins/ directory.
• Include a preview.png (recommended: 256×256) for the skin selector thumbnail.
• Use lowercase folder names with underscores (no spaces or special characters).