# Tycoon Boost Armors

\
Each armor is fully configurable, supports custom visuals (including Nexo items), persistent levels, unlock requirements and dynamic boosters that scale per level.

This system is not cosmetic-only. It is a structured progression layer designed to integrate directly into farming, mining and economy mechanics.

***

### Core Concept

Every armor consists of:

* A **selector item** (used in GUI)
* Four **equipment pieces** (helmet, chestplate, leggings, boots)
* An **unlock condition**
* A **max level**
* A **level scaling system**
* One or multiple **boosters**
* A **display order**
* Persistent player state (unlocked, level, active armor)

Only one armor can be active at a time.

***

## Armor Configuration Structure

```
armors:
  <armor-id>:
```

Each armor ID is unique and used internally for storage and activation.

***

### 1. Display (Selector Item)

```yaml
display:
  selector:
    material: LEATHER_CHESTPLATE
    name: '&aFarmer Armor'
    custom-model-data: 101
    lore:
      - '&7Boosts farming efficiency'
```

#### Supported Options

| Field               | Required | Description                    |
| ------------------- | -------- | ------------------------------ |
| `material`          | Yes      | Bukkit material OR `nexo:<id>` |
| `name`              | No       | Display name                   |
| `lore`              | No       | List of lore lines             |
| `custom-model-data` | No       | Integer                        |
| `color`             | No       | HEX color (leather only)       |

#### Nexo Support

You can use:

```yaml
material: "nexo:my_custom_item"
```

If the value starts with `nexo:` it will be treated as a Nexo item instead of Bukkit material.

***

### 2. Pieces

```yaml
pieces:
  helmet:
    material: LEATHER_HELMET
    color: '#7FBF6A'
    name: '&aFarmer Helmet'
```

Supported piece keys:

* `helmet`
* `chestplate`
* `leggings`
* `boots`

All fields supported by selector are also supported here:

* material / nexo
* name
* lore
* custom-model-data
* color

If a piece is missing, it simply won’t be equipped.

***

### 3. Unlock System

```yaml
unlock:
  cost:
    essence: 25000
  require-prestige: 2
```

#### Options

| Field              | Description                |
| ------------------ | -------------------------- |
| `cost.essence`     | Essence required to unlock |
| `require-prestige` | Minimum prestige required  |

Unlocking:

* Marks armor as unlocked
* Initializes its level at 0
* Persists in database

***

### 4. Level System

```yaml
max-level: 20
```

Defines the maximum level for that armor.

Level progression is stored per player per armor.

***

### 5. Upgrade Cost Scaling

```yaml
levels:
  upgrade-cost:
    base: 500
    per-level: 150
```

Upgrade formula:

```java
cost = base + (current_level * per-level)
```

This allows fully linear scaling.

You can design:

* Cheap early scaling
* Exponential feeling via large per-level values
* High-end progression caps

***

### 6. Boosters

```yaml
levels:
  boosters:
    essence:
      base: 0.5
      per-level: 1
      max: 5.0
```

Each booster has:

| Field       | Description               |
| ----------- | ------------------------- |
| `base`      | Starting value at level 1 |
| `per-level` | Increase per level        |
| `max`       | Hard cap                  |

#### Available Booster Keys (Standard Usage)

The following booster keys are commonly used across Tycoon systems:

* **essence** → Increases essence gain
* **crops** → Increases crop rewards / yield
* **hoe-xp** → Increases Tycoon Hoe XP gain
* **activation** → Increases activation chance / proc-based effects

Calculation:

```yaml
value = base + ((level - 1) * per-level)
value = min(value, max)
```

Boosters are referenced by string key:

```java
ArmorBoosterService.getBooster(playerUUID, "essence")
```

Keys are lowercase internally.

You can define multiple boosters:

```yaml
boosters:
  essence:
    base: 0.5
    per-level: 1
    max: 5
  crops:
    base: 1
    per-level: 0.5
    max: 10
```

There is no hard limit on booster count.

***

### 7. Order

```yaml
order: 1
```

Used for GUI sorting. Lower number appears first.

***

## GUI Configuration

```yaml
armor:
```

Fully configurable inventory.

***

### Inventory Settings

```yaml
title: "&8        ᴛʏᴄᴏᴏɴ ᴀʀᴍᴏʀ ꜱᴇᴛꜱ"
size: 54
```

***

### Selector Slots

```yaml
selector-slots: [10,11,12,13,14,15,16]
```

Armor selector icons are placed here in order.

***

### Piece Slots

```yaml
piece-slots:
  helmet: 20
  chestplate: 21
  leggings: 22
  boots: 23
```

***

### Piece Template

This controls how upgrade items look dynamically.

```yaml
piece-template:
  name: "{display_name} Lv. {level}"
  lore:
    - "{description}"
    - "Max Level: {max_level}"
    - "Booster: {booster}"
```

#### Supported Placeholders

| Placeholder          | Meaning                  |
| -------------------- | ------------------------ |
| `{display_name}`     | Armor display name       |
| `{level}`            | Current level            |
| `{max_level}`        | Maximum level            |
| `{description}`      | Booster description      |
| `{upgrade_1_cost}`   | Cost for +1              |
| `{upgrade_50_cost}`  | Cost for +50             |
| `{upgrade_max_cost}` | Cost for max             |
| `{boost-type}`       | Booster key              |
| `{booster}`          | Current calculated value |

Upgrade interaction types:

* Left Click → +1
* Right Click → +50
* Q → Max upgrade

***

### GUI Buttons

```yaml
items:
  unlock:
  activate:
  deactivate:
  back:
```

Each supports:

* slot list
* material
* name
* lore

You can fully redesign visual style.

***

## Player State Model

Each player stores:

* activeArmorId
* unlocked armors
* level per armor
* dirty flag (for database flush)

State is cached in memory and periodically flushed to database.

***

## Persistence & Performance

* Async loading
* Async saving
* Dirty-check flush task
* No sync database operations
* Thread-safe cache (ConcurrentHashMap)

Armor activation:

* Instantly equips pieces
* Updates inventory
* Marks state dirty

***

## Creating a New Armor (Template)

Copy and modify:

```yaml
armors:
  harvester:
    display:
      selector:
        material: LEATHER_CHESTPLATE
        name: '&2Harvester Armor'
        custom-model-data: 110

    pieces:
      helmet:
        material: LEATHER_HELMET
        color: '#4CAF50'
        name: '&2Harvester Helmet'

      chestplate:
        material: LEATHER_CHESTPLATE
        color: '#4CAF50'

      leggings:
        material: LEATHER_LEGGINGS
        color: '#4CAF50'

      boots:
        material: LEATHER_BOOTS
        color: '#4CAF50'

    unlock:
      cost:
        essence: 75000
      require-prestige: 6

    max-level: 35

    levels:
      upgrade-cost:
        base: 800
        per-level: 200
      boosters:
        crops:
          base: 1.0
          per-level: 0.8
          max: 12

    order: 6
```

***

## Design Recommendations

• Early game: low max-level, low base, soft scaling\
• Mid game: moderate scaling, dual boosters\
• Late game: high cap, prestige gated\
• End game: multi-booster stacking

You can:

* Create specialization armors
* Create hybrid armors
* Create prestige-exclusive sets
* Design armor tiers aligned with server economy