# Configuration Files Overview

CelestialCosmetics splits its configuration across **several files, organised into folders** instead of one giant `config.yml`. This keeps each concern isolated and makes it far easier to manage a server with hundreds of cosmetics.

Everything lives under `plugins/CelestialCosmetics/` and is merged into a single configuration in memory at startup — you can reference values across files (e.g. a set in `sets.yml` referencing a tag defined in `cosmetics/tags.yml`) with no extra syntax.

```
plugins/CelestialCosmetics/
├── config.yml
├── crates.yml
├── messages.yml
└── cosmetics/
    ├── tags.yml
    ├── rebirth.yml
    ├── customstat1.yml / customstat2.yml / customstat3.yml
    ├── namecolors.yml
    ├── chatcolors.yml
    ├── rankcolors.yml
    ├── rank-backgrounds.yml
    ├── emojis.yml
    ├── glows.yml
    ├── joinmessages.yml
    ├── leavemessages.yml
    ├── chatemojis.yml
    └── sets.yml
```

| File | Contains |
|---|---|
| `config.yml` | General settings: **storage (SQLite/MySQL)**, menu layout, economy, category toggles, rank-defaults, color fallbacks |
| `cosmetics/tags.yml` | All Tag cosmetics |
| `cosmetics/rebirth.yml` | All Rebirth Color styles |
| `cosmetics/customstat1.yml` / `2` / `3` | The 3 Custom Stat slots — same shape as `rebirth.yml`, each pointed at its own placeholder |
| `cosmetics/namecolors.yml` | All Name Color cosmetics |
| `cosmetics/chatcolors.yml` | All Chat Color cosmetics |
| `cosmetics/rankcolors.yml` | Rank **Effects** + the whole [Rank System](Rank-System) config (ranks, weight, template, offsets) |
| `cosmetics/rank-backgrounds.yml` | Rank **Background** plates — see [Rank Backgrounds](Rank-Backgrounds) |
| `cosmetics/emojis.yml` | All Emoji cosmetics (glyph shown after the tag) |
| `cosmetics/glows.yml` | All Glow cosmetics (colored player outline) — see [Glows](Glows.md) |
| `cosmetics/joinmessages.yml` | All custom Join Message cosmetics — see [Join Messages](Join-Messages.md) |
| `cosmetics/leavemessages.yml` | All custom Leave Message cosmetics — see [Leave Messages](Leave-Messages) |
| `cosmetics/chatemojis.yml` | All Chat Emoji `:shortcode:` definitions — see [Chat Emojis](Chat-Emojis.md) |
| `cosmetics/sets.yml` | All Sets (bundles of the above) |
| `crates.yml` | All Crates and their reward tables, including pity, daily-key settings, and default block locations |
| `messages.yml` | Every player-facing message, plus configurable GUI lore templates |

## Editing Safely

1. Edit files directly with any text editor while the server is running (or stopped — either is fine).
2. Run `/cosmetics reload` (or the Reload button inside `/cosmetics admin`) to apply changes.
3. Check console for warnings — invalid cosmetic references (e.g. a set pointing at a tag id that doesn't exist) are logged clearly at reload time rather than causing a crash.

## Automatic Migration

Two migrations happen automatically on startup, no action needed:

1. **Single-file → multi-file.** If you're upgrading from a version that used one big `config.yml`, the plugin splits it into the separate files above, preserving all your existing cosmetics.
2. **Flat → folders (since 4.15.0).** If you're upgrading from a version where every `*.yml` sat directly in `plugins/CelestialCosmetics/` (the pre-4.15 layout), each cosmetic file is **moved** into `cosmetics/` — a plain file rename, so your comments and formatting are preserved exactly, nothing is re-parsed or rewritten. `crates.yml` and `messages.yml` were already in the right place and aren't touched.

A confirmation is printed to console either way. **Back up the plugin folder before upgrading regardless.**

## The `config.yml` General Settings

Key sections you'll touch most:

```yaml
storage:
  type: sqlite            # sqlite (single server) | mysql (network)
  file: "cosmetics.db"
  mysql: { host: localhost, port: 3306, database: celestialcosmetics, username: root, password: '' }

categories-enabled:       # turn whole cosmetic types on/off
  rankbg: true
  chatemoji: true
  # ...

economy:
  economy-mode: vault     # vault | eddungeons | commands
  currency: "credits"

rebirth-source-placeholder: "%eddungeons_leveling_level_rebirth_formatted%"
chatcolor-default: "&f"
namecolor-default: "&f"

crate-holograms:          # floating Limited/Normal label over crate blocks
  enabled: true            # requires FancyHolograms; see Crates
```

Full breakdown of the `menu` section: [GUI Customization](GUI-Customization).
Full breakdown of `storage`: [Network Sync](Network-Sync).
Full breakdown of `economy`: [Economy Integration](Economy-Integration).
Full breakdown of the rank config: [The Rank System](Rank-System).
Full breakdown of `crate-holograms` and default block locations: [Crates](Crates.md#default-block-locations-config).

## Anatomy of a Single Cosmetic Entry

Every cosmetic (tag, name color, chat color, rank color, emoji) follows the same basic shape:

```yaml
tags:
  dragon:
    display: "&#fc6c00Dragon"
    value: "&#fc0000&l[&#fc6c00&lDRAGON&#fc0000&l]"
    icon: DRAGON_HEAD
    permission: celestial.cosmetics.tag.dragon
    description:                 # optional — overrides the default lore template
      - "&fA fierce dragon-themed tag."
    texture: "eyJ0ZXh0..."        # optional — only if icon: PLAYER_HEAD
```

Rebirth styles have a slightly different shape (prefix/text/suffix/gradient instead of a flat `value`) — see [Cosmetic Types → Rebirth Color](Cosmetic-Types.md#rebirth-color).

Next: [Cosmetic Types](Cosmetic-Types.md)