# Adding Plants

This guide covers how to define new plant types in the `data/plants.lua` static configuration file. 

Each plant entry defines how that plant behaves in the growing system covering growth stages, item requirements, XP rewards, environmental resistances, and yield.

***

## Default Values

The `defaults` table defines shared values that are inherited by all plants unless explicitly overridden.

#### Example: `defaults`

```lua
plants.defaults = {
    image = "plant_icon.png",
    should_outline = true,
    outline_colour = { r = 100, g = 200, b = 100 },
    preferred_altitude = { min = 0, max = 2000 },

    stages = {
        { stage = 1, model = "prop_veg_crop_03_cab", threshold = 0 },
        { stage = 2, model = "prop_veg_crop_03_cab", threshold = 25 },
        { stage = 3, model = "prop_veg_crop_03_cab", threshold = 50 },
        { stage = 4, model = "prop_veg_crop_03_cab", threshold = 75 },
        { stage = 5, model = "prop_veg_crop_03_cab", threshold = 100 }
    },

    resistances = {
        altitude = 1,
        disease = 1,
        pest = 1,
        soil = 1,
        weather = 1
    },

    yield = {
        min = 2,
        max = 6,
        seed_chance = 0.2,
        seed_factor = 0.2
    },

    xp = {
        water = { min = 2, max = 6 },
        fertilize = { min = 2, max = 6 },
        harvest = { min = 3, max = 9 },
        plant = { min = 1, max = 4 },
        cure = { min = 1, max = 4 }
    },

    water_item = { id = "watering_can_full", label = "Watering Can (Full)", min = 10, max = 20 },
    fertilizer_item = { id = "fertilizer", label = "Basic Fertilizer", min = 5, max = 10 },
    harvest_item = { id = "trimming_shears", label = "Trimming Shears" }
}
```

***

## Adding a New Plant

Each plant is defined as a key in the returned table. All properties are optional and will fall back to `defaults` if omitted.

#### Example: Cabbage

```lua
plants.cabbage = {
    label = "Cabbage",
    image = "cabbage.png",
    xp = {
        water = { min = 2, max = 5 },
        fertilize = { min = 2, max = 5 },
        harvest = { min = 4, max = 8 },
        plant = { min = 2, max = 4 },
        cure = { min = 1, max = 3 }
    }
}
```

Only XP values and image are overridden. All other values will use the shared `defaults`.

#### Example: Tomato with Custom Stages

```lua
plants.tomato = {
    label = "Tomato",
    image = "tomato.png",
    stages = {
        { stage = 1, model = "prop_veg_crop_01", threshold = 0 },
        { stage = 2, model = "prop_veg_crop_01", threshold = 25 },
        { stage = 3, model = "prop_veg_crop_01", threshold = 50 },
        { stage = 4, model = "prop_veg_crop_01", threshold = 75 },
        { stage = 5, model = "prop_veg_crop_01", threshold = 100 }
    }
}
```

This overrides the stage models but inherits everything else.

***

## Automatic Rewards

Each plant automatically generates two reward items unless manually defined:

* A crop item: `{id = "<plant>_crop", label = "<Label>"}`
* A seed item: `{id = "<plant>_seed", label = "<Label> Seed"}`

These are stored in the `rewards` field per plant:

```lua
plants.tomato.rewards = {
    crop = { id = "tomato_crop", label = "Tomato" },
    seed = { id = "tomato_seed", label = "Tomato Seed" }
}
```

This is handled automatically at the bottom of the file:

```lua
for crop_name, def in pairs(plants) do
    if crop_name ~= "defaults" then
        def.rewards = def.rewards or {}
        def.rewards.crop = { id = crop_name .. "_crop", label = def.label }
        def.rewards.seed = { id = crop_name .. "_seed", label = def.label .. " Seed" }
    end
end
```

You can override this if needed by providing your own `rewards` table.

***

## Plant Definition Reference

| Field                | Description                                                             |
| -------------------- | ----------------------------------------------------------------------- |
| `label`              | Display name of the plant.                                              |
| `image`              | Icon filename shown in the UI.                                          |
| `stages`             | Table of `{ stage, model, threshold }` entries defining growth visuals. |
| `resistances`        | Environmental tolerance scores (1 = average).                           |
| `yield`              | Harvest quantity and seed drop logic.                                   |
| `xp`                 | XP rewards granted for various interactions.                            |
| `water_item`         | Item used to water the plant (requires `id`, `label`, `min`, `max`).    |
| `fertilizer_item`    | Item used to fertilize the plant.                                       |
| `harvest_item`       | Required item to harvest the crop.                                      |
| `preferred_altitude` | Optional altitude range the plant prefers to grow in.                   |
| `should_outline`     | If true, highlights the plant with an outline in DUI-based UIs.         |
| `outline_colour`     | RGB values used for the outline color.                                  |
| `rewards`            | Custom crop and seed item definitions (optional).                       |