# Tycoon Boss System

Damage is tracked per player, ranked, rewarded and broadcasted in real time.

This is not a mob-based combat boss.\
It is a server-wide competitive farming event tied directly to crop activity.

***

## Core Concept

Each boss consists of:

* A unique ID
* A display name
* A maximum HP
* A timeout duration
* Crop damage rules
* Optional visual representation
* Optional BossBar
* Start & end broadcasts
* Ranked reward distribution
* Participant rewards
* Scheduler triggers
* Personal statistics messaging

Only one boss can be active at a time.

***

## Boss Configuration Structure

```yaml
bosses:
  <BOSS_ID>:
```

Boss IDs are stored uppercase internally.

***

## Basic Configuration

```yaml
CARROT_KING:
  name: Carrot King
  max-hp: 2500
  timeout: "1h"
```

#### Fields

| Field     | Description    |
| --------- | -------------- |
| `name`    | Display name   |
| `max-hp`  | Total HP       |
| `timeout` | Event duration |

***

## Timeout Format

Supported formats:

* `30s`
* `15m`
* `2h`
* `1d`
* `5000ms`
* raw milliseconds

If timeout is reached and boss is not killed → event ends without kill rewards.

***

## Damage System

Bosses take damage from crop breaking.

```yaml
damage:
  default: 2
  overrides:
    CARROTS: 3
    WHEAT: 1
```

#### How It Works

* `default` → applied to all crops
* `overrides` → material-specific damage
* Final damage is scaled by enchant bonuses
* Damage cannot be negative
* Custom `BossDamageEvent` is fired

***

## Boss Visual System

Global visual configuration:

```yaml
visual:
  spawn-location:
    world: "world"
    x: 0.5
    y: 100
    z: 0.5
  height-offset: 0
```

Per-boss visual:

```yaml
visual:
  type: HEAD
```

#### Supported Types

### HEAD

```yaml
visual:
  type: HEAD
  head:
    owner: "CarrotKing"
    # texture: "base64"
  display:
    scale: 2.5
    yaw: 0
    pitch: 0
```

Options:

* `owner` → Player skull owner
* `texture` → Base64 custom texture
* `scale` → Display scaling
* `yaw`, `pitch` → Rotation

***

### MODEL (ModelEngine)

```yaml
visual:
  type: MODEL
  model-id: "carrot_king"
```

Spawns invisible pig carrier entity and attaches ModelEngine model.

***

## BossBar

```yaml
bossbar:
  enabled: true
  title: "{boss_name} - {hp}/{max} ({percent}%)"
  color: RED
  style: SEGMENTED_20
  update-interval: 5
```

#### Supported Colors

* RED
* BLUE
* GREEN
* YELLOW
* PURPLE
* PINK
* WHITE

#### Supported Styles

* SOLID
* SEGMENTED\_6
* SEGMENTED\_10
* SEGMENTED\_12
* SEGMENTED\_20

***

## Start Broadcast

```yaml
start-broadcast:
  - "Boss started!"
```

Placeholders:

* `{boss_name}`
* `{hp}`
* `{max}`
* `{time}`

***

## End Broadcast

```yaml
end-broadcast:
  limit: 3
  header:
  ranks:
  footer:
  personal:
```

#### limit

Maximum ranks displayed publicly.

***

#### Rank Sections

Supports:

* Exact rank: `"1"`
* Range: `"3-5"`
* `default`

Placeholders:

* `{player}`
* `{rank}`
* `{damage}`
* `{dmg_ratio}`
* `{boss_name}`

***

#### Personal Section

Sent to each player individually.

Placeholders:

* `{damage}`
* `{dmg_ratio}`
* `{rank}`

***

## Rewards System

```yaml
rewards:
  top:
    limit: 5
    per-rank:
      "1":
        - "eco give {player} 10000"
      "2":
        - "eco give {player} 7500"
      "3-5":
        - "eco give {player} 5000"
      default:
        - "eco give {player} 2000"
  participants:
    min-damage: 100
    commands:
      - "eco give {player} 150"
```

#### Top Rewards

* `limit` → number of ranked rewards
* `per-rank` supports:
  * exact rank
  * rank ranges
  * default fallback

***

#### Participant Rewards

* `min-damage` → required to receive reward
* Commands executed from console
* `{player}`, `{damage}`, `{rank}`, `{dmg_ratio}` supported

***

## Scheduler System

Bosses can auto-start via triggers.

```yaml
triggers:
  - boss-id: CARROT_KING
    when: every:2h
    conditions:
      - "[player>=50]"
```

***

### Trigger Timing

#### Fixed Interval

```yaml
when: every:15m
```

#### Random Interval

```yaml
when: random:10m..30m
```

#### Direct Duration

```yaml
when: 1h
```

***

### Conditions

Currently supported:

```python
[player>=50]
[player<=30]
[player=100]
[player>10]
[player<200]
```

Checks online player count.

If conditions fail → trigger postponed.