Farming

Usage guide of farming.crops: plots, tilling, planting, watering, growth stages over game time, harvest and regrowth, seasons, settings and defaults, service, events, verbs and hooks.

Source: module-kits:kits/farming_crops/usage/en.mdView Markdown source

Also read offline — CLI: grip-forge docs farming-cropsMCP tool: gripforge_docs { "topic": "farming-crops" }

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 #

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 #

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.

{ "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 } }] }

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.