# Config Overview

Structure of Mira's configuration files. Every file can be edited directly; for most changes, `/mira reload` is enough afterward instead of a server restart.

## Main Configuration (config.yml)

Location: `plugins/Mira/config.yml`

This file only contains shared base settings. Feature-specific settings live in the individual files under `plugins/Mira/modules/`.

Most important sections:

```yaml
general:
  # Seconds until confirmations (e.g. shop purchases) expire.
  # At least 5 seconds; smaller values are raised to 5.
  confirmation-timeout: 30

economy:
  # Starting balance for new accounts
  start-balance: 1000.0
  # Currency name and symbol
  currency-name: "Coin"
  currency-name-plural: "Coins"
  currency-symbol: "⛃"
  # Limits and minimum amount
  max-balance: 1000000000.0
  min-transfer: 0.01
  # Entries per /baltop page
  baltop-entries-per-page: 10

cooldown:
  # Fallback cooldown for commands without their own value
  default: 0
  # Cooldowns for core commands (module cooldowns are in modules/*.yml)
  commands:
    pay: 1

cost:
  # Costs for core commands (0 = free)
  commands: {}

warmup:
  # Default wait time for all teleport commands
  default:
    duration: 3
    cancel-on-move: true
    # true = any damage cancels the warmup (default: movement only)
    cancel-on-damage: false
    display: actionbar
    particles:
      enabled: true
      type: PORTAL
      count: 10
      radius: 0.5
  # Warmups for core commands
  commands: {}
```

## Module Configurations (modules/*.yml)

Location: `plugins/Mira/modules/<module>.yml`

Every module file can be turned on or off via `enabled: true/false`. Many modules additionally have their own `cooldown`, `cost` and `warmup` settings in the same format as in `config.yml`.

| Module File | Category | Most Important Settings |
|---|---|---|
| `afk.yml` | AFK | Auto-AFK timeout, AFK kick time, broadcast, tab list decoration, anti-AFK machine detection |
| `betterhud.yml` | Integration | BetterHud popup integration for economy and teams |
| `chat.yml` | Chat | Chat format, display name, LuckPerms integration, Nexo glyphs, team/alliance chat |
| `claim.yml` | Claims | Land protection: world modes, protection flags, claim block economy, PvP rules, wilderness, sieges, team plots, storage backend |
| `holograms.yml` | Holograms | View distance, line spacing, placeholder update rate, text shadow, background |
| `homes.yml` | Homes | Home limit, name length, world blacklist, cooldown, cost, warmup |
| `jobs.yml` | Jobs | Max jobs, leveling, quests, boosts, dynamic pay, integrations, job shop, exploit protection |
| `joinleave.yml` | Join/Leave | Join/leave texts, MOTD, sounds, titles, action bar, vanish suppression |
| `messaging.yml` | Messages | Formats for private messages, maximum message length |
| `mobteleport.yml` | Mob Teleport | Radius, leash reattachment, invulnerability, entity filter, region protection |
| `moderation.yml` | Moderation | Warn actions, jail rules, CommandSpy blacklist, vanish |
| `joinprotection.yml` | Join Protection | Duration, mode (all or PvP only), end on attack, boss bar colour and style |
| `nick.yml` | Nicknames | Nick length, colors, formatting |
| `permissions.yml` | Command Visibility | Tab completion only shows permitted commands, hides namespaced duplicates |
| `rtp.yml` | Random Teleport | Radius, height range, attempts, world border, biome, queue, claim protection, cost |
| `shop.yml` | Chest Shops | Shop limit, hopper protection, price limits, tax, sounds, integrations |
| `sleep.yml` | Sleep | Sleep percentage, skip speed, AFK exclusion, world mode |
| `reminder.yml` | Reminder | Interval of the chat tips, disable shipped tips, own tips with weight |
| `spawn.yml` | Spawn | First spawn, respawn logic, cooldown, cost, warmup |
| `stations.yml` | Stations | Virtual workstation commands, hub menu |
| `tab.yml` | Tab List | Tab name, LuckPerms integration, Nexo glyphs, optional fixed tab layout |
| `team.yml` | Teams | Limits, ranks, team level, score, bank, menu, CoreProtect logging |
| `teleport.yml` | Teleport | Safety check, combat lock, back positions, cooldown, cost, warmup |
| `tpa.yml` | TPA | Request timeout, distance limit, cross-dimension, cooldown, cost, warmup |
| `utility.yml` | Utility | God persistence, near radius, toggleable utility commands, cost/cooldowns |
| `warps.yml` | Warps | Name length, cooldown, cost, warmup |
| `websession.yml` | Web Interface | Configuration of the web interface for `/cweb` |
| `world.yml` | World | Gamerule menu, custom gamerule presets |
| `leafdecay.yml` | Fast Leaf Decay | Leaf delay, particles and sound, world mode |
| `mobtoegg.yml` | Mob to Egg | Chance, blocked mobs, pets and name tags, delivery, effects, world mode |
| `worldspawn.yml` | World Spawn | Toggle for `/setworldspawn` |

### Common Structure of All Modules

```yaml
enabled: true  # Enables/disables the entire module

# Command-specific cooldowns (seconds, 0 = disabled)
cooldown:
  commands:
    home: 180
    warp: 600

# Command-specific costs (economy, 0 = free)
cost:
  commands:
    home: 0
    rtp: 100.0

# Command-specific warmups (wait time before action/teleport)
warmup:
  commands:
    home:
      duration: 2
      cancel-on-move: true
      cancel-on-damage: false
      display: actionbar
      particles:
        enabled: true
        type: PORTAL
```

> **Note:** Bypass permissions can be used to bypass these restrictions: `cooldown.bypass.<command>`, `cost.bypass.<command>` and `warmup.bypass.<command>` (or `.*` for all commands of a module).

## Messages (messages.yml)

Location: `plugins/Mira/messages.yml`

All texts that players see are stored here centrally in MiniMessage format (colors like `<red>`, `<b>`, `<#4fc3f7>` etc.) and can be freely customized.

Every module has its own chat prefix in the style of `TEAMS »`, `JOBS »` or `MOD »`, each with its own color. Which prefix appears in front of a message is controlled by the `prefixes:` block at the top of the file: the first part of the message key selects the entry (`team.create-success` uses `prefixes.team`). Sections without their own entry use `prefixes.default`. Colors, labels and the separator can be changed freely there.

```yaml
prefixes:
  default: "<b><#f55a7d>MIRA</#f55a7d></b> <#ffb2bd>»</#ffb2bd> "
  team: "<b><#00e5ee>TEAMS</#00e5ee></b> <#00e5ee>»</#00e5ee> "
  jobs: "<b><#ffa502>JOBS</#ffa502></b> <#ffa502>»</#ffa502> "
```

**Color system:** the bundled texts follow a fixed scheme so it is immediately clear what a highlight refers to: player names in aqua, named things like homes, warps, teams, jobs or cosmetics in yellow, items in gold, numbers, money, times and coordinates in green, errors in red. White is reserved for free text (reasons, messages, descriptions). All of it can be changed freely.

> **Note:** Existing servers keep their old `messages.yml` including all texts when updating. To adopt the new look completely, delete the file once (back up your own customizations first); it is recreated on the next start.

> **Tip:** After changes to `messages.yml`, `/mira reload` is enough; a restart is not necessary.

## Jobs: Custom Definition Files

Jobs are a special case: in addition to `modules/jobs.yml` (general job settings), each job has its own file under `modules/jobs/`, for example `miner.yml` or `farmer.yml`.

```yaml
name: "Miner"
color: "<#FFB400>"           # Hex color
short-name: "MIN"
icon: "DIAMOND_PICKAXE"
description: "Mine ores for profit"
max-level: 100
actions:
  BREAK:
    DIAMOND_ORE:
      money: 10.0
      xp: 5.0
    COAL_ORE:
      money: 2.0
      xp: 1.0
titles:
  "1": "Novice Miner"
  "25": "Expert Miner"
level-up-rewards:
  "10": "give <player> diamond 5"
```

`modules/jobs.yml` controls the general settings:

```yaml
enabled: true
jobs:
  max-jobs: 2              # Max. simultaneously active jobs per player
  leveling:
    max-level: 100
    xp-per-level: 100.0
  quests:
    enabled: true
    daily-reset: "00:00"
  boosts:
    enabled: true
  dynamic-pay:
    enabled: true
    player-count-multiplier: 0.5
  shop:
    enabled: true
```