> For the complete documentation index, see [llms.txt](https://plugins.elitefantasy.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plugins.elitefantasy.net/masky-plugins/maskycrops/soil-system.md).

# Soil System

## Introduction

MaskyCrops adds an optional soil health system on top of CustomCrops. Its goal is to reward crop rotation and land recovery without replacing the standard CustomCrops systems.

## Enable this on settings

The system is fully optional. With `soil-enabled: false`, all existing CustomCrops gameplay works exactly as before.

settings.yml

```yaml
settings:
  soil-enabled: true
```

### Water and Hydration

Water management remains the responsibility of CustomCrops.

* The pots retain their water capacity, water bar, watering can, rain, and nearby water absorption.
* MaskyCrops does not fill or consume water from the pot.
* A crop still requires a valid pot and the normal watering conditions configured in CustomCrops.

The soil system is an additional layer: water and nutrients are handled separately.

### Game Cycle

1. A player plants a CustomCrops crop in a pot.
2. If that ID is included in soils.\<id>.crops, MaskyCrops creates or restores the plot's state.
3. During growth, soil fertility and chemistry determine how many growth points the crop receives.
4. When a mature crop is harvested, the plot loses fertility and consumes/restores nutrients based on its profile.
5. An unused plot slowly regains fertility and soil chemistry.
6. The player can use configured fertilizers to restore the soil.

All state data is saved in H2, within plugins/MaskyCrops/database/soil.

### Fertility and Growth Curve

Fertility is the general value inherited from the initial system, typically between 0 and 100

```yaml
    growth:
      100: 1.00
      75: 0.85
      50: 0.65
      25: 0.40
      0: 0.00
```

The curve is interpolated between points. For example, with a fertility level of 50, the crop achieves 65% of the required growth points before applying soil chemicals.

### Soil Chemistry

Each plot stores the following values:

| Value          | Current function                                                               |
| -------------- | ------------------------------------------------------------------------------ |
| Nitrogen (N)   | It affects the rate of growth.                                                 |
| Phosphorus (P) | It limits the effective absorption of nutrients.                               |
| Potassium (K)  | It is saved and remains available for performance/quality analysis.            |
| Organic matter | It stabilizes the growth multiplier.                                           |
| pH             | It limits absorption; each crop has an ideal pH and a certain tolerance range. |
| Compaction     | It reduces growth efficiency.                                                  |

The N/P/K, organic matter, and compaction values use a scale of `0–100`. The pH uses a scale of `0–14`

Currently, the chemical growth multiplier combines nitrogen, phosphorus, pH, organic matter, and compaction. The system also provides a yield multiplier based on P/K, but it does not yet automatically modify MythicMobs drops; a specific harvest/drop hook is required for that.

### Crop rotation

```yaml
crop-profiles:
  pepper:
    family: "nightshades"
    root-depth: "SHALLOW"
    consumes: { nitrogen: 8.0, phosphorus: 5.0, potassium: 7.0 }
    ideal-ph: 6.3
    ph-tolerance: 1.5
    compaction-change: 1.5
```

The crop rotation bonus requires:

* a family different from the last crop harvested, and
* a different root depth.

For example, pepper → eggplant is not a good rotation: both are nightshades. Alternating a shallow-rooted Brassica with a deep-rooted crop from another family can earn the bonus.

Legumes can restore nitrogen:

```yaml
crop-profiles:
  soybean:
    family: "legumes"
    root-depth: "DEEP"
    consumes: { phosphorus: 2.0, potassium: 2.0 }
    restores: { nitrogen: 8.0 }
    organic-matter-change: 3.0
    compaction-change: -2.0
```

### Fertilizers

Soil fertilizers are configured in fertilizers

```yaml
fertilizers:
  bone_meal_compost:
    Material: "mc:bone_meal"
    Radius: 1
    Fertility: 10.0
    Cooldown: 30
    nitrogen: 3.0
    phosphorus: 6.0
    potassium: 2.0
    organic-matter: 2.0
    ph-change: 0.0
    compaction-change: -1.0
```

`Radius`: 1 covers an area of 3×3 pots. The fertilizer increases fertility and applies the configured chemical values.

CustomCrops’ native fertilizers—such as `quality_1`, `yield_increase_1`, or `speed_grow_1`—remain mechanics independent of the pot. It is not recommended to register them as soil fertilizers as well, unless a dual effect is deliberately desired.

{% hint style="info" %}
Technical note: Cooldown is loaded in seconds. It must be enforced by the fertilizer listener/manager to prevent repeated use; verify this before announcing it as an active limitation in production.
{% endhint %}

### Deterioration of the pot

When fertility reaches “depleted-at,” the original pot is saved and replaced with the configured block. When it recovers to “recovered-at,” MaskyCrops restores the original pot.

```yaml
    deterioration:
      enabled: true
      depleted-at: 0.0
      recovered-at: 25.0
      block: "mc:coarse_dirt"
```

If a player breaks or replaces that deteriorated block, MaskyCrops removes the status from the plot and never overwrites the player’s block.

### Agricultural Governance

It is designed to transform the land-use system into a territorial system using “Lands.” The idea is to separate agriculture into two layers: a broad strategic decision and a specific, active policy

“development-philosophies” defines the agricultural philosophy of the state or nation

firts example:

```yaml
  development-philosophies:
    sustainable:
      display-name: "Sustainable"
      description: "Lower volume, lower long-term risk, stronger recovery and upkeep stability."
      allowed-policies:
        - fallow_rest
        - autarky_isolationism
        - communal_shifts
        - boutique_agronomy
        - nomadic_foraging
      effects:
        upkeep-multiplier: 0.90
        production-multiplier: 0.95
        recovery-multiplier: 1.15
```

This represents the long-term direction. For example, sustainable farming yields less, but it restores the soil more effectively and requires less maintenance. Industrial farming yields more, but it takes a greater toll on the soil and is more expensive to maintain.

second example

```yaml
  policies:
    fallow_rest:
      display-name: "Fallow Rest"
      philosophy: "sustainable"
      category: "ecological"
      description: "Temporarily protects farmland so soil health and organic matter recover quickly."
      transition-days: 7
      requirements:
        resting-land-required: true
        prevents-planting: true
        prevents-harvesting: true
      maintenance:
        upkeep-multiplier: 0.00
      effects:
        soil-health-recovery-multiplier: 2.50
        organic-recovery-multiplier: 2.50
        production-multiplier: 0.00
      consequences:
        - "No production while resting."
        - "Encourages territorial crop rotation and recovery zones."
```

A policy has:

| type            | description                                                          |
| --------------- | -------------------------------------------------------------------- |
| philosophy      | the philosophy to which it belongs.                                  |
| category        | type of policy, such as ecological, economic, labor, or territorial. |
| transition-days | the time required to switch from one policy to another.              |
| requirements    | conditions for using it.                                             |
| maintenance     | costs or fees to maintain it.                                        |
| effects         | gameplay modifiers.                                                  |
| consequences    | descriptive text for documentation or future GUI.                    |

`agricultural-governance` isn't just a list of buffs. It's a framework that allows each territory to have its own agricultural identity: sustainable, industrial, specialized, communal, nomadic, etc. First, it defines the direction in which the agricultural civilization is heading, and then it defines how that strategy is being implemented on a day-to-day basis.

## Configurations

### Soils Configuration

```yaml
soils:
  default:
    crops:
      - apple
      - cabbage
      - chinese_cabbage
      - corn
      - default
      - eggplant
      - garlic
      - grape
      - hop
      - pepper
      - pineapple
      - pitaya
      - redpacket

    # Existing fertility layer. It remains useful for deterioration and the
    # legacy growth curve; chemistry adds the more detailed simulation below.
    initial-fertility: 100.0
    min-fertility: 0.0
    max-fertility: 100.0
    harvest-depletion: 8.0
    repeat-crop-penalty: 6.0
    rotation-bonus: 3.0
    recovery-per-minute: 0.25
    growth:
      100: 1.00
      75: 0.85
      50: 0.65
      25: 0.40
      0: 0.00

    # Values are 0..100 except pH, which uses 0..14.
    chemistry:
      initial-nitrogen: 70.0
      initial-phosphorus: 65.0
      initial-potassium: 65.0
      initial-organic-matter: 50.0
      initial-ph: 6.5
      initial-compaction: 0.0
      nitrogen-recovery-per-minute: 0.03
      phosphorus-recovery-per-minute: 0.02
      potassium-recovery-per-minute: 0.02
      organic-matter-recovery-per-minute: 0.01
      ph-recovery-per-minute: 0.01
      compaction-recovery-per-minute: 0.05
      max-compaction-growth-penalty: 0.50

    # Safe first-test setting: disable this until all crop IDs are confirmed.
    # When enabled, a fully depleted pot becomes coarse dirt and returns only
    # when its tracked fertility recovers and the dirt was not replaced.
    deterioration:
      enabled: false
      depleted-at: 0.0
      recovered-at: 25.0
      block: "mc:coarse_dirt"
```

### Crop Profiles Configuration

```yaml
# Crop profiles: family drives rotation, root-depth rewards alternating shallow
# and deep crops, and consumes/restores are applied per harvest.
crop-profiles:
  apple:
    family: "orchard"
    root-depth: "DEEP"
    consumes: { nitrogen: 6.0, phosphorus: 5.0, potassium: 8.0 }
    ideal-ph: 6.5
    ph-tolerance: 1.5
    compaction-change: 1.0

  cabbage:
    family: "brassicas"
    root-depth: "SHALLOW"
    consumes: { nitrogen: 9.0, phosphorus: 4.0, potassium: 4.0 }
    ideal-ph: 6.5
    ph-tolerance: 1.4
    compaction-change: 1.0

  chinese_cabbage:
    family: "brassicas"
    root-depth: "SHALLOW"
    consumes: { nitrogen: 8.0, phosphorus: 4.0, potassium: 3.0 }
    ideal-ph: 6.5
    ph-tolerance: 1.4
    compaction-change: 1.0

  corn:
    family: "grasses"
    root-depth: "DEEP"
    consumes: { nitrogen: 10.0, phosphorus: 4.0, potassium: 6.0 }
    ideal-ph: 6.2
    ph-tolerance: 1.8
    compaction-change: 2.0

  # The pack's default.yml crop. It is a neutral fallback profile.
  default:
    family: "generic"
    root-depth: "SHALLOW"
    consumes: { nitrogen: 6.0, phosphorus: 4.0, potassium: 4.0 }
    ideal-ph: 6.5
    ph-tolerance: 2.0
    compaction-change: 1.0

  eggplant:
    family: "nightshades"
    root-depth: "DEEP"
    consumes: { nitrogen: 9.0, phosphorus: 5.0, potassium: 7.0 }
    ideal-ph: 6.3
    ph-tolerance: 1.5
    compaction-change: 2.0

  garlic:
    family: "alliums"
    root-depth: "SHALLOW"
    consumes: { nitrogen: 5.0, phosphorus: 4.0, potassium: 5.0 }
    ideal-ph: 6.5
    ph-tolerance: 1.8
    compaction-change: 0.5

  grape:
    family: "vines"
    root-depth: "DEEP"
    consumes: { nitrogen: 5.0, phosphorus: 5.0, potassium: 8.0 }
    ideal-ph: 6.2
    ph-tolerance: 1.3
    compaction-change: 1.0

  hop:
    family: "vines"
    root-depth: "DEEP"
    consumes: { nitrogen: 7.0, phosphorus: 4.0, potassium: 6.0 }
    ideal-ph: 6.4
    ph-tolerance: 1.5
    compaction-change: 1.0

  pepper:
    family: "nightshades"
    root-depth: "SHALLOW"
    consumes: { nitrogen: 8.0, phosphorus: 5.0, potassium: 7.0 }
    ideal-ph: 6.3
    ph-tolerance: 1.5
    compaction-change: 1.5

  pineapple:
    family: "bromeliads"
    root-depth: "SHALLOW"
    consumes: { nitrogen: 5.0, phosphorus: 3.0, potassium: 8.0 }
    ideal-ph: 5.8
    ph-tolerance: 1.6
    compaction-change: 0.5

  pitaya:
    family: "cacti"
    root-depth: "DEEP"
    consumes: { nitrogen: 3.0, phosphorus: 4.0, potassium: 7.0 }
    ideal-ph: 6.0
    ph-tolerance: 2.0
    compaction-change: 0.5
  redpacket:
    family: "ornamental"
    root-depth: "SHALLOW"
    consumes: { nitrogen: 4.0, phosphorus: 4.0, potassium: 4.0 }
    ideal-ph: 6.5
    ph-tolerance: 2.0
    compaction-change: 0.5
```

### Fertilizers Configuration

```yaml
fertilizers:
  bone_meal_compost:
    Material: "mc:bone_meal"
    Radius: 1
    Fertility: 10.0
    Cooldown: 30
    nitrogen: 3.0
    phosphorus: 6.0
    potassium: 2.0
    organic-matter: 2.0
    ph-change: 0.0
    compaction-change: -1.0

  # Example only
  # rich_compost:
  #   Material: "ce:your_namespace:rich_compost"
  #   Radius: 2
  #   Fertility: 25.0
  #   Cooldown: 60
  #   nitrogen: 10.0
  #   phosphorus: 8.0
  #   potassium: 8.0
  #   organic-matter: 12.0
  #   ph-change: 0.0
  #   compaction-change: -4.0
```

### Agricultural Governance Configuration

```yaml
agricultural-governance:
  # Layer 1: one long-term direction per Land/Nation.
  default-philosophy: "sustainable"
  default-policy: "fallow_rest"
  development-philosophies:
    sustainable:
      display-name: "Sustainable"
      description: "Lower volume, lower long-term risk, stronger recovery and upkeep stability."
      allowed-policies:
        - fallow_rest
        - autarky_isolationism
        - communal_shifts
        - boutique_agronomy
        - nomadic_foraging
      effects:
        upkeep-multiplier: 0.90
        production-multiplier: 0.95
        recovery-multiplier: 1.15
    industrial:
      display-name: "Industrial"
      description: "Higher output through chemicals, specialization, and territorial pressure."
      allowed-policies:
        - slash_and_burn
        - cash_crop_monopoly
        - guild_specialization
        - tech_agri
        - feudal_serfdom
      effects:
        upkeep-multiplier: 1.20
        production-multiplier: 1.20
        recovery-multiplier: 0.85

  # Layer 2: one active agricultural policy at a time.
  policies:
    fallow_rest:
      display-name: "Fallow Rest"
      philosophy: "sustainable"
      category: "ecological"
      description: "Temporarily protects farmland so soil health and organic matter recover quickly."
      transition-days: 7
      requirements:
        resting-land-required: true
        prevents-planting: true
        prevents-harvesting: true
      maintenance:
        upkeep-multiplier: 0.00
      effects:
        soil-health-recovery-multiplier: 2.50
        organic-recovery-multiplier: 2.50
        production-multiplier: 0.00
      consequences:
        - "No production while resting."
        - "Encourages territorial crop rotation and recovery zones."

    slash_and_burn:
      display-name: "Slash and Burn"
      philosophy: "industrial"
      category: "ecological"
      description: "Converts organic matter into short-term output at the cost of severe degradation."
      effects:
        production-multiplier: 2.50
        growth-time-multiplier: 0.50
        organic-recovery-multiplier: 0.25
        harvest-depletion-multiplier: 3.00
        monocrop-penalty-multiplier: 2.50
      consequences:
        - "Soil health collapses rapidly."
        - "Recovery becomes difficult after prolonged exploitation."
        - "Land can become barren if fully depleted."

    cash_crop_monopoly:
      display-name: "Cash Crop Monopoly"
      philosophy: "industrial"
      category: "economic"
      description: "Specializes the land around one crop family for export-focused production."
      requirements:
        specialization: "tomato"
      maintenance:
        quota-crop: "tomato"
        quota-amount: 500.0
      effects:
        production-multiplier: 2.50
        growth-time-multiplier: 0.90
        monocrop-penalty-multiplier: 1.80
      consequences:
        - "Other crops become inefficient."
        - "The economy becomes vulnerable to shortages and market shifts."

    autarky_isolationism:
      display-name: "Autarky Isolationism"
      philosophy: "sustainable"
      category: "economic"
      description: "Rewards self-sufficient nations with high crop diversity."
      requirements:
        crop-diversity-min: 80.0
      maintenance:
        upkeep-multiplier: 0.80
      effects:
        production-multiplier: 1.05
        organic-recovery-multiplier: 1.10
      consequences:
        - "Slower monetary growth."
        - "Lower dependency on external markets."

    guild_specialization:
      display-name: "Guild Specialization"
      philosophy: "industrial"
      category: "labor"
      description: "Turns Lands roles into agricultural jobs such as sower, caretaker, and harvester."
      requirements:
        players-required: 3
      effects:
        growth-time-multiplier: 0.90
        fertilizer-efficiency-multiplier: 1.20
        yield-bonus: 0.10
        premium-quality-bonus: 0.05
        seed-recovery-bonus: 0.05
      consequences:
        - "Manual teamwork becomes more valuable."
        - "Players outside their specialization can be penalized by future role hooks."

    communal_shifts:
      display-name: "Communal Shifts"
      philosophy: "sustainable"
      category: "labor"
      description: "Rewards coordinated harvest seasons where several nation members work together."
      maintenance:
        no-tool-durability-consumption: true
      effects:
        organic-recovery-multiplier: 1.15
        compaction-recovery-multiplier: 1.10
        yield-bonus: 0.05
      consequences:
        - "Solo farming is less efficient than organized work."

    boutique_agronomy:
      display-name: "Boutique Agronomy"
      philosophy: "sustainable"
      category: "labor"
      description: "Focuses on craftsmanship, quality, mutation chances, and low-volume premium crops."
      effects:
        production-multiplier: 0.60
        premium-quality-bonus: 0.15
        mutation-bonus: 0.10
        seed-recovery-bonus: 0.10
        harvest-depletion-multiplier: 0.75
        rotation-bonus-multiplier: 1.25
        organic-recovery-multiplier: 1.20
      consequences:
        - "Cannot support mass food production alone."

    nomadic_foraging:
      display-name: "Nomadic Foraging"
      philosophy: "sustainable"
      category: "territorial"
      description: "Integrates crops into forests, meadows, and scattered landscapes."
      effects:
        harvest-depletion-multiplier: 0.00
        compaction-recovery-multiplier: 1.50
        max-water-storage-multiplier: 1.25
        production-multiplier: 0.45
      consequences:
        - "Requires much larger territories for the same total output."
```

## Lands Integration

### Enable this on settings

settings.yml

```yaml
settings:
  soil-enabled: true
  lands:
    # Nothing is loaded or calculated unless this is enabled and a supported territory plugin is found.
    # provider: auto, lands, towny
    enabled: false
    provider: "towny" # auto, lands, towny
    # false = track each Towny town separately. true = track the whole Towny nation together.
    towny-use-nations: false
    # Cache values once a real Lands API hook is connected; 300 = five minutes    # Cache values once a real territory hook is connected; 300 = five minutes.
    cache-refresh-seconds: 300
    default-philosophy: "sustainable"
    default-policy: "sustainable"
    policies:
      sustainable:
        rotation-bonus-multiplier: 1.10
        organic-recovery-multiplier: 1.20
        yield-bonus: 0.05
        monocrop-penalty-multiplier: 1.00
      industrial:
        rotation-bonus-multiplier: 1.00
        organic-recovery-multiplier: 0.90
        yield-bonus: 0.10
        monocrop-penalty-multiplier: 2.00
```

### How this works?

1. MaskyCrops detects that \`settings.lands.enabled\` is true and that the Lands plugin is installed.
2. When planting, harvesting, fertilizing, or reclaiming a plot, MaskyCrops queries Lands: “Which claim does this location belong to?”
3. If the plot is within a claim, its H2 status is grouped under that claim’s ID.

Every cache-refresh-seconds, MaskyCrops recalculates the claim’s statistics:

### Placeholders

|                                      | Info                                                                                                                                                                                       |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `%maskycrops_land_soil_health%`      | Shows the overall agricultural health of the claim, on a scale from 0 to 100. It combines fertility, N/P/K, organic matter, pH, compaction, and diversity.                                 |
| `%maskycrops_land_crop_diversity%`   | Shows the agricultural diversity of the claim, on a scale from 0 to 100. It increases when you harvest crops from different families, such as nightshades, brassicas, legumes, or grasses. |
| `%maskycrops_land_average_nitrogen%` | Displays the average nitrogen level for all plots recorded within the claim, on a scale from 0 to 100. A low value reduces effective crop growth.                                          |
| `%maskycrops_land_specialization%`   | Shows the predominant crop family in the claim based on the most recent recorded harvests. For example: `nightshades`, `legumes`, `grasses`, or “`none`” if there are no harvests yet.     |