# Farming and crops (farming.crops)

## What it is for

Grow food on plots of soil: till a plot, plant a seed of the `crops` collection, water it, watch it go through its growth stages over game time (hours of `world.daynight`, or a pace of its own), and harvest what it yields. Some crops grow back after a harvest; seasons, rain that waters and crops that wither when left dry are optional. A plot is an entity whose state lives in its component. For farming, cozy, survival and RPG games.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "farming.crops" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "farming.crops",
                              config: { "hoursPerSecond": 0.1, "waterHours": 24 } }
```

Needs `game.engine`; installing the kit brings them along.

## First example

<!-- test: kits/game_engine/host/tests/farming_crops.rs::a_plot_goes_from_bare_soil_to_a_harvest -->
One game hour per second. A plot goes from bare soil to a harvest: `use` tills, plants, then waters it in turn. Three wet hours bring the wheat through its first stage and half of the second; growth stops until it is watered again, then the crop is ripe and the harvest pays two wheat.

```json
{ "config": { "hoursPerSecond": 1, "waterHours": 3 },
  "crops": [{ "id": "wheat", "name": "Wheat", "seed": "wheat_seed",
    "stages": [{ "name": "Seed", "hours": 2 }, { "name": "Sprout", "hours": 2 }, { "name": "Ripe", "hours": 0 }],
    "harvest": { "item": "wheat", "count": 2 } }] }
```

```text
placePlot([0, 0, 0], { tilled: false }) -> "e1"
use("e1") x4 -> "till", "plant", "water", "none"
harvest("e1") -> { item: "wheat", count: 2 }     (a second harvest answers null)
```

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `hoursPerSecond` | 0.1 | Game hours a real second is worth when `world.daynight` is not installed. |
| `waterHours` | 24 | Game hours one watering keeps the soil wet. |
| `witherHours` | 0 | A planted crop left dry this many game hours dies (0: never). |
| `hoeItem`, `waterItem` | `""`, `""` | Item needed to till and to water (empty: none needed). |
| `rainWaters` | `true` | Rain of `world.weather` waters every plot. |
| `seasons`, `seasonDays` | `[]`, 7 | Season names in order (empty: no seasons) and the game days a season lasts; a crop can list the seasons it grows in. |
| `reach` | 3 | Plot prompt distance (m). |

A document of `crops` holds `id`, `name`, `seed` (the item planted, one is taken), `stages` (in order, at least 2, each `name` and `hours`; the last is ripe), `harvest` (`item`, `count`), `regrow` (the stage index it goes back to after a harvest; absent: the plot is empty again), `water` (false: grows dry) and `seasons`. Models are bound to the slots `crop` (variant = crop id + "_" + stage index) and `farm_plot` (untilled, tilled, wet).

## Services, events, variables

- Service `farming.crops`: `plots()`, `plot(entity)`, `crops()`, `till(entity)`, `plant(entity, crop?)`, `water(entity)`, `harvest(entity)`, `use(entity)`, `placePlot(at, opts?)`, `season()`, `hours()`.
- Verbs and conditions: `place_plot` (`at`, `tilled`, `crop`), `water_plots`, `crops_ready` (`count`, `crop`). Component on a plot entity: `farm_plot { "tilled": true }`.
- Events: `farm.tilled`, `farm.planted` (`entity`, `crop`), `farm.watered` (`by`: player, rain or script), `farm.stage`, `farm.ready`, `farm.harvested` (`item`, `count`, `regrows`), `farm.withered`, `farm.season`. It listens to `interaction.requested`, `entity.spawned`, `inventory.changed`.
- Variables: `farm.plots`, `farm.ready`, `farm.season`.

## Hooks and modding

| Hook | Meaning |
|---|---|
| `crop.till` | A plot is about to be tilled; cancelled, nothing happens and `till` answers false. |
| `crop.plant` | A seed is about to be planted (before it is taken); cancelled, the seed stays in the bag and `plant` answers false. |
| `crop.water` | A plot is about to be watered by the player or a script (not by rain); `hours` (how long the soil stays wet) is mutable; cancelled, `water` answers false. |
| `crop.harvest` | A ripe crop is about to be harvested; `count` is mutable (a bonus yield, a blight); cancelled, the crop stays ripe and `harvest` answers null. |
| `crop.wither` | A crop left dry `witherHours` is about to die (asked once at the threshold); cancelled, it lives and its dry hours start again from zero. |

Moddable: every setting above and the collection `crops`.

## Limits

Runs on the web player and the native player; Godot, Unity and Unreal have no native delivery of this kit. Rain waters the plots without asking the hooks: it is weather, not a decision. The kit has no shop or inventory of its own: seeds and harvested items are items of the inventory kit.

## Versions

Kit 1.1.1 (hooks in 1.1.0); service `farming.crops` 1.0.0. It relies on `game.engine` ^1; `world.daynight` and `world.weather` are optional.