# 🎁 Drop Table

The **Drop Table System** in **nwMVP** is a **core reward engine** designed to handle **all reward distributions** in a flexible, reusable, and highly configurable way.

This system allows server owners to design **complex reward logic** using:

* Conditions
* Chances
* Nested tables
* Multiple reward sources
* Player performance data

Drop tables are used across:

* Boss rewards
* Territory rewards
* Season rewards
* Participation rewards
* Achievement-based rewards

***

### 📌 Core Concept

A **Drop Table** is a **reusable reward definition** that can be executed when a player qualifies for a reward.

Instead of defining rewards directly inside bosses or territories, nwMVP uses **drop tables** as a centralized reward system.

#### Why Drop Tables?

✅ Reusable\
✅ Easy to balance\
✅ Supports complex logic\
✅ Works with all major plugins\
✅ Clean configuration structure

***

### 🧠 High-Level Execution Flow

When a drop table is executed:

1. **Table Lookup**
   * System checks whether the drop table exists
2. **Condition Validation**
   * All defined conditions are evaluated
   * Uses **AND logic**
   * If **any condition fails**, the table stops immediately
3. **Entry Processing**
   * Each entry inside `lists` is processed sequentially
4. **Chance Roll**
   * Each entry rolls its own chance independently
5. **Reward Execution**
   * If chance succeeds, reward is given
   * Items are added to inventory or dropped if full

***

### 📁 File Structure

#### Location

```
/plugins/nwMVP/droptables/
```

#### Example Structure

```
droptables/
 ├── basic.yml
 ├── epic.yml
 ├── legendary.yml
 ├── vip.yml
 └── territory.yml
```

#### Why Multiple Files?

* Easier organization
* Better maintainability
* Clear reward tiers

***

### 🧩 Basic YAML Structure

```yaml
tables:
  table_name:
    conditions:
      # optional
    lists:
      - "<entry> | <chance>"
```

#### Root Elements

| Key          | Description                          |
| ------------ | ------------------------------------ |
| `tables`     | Root container for all drop tables   |
| `table_name` | Unique identifier (case-insensitive) |
| `conditions` | Optional execution conditions        |
| `lists`      | Reward entries                       |

***

### ⚙️ Conditions System

Conditions define **who is allowed** to receive rewards from a drop table.

> ⚠️ **All conditions use AND logic**\
> Every condition must pass.

***

#### 🔐 Permission Condition

```yaml
conditions:
  permission: "mvp.drop.basic"
```

✔ Player must have the permission\
❌ Otherwise, table does not execute

***

#### 🌍 World Condition

```yaml
conditions:
  worlds:
    - world
    - world_nether
```

✔ Player must be inside one of the listed worlds

***

#### 📏 Radius Condition

```yaml
conditions:
  radius: 30
```

✔ Player must be within **X blocks** of the boss death location\
✔ Only works when location context exists (boss rewards)

***

#### ⚔ Damage Conditions

**Minimum Damage**

```yaml
conditions:
  min_damage: 100
```

**Maximum Damage**

```yaml
conditions:
  max_damage: 5000
```

✔ Filters players based on contribution\
✔ Used for tiered reward logic

***

#### 🔎 Placeholder Conditions (Advanced)

```yaml
conditions:
  placeholders:
    level_check: "%player_level% >= 30"
    class_check: "%player_class% == 'Warrior'"
```

**Supported Operators**

```
>=  <=  >  <  ==  !=
```

✔ Uses PlaceholderAPI\
✔ Supports numeric & string comparisons\
✔ Case-insensitive string matching

***

#### 🏆 Reward-Type Conditions

```yaml
conditions:
  top: true
  firststrike: true
  finalblow: true
```

Available Flags:

* `top`
* `firststrike`
* `finalblow`
* `top_damage_dealer`
* `top_support_healer`
* `top_damage_taken`

✔ Only executes if player **received that reward type**

***

### 📜 Drop Entries (lists)

Each entry defines **what is given** and **how often**.

#### Entry Syntax

```
<value> | <chance>
```

| Part     | Description       |
| -------- | ----------------- |
| `value`  | Reward definition |
| `chance` | 0.0 → 1.0         |
| \`       | \`                |

If `chance` is omitted → defaults to `1.0`

***

### 🎲 Chance System

Each entry rolls independently:

| Chance | Meaning |
| ------ | ------- |
| `1.0`  | Always  |
| `0.5`  | 50%     |
| `0.1`  | 10%     |
| `0.0`  | Never   |

✔ Multiple rewards can succeed\
✔ Order does not affect probability

***

### 🎁 Supported Entry Types

***

#### 1️⃣ Vanilla Items

```yaml
- "diamond"
- "diamond 5"
- "diamond 10-20"
```

✔ Supports random ranges\
✔ Drops on ground if inventory full

***

#### 2️⃣ MMOItems

```yaml
- "SWORD;LEGENDARY_SWORD;1"
```

✔ TYPE;ID;AMOUNT\
✔ Requires MMOItems

***

#### 3️⃣ MythicMobs Drop Tables

```yaml
- "SkeletonKingDrops"
```

✔ Executes MythicMobs drop tables\
✔ Requires MythicMobs

***

#### 4️⃣ EliteMobs Items

```yaml
- "zombie_king_sword"
```

✔ Matches EliteMobs item ID

***

#### 5️⃣ Custom Items

(Supported plugins)

* ItemsAdder
* Nexo
* CraftEngine

```yaml
- "itemsadder:ruby_sword"
- "nexo:legendary_axe;2"
```

✔ Auto-detection\
✔ Amount optional

***

#### 6️⃣ Economy / Currency

```yaml
- "vault;100"
- "vault;100-200"
- "pp;50"
- "bt;25"
- "ce;gold;100"
```

Supported:

* Vault
* PlayerPoints
* BeastTokens
* CoinsEngine

***

#### 7️⃣ Nested Drop Tables

```yaml
- "basic_reward"
```

✔ Executes another drop table\
✔ Conditions are checked recursively\
✔ Unlimited depth (avoid loops)

***

#### 8️⃣ Commands

```yaml
- "[console] give {player} diamond 64"
- "[player] spawn"
- "say Congratulations {player}!"
```

✔ Default execution: console\
✔ Placeholders auto-replaced

***

### 🔄 Nested Drop Table Example

```yaml
tables:
  basic_reward:
    lists:
      - "diamond 5 | 1"

  epic_reward:
    lists:
      - "basic_reward | 1"
      - "gold_ingot 20 | 1"

  legendary_reward:
    lists:
      - "epic_reward | 1"
      - "SWORD;LEGENDARY_SWORD;1 | 1"
```

✔ Builds reward tiers cleanly\
✔ Highly reusable

***

### 🧠 Execution Logic Summary

* Conditions → checked once
* Entries → processed sequentially
* Each entry → independent chance
* Rewards → stackable
* Inventory overflow → auto-drop

***

### 🧪 Best Practices

✅ Use multiple files\
✅ Name tables clearly\
✅ Use nested tables\
✅ Balance chances carefully\
✅ Comment complex logic

***

### 🔁 Reloading Drop Tables

```
/nwmvp admin reload
```

✔ Applies instantly\
✔ No server restart

***

### 🎯 Where Drop Tables Are Used

* Boss rewards
* Territory rewards
* Season rewards
* Participation rewards
* Achievement rewards

Anywhere a reward is needed → **Drop Table**