# config.yml

## 📘 Configuration for the nwMVP

```yml
# =====================================================
#                     Nw MVP
#           Boss Damage • Season Ranking
# =====================================================

#Contact&Support: https://discord.gg/gwXcr7c6Gq
```

***

⚙️ Main Configuration

## **1.** 🔌**S**ettings Plugin

The `settings-plugin` section defines **which plugins nwMVP integrates with**.\
Features are automatically enabled or disabled based on the selected plugins.

* **boss-plugin**\
  Selects the boss plugin used for damage tracking and events (required)
* **party-plugin**\
  Enables party-based damage and rewards\
  If set to `None`, only individual tracking is used
* **guild-plugin**\
  Enables guild and territory systems\
  If set to `None`, guild and territory features are disabled
* **hologram-plugin**\
  Displays boss and territory information as holograms\
  If set to `None`, no holograms are shown
* **regen-block-plugin**\
  Handles block regeneration for territories\
  If set to `None`, blocks will not regenerate automatically

```yaml
settings-plugin:
  # Select which boss plugin to integrate with.
  # Supported: "MythicMobs", "EliteMobs"
  boss-plugin: "MythicMobs"
  # Select which party plugin to use.
  # Supported: "Parties", "MMOCore", "GangsPlus", "UltimateTeams", "None"
  party-plugin: "None"
  # Select which guild plugin to use.
  # Supported: "MMOCore", "GangsPlus", "LegendaryGuildRemapped",
  #            "FactionsUUID", "UltimateTeams", "None"
  guild-plugin: "None"
  # Select which Hologram plugin to use.
  # Supported: "Decentholograms", "CMI", "None"
  hologram-plugin: "None"
  # Select which Regen Block plugin to use.
  # Supported: "ultimateblockregeneration", "minexfarmregen", "blockregen", "nwmvp", "None"
  regen-block-plugin: "ultimateblockregeneration"

```

***

## **2.** ⚙️**G**eneral Settings

The `general-settings` section controls the basic behavior of the **nwMVP** plugin.

* **price-decimals**\
  Defines how many decimal places are shown when displaying numbers,\
  such as prices, points, or rewards.\
  Example: `1` = show 1 decimal place
* **permissions**\
  Defines permission nodes for nwMVP commands.
  * `reload` → Permission required to use the reload command
  * `player` → Permission required for player commands (score, stats, rewards)
* **events.on-world-change-clear-score-player**\
  Controls what happens when a player **changes worlds**.
  * `true` → Clears the player’s boss score/damage immediately
  * `false` → Keeps the player’s score\
    This helps prevent players from carrying boss damage while switching worlds during a boss fight.

```yaml
general-settings:
  price-decimals: 1
  permissions:
    reload: nwmvp.reload
    player: nwmvp.player
  events:
    on-world-change-clear-score-player: true
```

***

## **3.** 💾 **Database**

The `database` section defines how **nwMVP** stores its data,\
such as boss damage, rankings, season progress, and territory information.

* **type**\
  Selects the database type to use.
  * `sqlite` → File-based database, recommended for small to medium servers
  * `mysql` → Network-based database, recommended for large or multi-server setups
* **mysql**\
  Defines MySQL connection settings.\
  This section is used **only when** `type` is set to `mysql`.
  * `host` → MySQL server address
  * `port` → MySQL server port (default: 3306)
  * `database` → Database name used by nwMVP
  * `username` → MySQL username
  * `password` → MySQL password

📌 When using `sqlite`, nwMVP automatically creates a local database file and ignores all MySQL settings.

```yaml
database:
  # Database type: "sqlite" or "mysql"
  type: "sqlite"
  # MySQL settings (only used if type is "mysql")
  mysql:
    host: "localhost"
    port: 3306
    database: "nwmvp"
    username: "root"
    password: "password"
```

***

## **4.** 📅Daily Boss Configuration

The `daily-boss` section controls **how many times players can fight bosses per day**.\
It helps prevent excessive boss farming and maintains server balance.

* **enabled**\
  Enables or disables the Daily Boss system
  * `true` → Daily limits are enforced
  * `false` → No limits (players can fight bosses unlimited times)
* **reset-time**\
  Defines how often daily attempts are reset\
  Supports time formats like `30m`, `1h`, `24h`
* **timezone**\
  Defines the timezone used for reset timing\
  Ensures resets occur at the correct server time
* **reset-daily-message**\
  Message broadcasted when daily boss attempts are reset\
  Supports color codes and MiniMessage

#### ⚙️ settings

* **max-attempts**\
  Base number of boss attempts per day for each player
* **no-attempt-message**\
  Message shown when a player tries to fight a boss with no attempts left
* **bosses-list**\
  List of boss IDs affected by the Daily Boss limit\
  Bosses not listed here are not restricted

#### 🔀 conditions (Bonus Attempts)

Defines **bonus boss attempts** granted when certain conditions are met.\
Multiple conditions can apply at the same time, and all bonuses are added together.

* **permission**\
  Grants extra attempts if the player has a specific permission
* **placeholder**\
  The `placeholder` condition grants extra boss attempts\
  based on values provided by **PlaceholderAPI**\
  (e.g. player level, stats, or custom plugin data).

  The system compares the placeholder value with the defined condition.\
  If the condition is true, bonus attempts are granted.

  #### ✅ Supported Operators

  | Operator | Meaning                  | Example                 |
  | -------- | ------------------------ | ----------------------- |
  | `==`     | Equal to                 | `%player_level% == 30`  |
  | `!=`     | Not equal to             | `%player_level% != 10`  |
  | `>`      | Greater than             | `%player_level% > 30`   |
  | `>=`     | Greater than or equal to | `%player_level% >= 30`  |
  | `<`      | Less than                | `%player_level% < 50`   |
  | `<=`     | Less than or equal to    | `%player_level% <= 100` |
* **day**\
  Grants extra attempts on specific days of the week

```yaml
daily-boss:
  enabled: false
  reset-time: "30m"
  timezone: "Asia/Bangkok"
  reset-daily-message: "&aDaily boss attempts have been reset!"
  settings:
    max-attempts: 3
    no-attempt-message: "&cYou have used up all your boss attempts for today!"
    bosses-list:
      - "SkeletalMinion"
    conditions:
      # Additional attempts if the player has a permission.
      vip:
        condition: "permission"
        value: "dailyboss.vip"
        attempts: 5
        message: "&6VIP: You now have 5 boss attempts per day!"
      # Higher-tier permission.
      elite:
        condition: "permission"
        value: "dailyboss.elite"
        attempts: 10
        message: "&bELITE: You now have 10 boss attempts per day!"
      # Condition based on a PAPI placeholder value.
      player_level:
        condition: "placeholder"
        value: "%player_level% >= 30"
        attempts: 6
        message: "&aLevel 30+: You receive 6 daily boss attempts!"
      # Special daily bonus based on the day of the week.
      day:
        condition: "day"
        value: "SATURDAY"  # Also supports MONDAY / TUESDAY / etc.
        attempts: 7
        message: "&dBonus Saturday! You receive 7 daily boss attempts!"
```

***

## **5. Season**

The **Season** system ranks players over a time period. It records boss-fight performance, converts it into **Season points**, calculates **Season Rank Points**, assigns **Tiers**, and distributes **Season rewards**.

### 1. enabled

**Purpose:** Enable/disable the entire Season system.

* `true` = Season is active (track points, ranks, rewards)
* `false` = Season is disabled

```yml
season:
  enabled: false
```

***

### **2.** name

**Purpose:** Display name of the current Season (GUI / announcements).\
Supports placeholders such as `%current_season%`.

```yml
name: "Season %current_season%: Start Adventure !"
```

***

### 3) schedule

**Purpose:** Automatically start/end the Season by date/time.

```yml
schedule:
  enabled: false
  start-date: "2025-01-01 00:00"
  end-date: "2025-03-01 00:00"
  timezone: "Asia/Bangkok"
```

* `schedule.enabled: true` → auto start/end based on dates
* `start-date`, `end-date` → Season time window
* `timezone` → timezone used for schedule evaluation

> Config note: `id` is removed; the plugin generates a UUID internally.

***

### 4) season-rank-points-calculation&#x20;

**Purpose:** Defines the **ranking formula** (Season Rank Points) using PlaceholderAPI.

```yml
formula: "%nwseasonplayer_tier_points% * 1.0 + ..."
```

* The formula supports `+ - * /`
* Players are ranked by the resulting score (higher is better)

Supported placeholders (as documented in your comments):

* `%nwseasonplayer_tier_points%`, `%nwseasonplayer_active_days%`, `%nwseasonplayer_participation%`,\
  `%nwseasonplayer_top_appearances%`, `%nwseasonplayer_boss_kills%`,\
  `%nwseasonplayer_player_deaths%`, `%nwseasonplayer_first_strike%`, `%nwseasonplayer_final_blow%`

***

### 5) bosses-list

**Purpose:** Only bosses in this list contribute to Season stats/points.

```yml
bosses-list:
  - "SkeletalMinion"
```

***

### 6) points

The **Points System** defines how many **Season points** players earn from boss fights.\
These points are accumulated throughout the Season and are used for:

* Season ranking
* Tier progression
* Reward eligibility

> ⚠️ Note:\
> These are **Season points**, not **MVP Points**.\
> MVP Points are configured separately under `mvp-points:`.

```yaml
season:
  points:
    top:
      top_1: 20
      top_2: 15
      top_3: 10
      top_10: 5
      participation: 1
    
    personal:
      top-damage: 5
      top-damage-taken: 5
      top-support-healer: 5
      first-strike: 3
      final-blow: 3
    
    special:
      no-damage-taken: "== 0:10"
      no-death-fight: "== 1:5"
      more-damage: "> 100:5"
      more-damage-taken: ">= 100:3"
      more-support-healer: "< 50:4"
```

***

#### 6.1 Top Points (Ranking-Based Points)

Points awarded based on the player’s **final ranking position** in a boss fight (usually damage ranking).

| Key             | Description                                           |
| --------------- | ----------------------------------------------------- |
| `top_1`         | Points for finishing 1st                              |
| `top_2`         | Points for finishing 2nd                              |
| `top_3`         | Points for finishing 3rd                              |
| `top_10`        | Points for finishing within Top 10                    |
| `participation` | Minimum points for participating (dealing any damage) |

This ensures that even non-top players still gain small progress for participating.

***

#### 6.2 Personal Points (Individual Achievements)

Points awarded for **special personal achievements** during a boss fight.

| Key                  | Description                            |
| -------------------- | -------------------------------------- |
| `top-damage`         | Highest total damage dealt             |
| `top-damage-taken`   | Highest damage taken (tank role)       |
| `top-support-healer` | Highest healing / support contribution |
| `first-strike`       | First player to hit the boss           |
| `final-blow`         | Player who delivers the killing blow   |

These rewards encourage different playstyles, not only raw damage.

***

#### 6.3 Special Points (Conditional Points)

Special points are awarded when **specific conditions** are met.

**Format**

```
"OPERATOR VALUE:POINTS"
```

| Part       | Description                             |
| ---------- | --------------------------------------- |
| `OPERATOR` | `==`, `!=`, `>`, `>=`, `<`, `<=`        |
| `VALUE`    | Number to compare against               |
| `POINTS`   | Points awarded if the condition is true |

**Examples**

| Key                   | Condition | Result     |
| --------------------- | --------- | ---------- |
| `no-damage-taken`     | `== 0`    | +10 points |
| `more-damage`         | `> 100`   | +5 points  |
| `more-damage-taken`   | `>= 100`  | +3 points  |
| `more-support-healer` | `< 50`    | +4 points  |

This system allows highly flexible performance-based rewards.

***

### 7) tier

The **Tier System** provides visible progression throughout the Season.\
Players advance through tiers based on accumulated Season points.

```yml
tier:
  enabled: true
  ranks:
    unranked:
      name: Unranked
      point: 0
    bronze:
      name: Bronze
      point: 100
    silver:
      name: Bronze
      point: 300
    gold:
      name: Bronze
      point: 600
    platinum:
      name: Bronze
      point: 1000
```

#### How It Works

* `enabled`\
  Enables or disables the Tier system entirely.
* `ranks`\
  Defines each tier:
  * `name` → Display name
  * `point` → Minimum Season points required

Players automatically **rank up** when their points reach the next tier threshold.

> Tier points are **separate** from final Season Rank Points.

***

### 8) event-boots

**Event Boosts** temporarily multiply Season points during specific days and time ranges.\
They are commonly used for weekend events or peak-hour activities.

```yml
event-boost:
  enabled: false
  schedule:
    x15:
      day: Saturday
      time: 18:00-21:00
      multiplier: 1.5
    x2:
      day: Wednesday
      time: 20:00-23:00
      multiplier: 2.0
```

#### How It Works

* `enabled`\
  Toggles Event Boosts on or off.
* `schedule`\
  Defines one or more boost events:
  * `day` → Day of the week
  * `time` → Time window (`HH:mm-HH:mm`)
  * `timezone` → Timezone reference
  * `multiplier` → Points multiplier (e.g. `1.5` = 1.5×)

During an active boost, **all Season points earned are multiplied** by the configured value.

> Multiple events can exist.\
> If events overlap, multipliers may stack depending on server implementation.

***

### 9) rewards

The **Rewards** section defines commands that are executed when the Season ends (or when players claim rewards).

```yml
rewards:
    lists:
      top_1:
      - give %player% diamond 32
      top_2:
      - give %player% gold_ingot 64
      participation:
      - give %player% iron_ingot 32
      unranked:
      - give %player% iron_ingot 32
      bronze:
      - give %player% iron_ingot 32
      silver:
      - give %player% iron_ingot 32
      gold:
      - give %player% iron_ingot 32
      platinum:
      - give %player% iron_ingot 32
```

#### How Rewards Work

* `lists` defines reward categories:
  * **Ranking-based**: `top_1`, `top_2`
  * **Participation-based**: `participation`
  * **Tier-based**: `unranked`, `bronze`, `silver`, `gold`, `platinum`
* Each entry is a **server command**
* `%player%` is replaced with the player’s name
* Commands are executed **in order**

Rewards can be:

* Items
* Currency
* Permissions
* Drop Table triggers (if integrated)

***

### 10) annountment

**Purpose:** Messages for Season events.

* `start-season`, `end-season`, `reset-season`
* `notify-player-reward` can include MiniMessage click actions
* `already-claimed-reward`
* `tier-rank-up` supports `{old_rank}` and `{new_rank}`

```yml
announcement:
  start-season:
    - "MVP SEASON START"
    - "Start"
  end-season:
    - "MVP SEASON START"
    - "Start"
  reset-season:
    - "MVP SEASON Reset"
  notify-player-reward:
    - "reward for you"
    - "<click:run_command:'/nwmvp season reward'> <yellow><u>[Click to claim]</u></yellow> </click>"
  already-claimed-reward:
    - "&cYou've already claimed this season's rewards!"
  tier-rank-up:
    - "rank up"
    - "{old_rank} -> {new_rank}"
```

***