## Introduction
The **`bosses` folder** contains configuration files for each boss that you want to be managed by **nwMVP**.\
In this folder, you can define how each boss behaves and how nwMVP should handle it.
You can configure, for example:
* How many top-ranked players will receive rewards when the boss is defeated
* The boss operating mode (such as Individual, Party, Guild, or other modes)
* Boss health scaling and other combat-related settings
* Reward configurations and drop behavior
* Particle effects when the boss spawns
* Custom messages and notifications related to the boss
Each boss has its own configuration file, allowing you to fully customize the gameplay experience for different bosses on your server.
***
## Boss Settings
This section defines how a boss behaves in **nwMVP**, including ranking rules, score calculation mode, boss health scaling, and reward distribution.
### 1. max-top-rewards
Defines the maximum number of top-ranked players (or groups) who will receive rewards when the boss is defeated.
**How it works:**
* After the boss dies, players are ranked based on the configured scoring system
* Rewards are given only to the top ranks defined by this value
```yaml
max-top-rewards: 5
```
***
### 2. mode
Defines the boss operating mode.\
This mode determines **how player scores are collected and grouped** when attacking the boss.
**Available Modes:**
```yaml
mode: "NORMAL" # NORMAL, INDIVIDUAL, PARTY, GUILD
```
#### NORMAL
Default behavior.
* If a player **does not have a party**, their score is tracked **individually**
* If a player **is in a party**, their score is tracked **as a party**
* This mode allows both solo and party play seamlessly
**Use case:**\
Public bosses where both solo players and parties can compete fairly.
***
#### INDIVIDUAL
Individual-only scoring.
* All damage and contribution are tracked **per player**
* Party or guild status is ignored
* Every player competes on their own
**Use case:**\
Competitive bosses where individual performance matters most.
***
#### PARTY
Party-based scoring only.
* Scores are tracked **per party**
* Only players **in a party** can contribute
* Players without a party **will not gain any score**
**Use case:**\
Bosses designed specifically for coordinated party play.
***
#### GUILD
Guild-based scoring only.
* Scores are tracked **per guild**
* Only players **in a guild** can contribute
* Players without a guild **will not gain any score**
**Use case:**\
Territory wars or large-scale guild competition.
***
### 3. scale-health-by-players
Dynamically scales the bossβs health based on the number of nearby players when the boss spawns.
This prevents bosses from being too easy or too difficult depending on player count.
**Configuration:**
```yaml
scale-health-by-players:
enabled: true
check-player-in-regions: true
health-scale-multiplier: 0.2
radius: 30
```
**enabled**
* `true` β Boss health is scaled dynamically
* `false` β Boss uses its default health
***
**check-player-in-regions**
* `true` β Counts players **inside the configured territory region**
* `false` β Counts players based on **distance (radius)** from the boss spawn point
***
**health-scale-multiplier**
* Multiplier applied per player
* Formula:
```
Final Health = Base Health Γ (1 + (Player Count Γ Multiplier))
```
**Example:**
* 5 players
* Multiplier = 0.2\
β‘ Health = Base Γ (1 + 1.0) = 200%
***
**radius**
* Used **only when `check-player-in-regions` is false**
* Counts players within this radius (in blocks) around the boss spawn location
***
### 4. rewards
Controls which reward types are enabled for this boss.
You can selectively enable or disable each reward category.
**Configuration:**
```yaml
rewards:
top: true
firststrike: true
finalblow: true
top_damage_dealer: true
top_damage_taken: true
top_support_healer: true
personal_reward: true
```
#### Reward Options
| Option | Description |
| -------------------- | ----------------------------------------------------- |
| `top` | Rewards for top rankings (based on `max-top-rewards`) |
| `firststrike` | Reward for the first player who hits the boss |
| `finalblow` | Reward for the player who delivers the killing blow |
| `top_damage_dealer` | Reward for the highest damage dealer |
| `top_damage_taken` | Reward for the player who takes the most damage |
| `top_support_healer` | Reward for the top healer/support |
| `personal_reward` | Personal rewards based on individual contribution |
***
### Example Configuration
```yaml
settings:
max-top-rewards: 5
mode: "NORMAL"
settings:
scale-health-by-players:
enabled: true
check-player-in-regions: true
health-scale-multiplier: 0.2
radius: 30
rewards:
top: true
firststrike: true
finalblow: true
top_damage_dealer: true
top_damage_taken: true
top_support_healer: true
personal_reward: true
```
***
## Boss Core Configuration
This section defines **how a boss is identified, spawned, displayed, restricted, and visualized** in **nwMVP**.\
These settings connect nwMVP with your boss plugins, spawners, regions, holograms, and visual effects.
***
### 1. boss-id
**Description:**\
Defines the unique ID of the boss that nwMVP should track and manage.
**Usage:**
* **MythicMobs** β Use the **MythicMob ID**
* **EliteMobs** β Use the **file name** of the boss **without `.yml`**
**Example:**
```yaml
boss-id: SkeletalMinion
```
***
### 2. spawner-id
**Description:**\
Defines the spawner that controls how and where the boss respawns.
This setting is **only required** when you are using **native spawners** from:
* MythicMobs
* EliteMobs
**Spawner ID format depends on the boss plugin:**
#### MythicMobs
Use the **Spawner ID** defined in MythicMobs:
```yaml
spawner-id: "SkeletalMinion_Spawner"
```
#### EliteMobs
Use the **location string** generated by EliteMobs:
```yaml
spawner-id: "devworld,9.5,-61.5,-14.5,0.0,0.0:1764952356947"
```
> β οΈ This location format must match exactly as defined by EliteMobs.
***
### 3. hologram
**Description:**\
Displays a hologram above the boss spawn location.
> **Important:**\
> Holograms only work **when `spawner-id` is defined**.
**Configuration:**
```yaml
hologram:
lines:
- "&6&l{bosses_display_name}"
- "&7Boss: &f{boss_name}"
- "&7Cooldown: &e{cooldown}"
- "&7Status: &bAlive or Dead"
```
#### Supported Placeholders
| Placeholder | Description |
| ----------------------- | -------------------------- |
| `{bosses_display_name}` | Display name of the boss |
| `{boss_name}` | Internal boss name |
| `{cooldown}` | Remaining respawn cooldown |
**Note:**\
Boss cooldown timing is **fully based on the spawner configuration**, not nwMVP.
***
### 4. worldguard
**Description:**\
Restricts boss combat to specific **WorldGuard regions**.
Only players inside the defined regions can attack the boss.
**Configuration:**
```yaml
worldguard:
enabled: true
world:
- devworld
- bossmap
region:
- mapboss1
- mapskeletonking1
```
**How it works:**
* Boss damage is **only counted** if the player is inside the allowed region
* Players outside the region **cannot damage the boss**
* Supports multiple worlds and regions
***
### 5. particle
**Description:**\
Adds visual particle effects when the boss spawns, making the boss location more visible.
**Configuration:**
```yaml
particle:
enabled: false
type: DUST
color: "255,0,0"
offset: 0,0.5,0
count: 10
size: 1.0
visible-range: 30.0
duration: 30
```
#### Particle Settings Explained
| Option | Description |
| --------------- | ---------------------------------- |
| `enabled` | Enable or disable particle effects |
| `type` | Particle type (e.g. `DUST`) |
| `color` | RGB color format (`R,G,B`) |
| `offset` | Particle position offset |
| `count` | Number of particles per tick |
| `size` | Particle size |
| `visible-range` | Distance players can see particles |
| `duration` | Particle duration in seconds |
***
### Example Full Boss Configuration
## Rewards (Boss Rewards)
This `rewards:` section is used to **give rewards to players after the boss dies**.
* Rewards are given **only to players who participated** in the fight (e.g., dealt damage / contributed to the boss encounter).
* If a player **did not attack the boss or had zero participation**, they **will not receive any rewards**.
* The plugin will run the **commands** you define in each reward category.
> For the full reward logic (advanced rules, random rewards, drop table behavior, chances, etc.), please refer to the **`droptables`** system documentation.
* **top1 β top5**\
Rewards for the **Top Damage Ranking** positions (Top 1 to Top 5).\
These are typically based on **damage ranking** after the boss dies.
* **guild**\
Reward for **GUILD mode** results (when the boss is configured to track guild scores).\
Given to eligible players in the winning / ranked guild context (depending on your boss mode & scoring).
* **party**\
Reward for **PARTY mode** results (party-based score tracking).
* **individual**\
Reward for **INDIVIDUAL mode** results (player-only score tracking).
* **firststrike**\
Reward for the player who landed the **first hit** on the boss.
* **finalblow**\
Reward for the player who landed the **killing hit** on the boss.
* **top\_damage\_dealer**\
Reward for the player who dealt the **highest damage**.
* **top\_damage\_taken**\
Reward for the player who took the **most damage** during the fight.
* **top\_support\_healer**\
Reward for the player who provided the **most healing/support** during the fight.
* **personal\_reward**\
Reward for **all participants** (every player who contributed and is eligible), even if they are not top-ranked.
```yaml
rewards:
top1:
- money give {_player} 500
top2:
- money give {_player} 888
top3:
- money give {_player} 300
top4:
- money give {_player} 200
top5:
- money give {_player} 100
guild:
- money give {_player} 1000
party:
- money give {_player} 1000
individual:
- money give {_player} 1000
firststrike:
- money give {_player} 1000
finalblow:
- money give {_player} 1000
top_damage_dealer:
- money give {_player} 1000
top_damage_taken:
- money give {_player} 1000
top_support_healer:
- money give {_player} 1000
personal_reward:
- money give {_player} 1000
```
**Note:** `{_player}` is replaced with the target player name when the command is executed
## Boss Announcement Messages
The `messages` section controls **global announcements** related to boss events in **nwMVP**.\
These messages are broadcast to players when a boss **spawns** and when a boss is **defeated**.
All messages support:
* **MiniMessage formatting**
* **RGB gradients**
* **Placeholders**
* **Bold, color, and icon styling**
***
### 1. Announcement: Boss Spawn
#### Configuration
```yaml
messages:
announcement-boss-spawn:
enabled: true
msg:
- ""
- "ββ A BOSS HAS SPAWNED ββ"
- "The mighty{boss}has emerged into the world!"
- "β’ Position: X:{x} Y:{y} Z:{z}"
- "β’ World:{world}"
- ""
```
#### How it Works
* Triggered **when a boss spawns**
* Broadcasts a global message to all players
* Displays:
* Boss name
* Spawn coordinates
* World name
* Used to **alert players** and encourage participation
#### Key Options
* **enabled**
* `true` β Boss spawn announcement is enabled
* `false` β No announcement is sent
* **msg**
* List of message lines
* Empty lines (`""`) create spacing
* Fully customizable using MiniMessage
#### Available Placeholders
| Placeholder | Description |
| ----------- | ----------------- |
| `{boss}` | Boss display name |
| `{x}` | X coordinate |
| `{y}` | Y coordinate |
| `{z}` | Z coordinate |
| `{world}` | World name |
***
### 2. Announcement: Boss Defeated
#### Configuration
```yaml
messages:
announcement-boss-dead:
enabled: true
guild-prefix: "Guild "
party-prefix: "Party "
individual-prefix: "Player "
msg:
- ""
- "ββ BOSS DEFEATED! ββ"
- "The boss {boss} has been slain!"
- ""
- "π Top Damage Dealers:"
- "1.{top1_name} - {top1_score}({top1_percentage})"
- "2.{top2_name} - {top2_score}({top2_percentage})"
- "3.{top3_name} - {top3_score}({top3_percentage})"
- "4.{top4_name} - {top4_score}({top4_percentage})"
- "5.{top5_name} - {top5_score}({top5_percentage})"
- ""
- "β‘ First Strike:{firststrike}"
- "β Final Blow:{finalblow}"
- ""
- "π‘ Top Damage Taken:{top_damage_taken_name} - {top_damage_taken_score}"
- "π Top Support Healer:{top_support_healer_name} - {top_support_healer_score}"
- ""
- "β Total Damage:{total_damage}"
- ""
```
#### How it Works
* Triggered **when the boss is killed**
* Broadcasts a detailed **battle summary**
* Shows:
* Top damage rankings
* First Strike & Final Blow
* Top damage taken
* Top support healer
* Total damage dealt
#### Prefix Settings
Used to visually identify the score type when displaying names:
* **guild-prefix** β Used for GUILD mode
* **party-prefix** β Used for PARTY mode
* **individual-prefix** β Used for INDIVIDUAL mode
Example:
```
Guild Knights
Party Alpha
Player Steve
```
***
### Ranking & Statistic Placeholders
#### Top Damage Rankings
| Placeholder | Description |
| ----------------------------------------- | --------------------------- |
| `{top1_name}` β `{top5_name}` | Player / Party / Guild name |
| `{top1_score}` β `{top5_score}` | Damage value |
| `{top1_percentage}` β `{top5_percentage}` | Damage percentage |
#### Special Roles
| Placeholder | Description |
| --------------- | ----------------------------- |
| `{firststrike}` | Player who hit the boss first |
| `{finalblow}` | Player who killed the boss |
#### Additional Stats
| Placeholder | Description |
| ---------------------------- | -------------------------------- |
| `{top_damage_taken_name}` | Player with highest damage taken |
| `{top_damage_taken_score}` | Damage taken value |
| `{top_support_healer_name}` | Best healer |
| `{top_support_healer_score}` | Healing amount |
| `{total_damage}` | Total damage dealt to the boss |
