# Configuration

## SproutGarden Configuration

This config file allows you to customise and control all aspects of the SproutGarden plugin. SproutGarden uses a flexible, per-schematic configuration system where each schematic entry has its own individual properties, allowing fine-grained control over tree generation. Whenever you make changes, be sure to reload the configuration in-game using the `/sproutgarden reload` command to apply your adjustments without restarting the server. 

***Default Config***

```yaml
schematics:
  Sproutgarden_oak_variant_1:
    schematic: SproutGarden_oak_1.schem
    replaces: [OAK]
    weight: 5
    rotation: true
    2x2: false
    growth-options:
      bonemeal-items: [BONE_MEAL]
      natural-growth: true
      minimum-age: 1
    offset:
      x: 0
      y: 0
      z: 0
  
  oak_variant_2:
    schematic: SproutGarden_oak_2.schem
    replaces: [OAK]
    weight: 3
    rotation: true
    2x2: false
    growth-options:
      bonemeal-items: [BONE_MEAL]
      natural-growth: true
      minimum-age: 1
    offset:
      x: 0
      y: 0
      z: 0
  
  birch_tree:
    schematic: SproutGarden_birch_1.schem
    replaces: [BIRCH]
    weight: 1
    rotation: true
    2x2: false
    growth-options:
      bonemeal-items: [BONE_MEAL]
      natural-growth: true
      minimum-age: 1
    offset:
      x: 0
      y: 0
      z: 0
  
  cherry_tree:
    schematic: SproutGarden_cherry_1.schem
    replaces: [CHERRY]
    weight: 1
    rotation: true
    2x2: false
    growth-options:
      bonemeal-items: [BONE_MEAL]
      natural-growth: true
      minimum-age: 1
    offset:
      x: 0
      y: 0
      z: 0

# Settings
settings:
  enabled-worlds:
    - world
    - world_nether
    - world_the_end
  place-at-sapling: true
  ignore-air-blocks: true
  block-updates: false
  enforce-decay: false
  destructive-growth: false
  debug: false

```

### Schematics Section

The schematics section defines individual tree schematic entries. Each entry has a unique internal name and detailed properties controlling when and how it's placed.

*Basic Structure*

```yaml
schematics:
  unique_internal_name:
    schematic: filename.schem
    replaces: [TREE_TYPE_1, TREE_TYPE_2]
    weight: 1
    rotation: true
    2x2: false
    growth-options:
      bonemeal-items: [BONE_MEAL]
      natural-growth: true
      minimum-age: 1
    offset:
      x: 0
      y: 0
      z: 0
```

#### Properties Explained

* **`unique_internal_name`**: (required). The internal name given by you for each schematic config, this can be anything you like but it must be unique.
* **`schematic`**: (required). The .schem file name located in your plugins/SproutGarden/schematics/ folder. You can also specify a specific folder within the schematics folder by writing the schematic entry like this: **`steves_schematics/tree1.schem`**. You can specify multiple schematics to share the same settings.
* **`replaces`**: (required). A list of tree types or custom saplings that this schematic can replace. Multiple entries mean the schematic can be used for any of those types. \
  \
  Vanilla Tree Types: [All TreeTypes are available](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/TreeType.html), but some friendly names are included for your convenience (shown in the [Technical Notes](#technical-notes)).\
  \
  Custom Saplings:
  * ItemsAdder: ia:namespace:sapling\_name (e.g., ia:magic:fairy\_sapling)
  * Nexo: nexo:sapling\_name (e.g., nexo:custom\_oak)

{% code title="Replace Examples" expandable="true" %}

```yaml
# Vanilla tree
replaces: [OAK, BIRCH]

# ItemsAdder custom sapling
replaces: [ia:magic:fairy_sapling]

# Nexo custom sapling
replaces: [nexo:custom_oak]
```

{% endcode %}

{% hint style="warning" %}
ItemsAdder blocks MUST be REAL\_WIRE type.\
Nexo blocks MUST be string\_block type
{% endhint %}

* **`weight`**: (optional, default: 1). Controls selection probability when multiple schematics can replace the same tree type. Higher weights = more common. If you have two OAK schematics with weights 5 and 3, the first appears \~63% of the time (5/8) and the second \~37% (3/8).
* **`rotation`**: (optional, default: true). Enables random 90° rotations (0°, 90°, 180°, 270°) when placing this schematic.
* **`2x2`**: (optional, default: false). Whether a 2x2 pattern of saplings is required for growth. Works with both vanilla and custom saplings.
  * The following vanilla types are excluded from 2x2 detection (already native 2x2): DARK\_OAK, JUNGLE, PALE\_OAK.
  * All 4 saplings must be the same type and arranged in a 2x2 square.
* **`growth-options`**: 
  * **`bonemeal-items`**:   Items which can be used as bonemeal for this specific config. Minecraft, Nexo and ItemsAdder items are accepted. Accepts a list, or one item.
  * **`natural-growth`**:  (optional, default: true). Whether the sapling can grow naturally over time.
  * **`minimum-age`**: (optional, default: 1). The minimum time (in minutes) a sapling must be in order to grow naturally. 
* **`offset`**: (optional, default: 0,0,0). Shifts the schematic placement relative to the sapling location. If **`place-at-sapling: true`** offset occurs after the centering process.

#### Settings Section

* **`enabled-worlds`**: Specifies which game worlds the plugin is active in. Adding the name of a world to this list means the plugin functions in that world. An empty list (`[]`) will disable the plugin entirely. World names are case sensitive
* **`place-at-sapling`**: If set to `true`, the plugin will automatically center schematics over a sapling. This involves calculation of the trunk, and schematics will be centered based on the trunk location.
* **`ignore_air_blocks`**: If set to `true`, air blocks in schematics are not placed.
* **`block-updates`**: If set to `false`, disables block updates when placing a schematic. Useful if your trees contain blocks like floating flowers or torches.
* **`enforce-decay`**: If set to `true`, all leaves in a schematic will be set to persistent=false, and distance=7. This allows for vanilla-like leaf decay and is useful if you forgot to set this when creating your schematics. 
* **`destructive-growth`**: If set to `false`, schematics will only replace air - not existing blocks.
* **`debug`**: Enables debug mode when set to `true`, allowing for more detailed plugin logging which aids in troubleshooting.

### Configuration Examples

***Example 1: Multiple Variants with Weighted Selection***

<pre class="language-yaml"><code class="lang-yaml"><strong>schematics:
</strong>  oak_small:
    schematic: oak_small.schem
    replaces: [OAK]
    weight: 10      # Most common
    rotation: true
    2x2: false
    offset:
      x: 0
      y: 0
      z: 0
  
  oak_medium:
    schematic: oak_medium.schem
    replaces: [OAK]
    weight: 5       # Less common
    rotation: true
    2x2: false
    offset:
      x: 0
      y: 0
      z: 0
  
  oak_large:
    schematic: oak_large.schem
    replaces: [OAK]
    weight: 1       # Rare
    rotation: true
    2x2: false
    offset:
      x: 0
      y: 0
      z: 0
</code></pre>

*Result: 62.5% small, 31.25% medium, 6.25% large.*

\
***Example 2: Custom Nexo and ItemsAdder Saplings***

```yaml
schematics:
  fairy_tree:
    schematic: fairy_tree.schem
    replaces: [ia:magic:fairy_sapling]
    weight: 1
    rotation: false
    2x2: false
    offset:
      x: 0
      y: 0
      z: 0
  palm_tree:
    schematic: palm_tree.schem
    replaces: [nexo:palm_sapling]
    weight: 1
    rotation: true
    2x2: false
    offset:
      x: 0
      y: 0
      z: 0
```

***Example 3: 2x2 Nonstandard Saplings***

```yaml
schematics:
  mega_oak:
    schematic: mega_oak.schem
    replaces: [OAK]
    weight: 1
    rotation: true
    2x2: true          # Requires 2x2 sapling pattern
    offset:
      x: 0
      y: 0
      z: 0
  
  normal_oak:
    schematic: normal_oak.schem
    replaces: [OAK]
    weight: 10
    rotation: true
    2x2: false         # Normal 1x1 growth
    offset:
      x: 0
      y: 0
      z: 0
```

***Example 4: Multiple Trees***

```yaml
schematics:
  generic_tree:
    schematic: generic_tree.schem
    replaces: [OAK, BIRCH, SPRUCE]  # Can replace multiple types
    weight: 1
    rotation: true
    2x2: false
    offset:
      x: 0
      y: 0
      z: 0
```

***Example 5: Multiple Schematics***

```yml
schematics:
  normal_oaks:
    schematic: # Can select multiple schematics to use the same settings
    - generic_tree_1.schem
    - generic_tree_2.schem
    - generic_tree_3.schem
    - generic_tree_4.schem
    replaces: [OAK]  
    weight: 1
    rotation: true
    2x2: false
    offset:
      x: 0
      y: -1
      z: 0
```

### Technical Notes/FAQ

**Database Storage**\
Schematics are stored in mappings.db (SQLite) for efficient runtime access. Database automatically rebuilds when config changes are reloaded using `/sproutgarden reload`.

**Tree Type Normalisation**\
The plugin automatically converts friendly names to Bukkit enums. You can use either in your config.

* OAK → TREE
* SPRUCE → REDWOOD
* BIG\_SPRUCE → TALL\_REDWOOD
* HUGE\_SPRUCE → MEGA\_REDWOOD
* BIG\_OAK → BIG\_TREE

**Custom Sapling Growth**\
Nexo and IA saplings can grow naturally overtime, or with bonemeal. 2x2 patterns are available for custom saplings.

**Leaf Decay Support**\
Unfortunately, Nexo and ItemsAdder custom leaves do not support automatic decay. This feature is planned for a future update/plugin. \
\
For vanilla leaves, use `enforce-decay: true` to enable decay for custom trees that don't have it set automatically.

### Need Help?

No worries! Help is available via our discord!\
[Click here to Join! ](https://discord.gg/UmtS8P2RDJ)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sproutstudios.gitbook.io/sproutstudios/sproutgarden/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.