# 🏰 Territory

### **Wiki Documentation**

***

### Introduction

The **Territory System** in **nwMVP** is a full-scale **guild-based territory conquest and ownership system** designed to create long-term competitive PvE content.

Territories are controlled through **scheduled boss events**, where guilds compete by dealing damage to a boss within a defined WorldGuard region.\
The system does **not rely on PvP dominance**, but instead focuses on **coordination, damage contribution, and sustained guild progression**.

This system is deeply integrated with:

* Boss systems (MythicMobs / EliteMobs)
* Guild systems
* Economy systems
* WorldGuard
* Regen Zones
* Buffs, EXP, and reward pipelines

***

### 🔑 Key Features

* Scheduled territory conquest events
* Boss-based territory capture mechanics
* Guild damage tracking and ranking
* Territory maintenance system
* Buffs, bonuses, and EXP multipliers
* Region-based utilities and restrictions
* Deep integration with WorldGuard, guild plugins, and boss plugins

***

### 📋 How the Territory System Works

The Territory System revolves around **scheduled boss events** inside WorldGuard regions.

#### Territory Lifecycle

1. Territory event becomes active (scheduled time)
2. Boss spawns inside the territory region
3. Guilds enter and fight the boss
4. Damage is tracked by guild
5. Boss is defeated
6. Guild with the highest damage wins
7. Territory is captured
8. Maintenance cost is paid (if enabled)
9. Territory benefits activate
10. Guild controls the territory until the next event

***

### 🗺 Territory Configuration

**File Location:**

```
/plugins/nwMVP/territory/<territory_name>.yml
```

#### Basic Territory Settings

```yaml
territory:
  enabled: true
  display-name: "Forest Temple"
  mode: "DAMAGE"
  world: "devworld"
  region: "mapboss1"
```

**Explanation**

| Option         | Description                                             |
| -------------- | ------------------------------------------------------- |
| `enabled`      | Enable or disable this territory                        |
| `display-name` | Display name shown in messages, holograms, and GUIs     |
| `mode`         | Territory capture mode (`DAMAGE`, `CAPTURE`, `DEFENSE`) |
| `world`        | World name where the territory exists                   |
| `region`       | WorldGuard region name                                  |

***

### 🆔 Territory ID

Each territory has a **unique UUID** generated automatically.

```yaml
territory:
  territory_id: "550e8400-e29b-41d4-a716-446655440000"
```

* Automatically generated on first load
* Used internally for database tracking
* Should not be edited manually

***

### ⏰ Territory Schedule

Defines when the territory event becomes active.

```yaml
territory:
  start-territory:
    day: "Saturday"
    time: "18:00-21:00"
    timezone: "Asia/Bangkok"
```

#### Supported Formats

* `EVERYDAY`
* `Monday`
* `Monday,Friday,Sunday`
* Time format: `HH:mm-HH:mm`

The territory is **only active during the scheduled time**.

***

### 👹Boss Configuration

#### boss-id

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
```

***

#### 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.

***

### 📊 Hologram Display

**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"
```

Requires:

* **CMI** or **DecentHolograms**

#### 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.

***

### 🎁 Rewards System

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.<br>

```yaml
rewards:
  top1:
    - money give {_player} 500
  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
  participation:
    - money give {_player} 400
```

#### Supported Reward Types

* Vault money
* PlayerPoints
* CoinsEngine
* BeastTokens
* MMOItems
* Drop Tables
* Any console command

***

## ⚙ Region Settings

`region-settings` defines **how players behave inside a Territory region**, both **before capture (AVAILABLE)** and **after capture**.

> 🔹 Some settings apply at all times\
> 🔹 Some apply **only during Contest (Boss Alive)**\
> 🔹 After capture, many behaviors are handed over to **WorldGuard**

```yaml
region-settings:
    allow-player-no-guild: true
    titles:
      enabled: true
      title: Welcome {territory_display_name}
      sub-title: Guild {territory_guild_name} Zone
    max-guilds-per-zone:
      enabled: false
      per-guilds: 10
    player-respawn-in-region:
      enabled: true
      locations:
      - devworld,140,70,-40
      - devworld,140,70,-40
    sound-theme-in-region:
      enabled: true
      region-sound: MUSIC_DISC_PIGSTEP
      when-boss-dead-sound: MUSIC_DISC_PIGSTEP
    blocked-commands:
      enabled: false
      commands:
      - spawn
      - home
    utilities:
      allow-pvp: true # กำหนดภายใน region เท่านั้น ตอนที่กำลังชิงพื้นที่เท่านั้น ถ้ายึดพื้นที่เสร็จจะกลับไปอ้างอิงตาม worldguard ที่กำหนด flag ไว้
      allow-fly: false # กำหนดภายใน region เท่านั้น ตอนที่กำลังชิงพื้นที่เท่านั้น ถ้ายึดพื้นที่เสร็จจะกลับไปอ้างอิงตาม worldguard ที่กำหนด flag ไว้
      allow-enderpearl: false # กำหนดภายใน region เท่านั้น ตอนที่กำลังชิงพื้นที่เท่านั้น ถ้ายึดพื้นที่เสร็จจะกลับไปอ้างอิงตาม worldguard ที่กำหนด flag ไว้
      allow-elytra: false # กำหนดภายใน region เท่านั้น ตอนที่กำลังชิงพื้นที่เท่านั้น ถ้ายึดพื้นที่เสร็จจะกลับไปอ้างอิงตาม worldguard ที่กำหนด flag ไว้
      force-gamemode: SURVIVAL # เมื่อออก region จะถูกตั้งเป็น SURVIVAL
      disable-items-and-equipment: # กำหนดภายใน region เท่านั้น ตอนที่กำลังชิงพื้นที่เท่านั้น ถ้ายึดพื้นที่เสร็จ จะต้องไม่เป็นผล
        enabled: true
        # check equipment in inventory and mainhand offhand only
        items:
        - ELYTRA
        - DIAMOND_SWORD
        - DIAMOND_AXE
        - DIAMOND_HOE
        - DIAMOND_SHOVEL
        - DIAMOND_BOOTS
        - DIAMOND_LEGGINGS
        - mi;sword;katana
```

### 1️. allow-player-no-guild

Controls whether players **without a guild** can enter the Territory.

```yaml
allow-player-no-guild: true
```

* `true` → Non-guild players may enter (but cannot capture)
* `false` → Only guild members can enter

***

### 2️. titles

Displays a title/subtitle when entering the Territory.

```yaml
titles:
  enabled: true
  title: Welcome {territory_display_name}
  sub-title: Guild {territory_guild_name} Zone
```

* Triggered when entering the region
* Typically shown **after successful capture**
* Supports placeholders

***

### 3️. max-guilds-per-zone

Limits how many territories a single guild may own.

```yaml
max-guilds-per-zone:
  enabled: false
  per-guilds: 10
```

Prevents guild monopolization.

***

### 4️. player-respawn-in-region

Custom respawn points for deaths inside Territory.

```yaml
player-respawn-in-region:
  enabled: true
  locations:
    - devworld,140,70,-40
```

* Random respawn from list
* Improves flow of Territory fights

***

### 5️. sound-theme-in-region

Plays sounds when entering Territory or when boss dies.

```yaml
sound-theme-in-region:
  enabled: true
  region-sound: MUSIC_DISC_PIGSTEP
  when-boss-dead-sound: MUSIC_DISC_PIGSTEP
```

***

### 6️. blocked-commands

Blocks specific commands inside Territory.

```yaml
blocked-commands:
  enabled: false
  commands:
    - spawn
    - home
```

Prevents escaping during fights.

### 7. allow-pvp

* `false` → **Disables player-vs-player damage** during the contest\
  Ideal if you want a pure PvE boss competition without guilds griefing each other.
* `true` → **Enables PvP** during the contest for PvPvE-style territory wars.

```yaml
allow-pvp: true
```

> After contest: PvP behavior follows **WorldGuard PVP flags**.

***

### 8. allow-fly

* `false` → **Blocks flying** during the contest (including flight from permissions/plugins)\
  Prevents players from hovering, safe-spotting, or escaping the fight.
* `true` → Allows flight during the contest.

```yaml
allow-fly: true
```

> After contest: flight behavior is handled by **WorldGuard** and other server systems normally.

***

### 9. allow-enderpeal

* `false` → **Blocks Ender Pearl usage** during the contest\
  Prevents teleport escapes, wall-skipping, and unfair positioning.
* `true` → Allows Ender Pearls during the contest.

```yaml
allow-enderpearl: true
```

> After contest: usage follows **WorldGuard** rules and your server setup.

***

#### 10. force-gamemode

* Forces players to a specific **GameMode** (e.g., `"SURVIVAL"`) during the contest.\
  Common reasons:
  * Prevent Creative/Adventure abuse
  * Ensure everyone fights under the same ruleset

Common values:

* `"SURVIVAL"`
* `"ADVENTURE"`
* `"CREATIVE"` (not recommended for contests)

```yaml
force-gamemode: SURVIVAL
```

> Typical behavior: if a player is in the contest region with a different mode, nwMVP switches them to the configured mode to enforce fairness.

### 11. disable-items-and-equipment

Contest-only item and equipment restrictions

```yaml
disable-items-and-equipment:
  enabled: true
  items:
    - ELYTRA
    - DIAMOND_SWORD
    - mi;sword;katana
```

***

## 🏰 Guild Territory Benefits

### 1. Maintenance System

```yaml
maintenance:
  enabled: true
  cost: 2000
```

#### How It Works

* After a guild wins the Territory
* Status becomes `WAITING_PAID_MAINTENANCE`
* The Territory is **not active yet**
* The **guild leader only** must pay maintenance

#### Command

```
/nwmvp territory maintenance
```

#### Supported Economies

* Vault
* PlayerPoints (`pp`)
* CoinsEngine (`ce;<currency>`)
* BeastTokens (`bt`)

***

### 2. Buffs & Effects

```yaml
stats-and-effect:
  enabled: true
  apply-to-new-members: true
  buffs:
    - "Vanilla;Haste;1;"
    - "MythicLib;ATTACK_DAMAGE;2"
```

#### Behavior

* Applies only after capture success
* Removed immediately if territory is lost
* Optional auto-apply to new guild members

#### Supported Buff Types

* MythicLib stats
* Vanilla potion effects

***

### 3️. Cost Bonus (Mob Kill Rewards)

```yaml
cost-bonus:
  enabled: true
  mobs:
    - mythicmobs;WITHER_SKELETON;100-120
```

* Rewards guild members for killing mobs in the territory
* Supports MythicMobs, EliteMobs, and Vanilla mobs
* Bosses are excluded

***

### 4️. EXP Bonus (Vanilla)

```yaml
exp-bonus:
  enabled: true
  multiplier: 1.2
```

* Multiplies vanilla EXP gain
* Applies only to territory owner guild

***

### 5️. MMOCore EXP Bonus

```yaml
mmocore-exp-bonus:
  enabled: true
  profession-multiplier: 1.2
  class-multiplier: 1.1
```

* Requires MMOCore
* Applies separate multipliers to profession and class EXP

## **Owner Territory Cost System**

`owner-territory-settings.cost` defines **usage fees for territories owned by a guild**.

This system charges **only players who are NOT members of the owning guild** and allows territory owners to control how their land is used.

***

### 1️. Allow Other Guild Players to Enter

```yaml
allow-player-other-guild-enter-region:
  enabled: true
  cost: 100
```

#### Behavior

* If enabled, non-guild players must **pay to enter** the territory
* If disabled, non-guild players are **completely blocked**
* Cost is charged **per entry**

***

### 2️. Player Events Cost System

This section charges non-guild players for specific actions inside the territory.

#### Allow Regen Regions

```yaml
allow-regen-regions:
  - "nwmvptest"
```

`allow-regen-regions` defines **which territory regions are allowed to use the Regen Zone system** for **block breaking** and **crop harvesting**.

This setting is **only applicable to**:

* `block-break`
* `crop-harvest`

and **only works when** `regen-block-plugin: "nwmvp"` is enabled.

***

#### How It Works

* This configuration tells the system **which territory regions are permitted to regenerate blocks and crops**.
* The regions listed here must **match the region names defined in `regenzone.yml`**.
* When a player interacts with blocks or crops:
  1. The system checks whether the action occurs inside a territory.
  2. It then checks whether the territory’s region name exists in `allow-regen-regions`.
  3. If the region is allowed, the action follows the Regen Zone rules.
  4. If not, the action is **blocked or charged (depending on configuration)**.

***

#### Important Requirements

* `allow-regen-regions` **only works with the built-in nwMVP regen system**
* You **must** set:

  ```yaml
  regen-block-plugin: "nwmvp"
  ```
* If you use **any other regen plugin** (such as UltimateBlockRegeneration, MineXFarmRegen, BlockRegen, etc.):
  * `regenzone.yml` will **NOT work**
  * `allow-regen-regions` will have **no effect**

***

#### Region Matching Logic

To enable Regen Zones successfully:

* The region name in **Territory config**\
  **must match exactly**
* The region name in **regenzone.yml**
* The region name in **allow-regen-regions**

Example:

```yaml
# territory.yml
allow-regen-regions:
  - "nwmvptest"
```

```yaml
# regenzone.yml
allow-regen-regions:
  - "nwmvptest"
```

✅ Result: Regen Zone works correctly

***

#### Behavior Summary

| Location                      | Result                                                        |
| ----------------------------- | ------------------------------------------------------------- |
| Inside `allow-regen-regions`  | ✅ Block break & crop harvest allowed (Regen Zone rules apply) |
| Outside `allow-regen-regions` | ❌ Block break & crop harvest NOT allowed                      |
| Using non-nwMVP regen plugin  | ❌ Regen Zone (nwMVP) system disabled                          |

***

#### Block Break Cost

* Charges per block destroyed
* Supports:
  * Vanilla blocks
  * Nexo
  * CraftEngine
  * ItemsAdder
* If player cannot afford → block break is cancelled

```yaml
block-break:
    enabled: true
    blocks:
    DIAMOND_ORE:
        cost: 500
    COAL_ORE:
        cost: 10
    LOG:
        cost: 5
    nexo_crop:
        type: "nexo"
        id: "ruby_ore"
        cost: 5
    craftengine_topaz:
        type: "craftengine"
        id: "default:topaz_ore"
        cost: 1000
    ia_block:
        type: "itemsadder"
        id: "orespackvol1:galenite_ore"
        cost: 1000
    ia_block1:
        type: "itemsadder"
        id: "orespackvol1:bloodstone_ore"
        cost: 1000
```

***

#### Mob Kill Cost

* Charges per mob killed
* Supports:
  * Vanilla mobs
  * MythicMobs
  * EliteMobs
* Prevents free farming in enemy territories

```yaml
mob-kill:
    enabled: true
    mobs:
    ZOMBIE:
        cost: 5
    SKELETON:
        cost: 8
    SkeletalMinion:
        type: mythicmobs
        id: SkeletalMinion
        cost: 50
    zombie_king:
        type: elitemob
        id: zombie_king
        cost: 100
```

***

#### Fishing Cost

```yaml
fishing:
    enabled: true
    cost-per-catch: 10
```

* Charged every time a fish is caught

***

#### Crop Harvest Cost

* Charges when harvesting crops
* Supports all vanilla crops
* Works with regen crop system
* Supports:
  * Vanilla blocks
  * Nexo
  * CraftEngine
  * ItemsAdder

```yaml
crop-harvest:
    enabled: true
    crops:
    WHEAT:
        cost: 2
    CARROTS:
        cost: 2
```

***

## 🎯 Territory Capture Modes

#### DAMAGE

Highest total guild damage wins.

#### CAPTURE (Coming Soon)

First guild to reach a damage threshold wins.

#### DEFENSE (Coming Soon)

Defending guild must hold territory against attackers.