Log inGet started
Package

cropsKit.package

This package holds more than this page lists. See all of its files in its world.

README.md

cropsKit

cropsKit lets any world grow things. Plants go from seed to harvest over the in-game days of the shared worldClockKit clock: twenty-two growables, from wheat and carrots to an apple tree that lasts for years, a crystal that only grows in the dark and an alien pod that runs the seasons backwards, each with five or six stages you can tell apart at a glance and a withered look. Water them with a watering can, a sprinkler or the shared rain, or watch them dry out and wither. Some regrow after harvest, trees last for years, every plant has seasons it loves and seasons it dies in, and a jump of the clock is caught up sensibly. Five kinds of plot, three farm looks, four ways to show a plant's state, seeds and harvests as ordinary inventoryKit items, farming XP and discoveries in saveKit. Every player sees the same farm, late joiners included; two players harvesting at once get one harvest; the farm carries on when the host leaves and is still there next session.

Everything shares one way of working: a growable is one name, a plot kind is one field, the look is one setting. Swapping a carrot for a pumpkin, a raised bed for a pot or the natural look for the pixel look is a single change.

Version 1.0.15 (Crops.VERSION, package.yaml and this README move together).

First example

  1. Install cropsKit from ZeroMind (search "cropsKit" or "Green Thumb"). It brings worldClockKit, gridKit, interactKit, inventoryKit (with saveKit) and the five Swatchbook material collections it paints with.
  2. In a brand-new world, open scenes/main.scene/build.luau and add these lines at the end of function content(), before its end:
    local Crops = require("~cropsKit.api")
    entity.spawnSynced("WorldClock").component.add("WorldClock", { dayLengthMinutes = 6 })
    Crops.farm({ look = "cozy" })
    Crops.plot("raised", { 0, 0, 5 }, { cols = 3, rows = 2, plant = "carrot,tomato,poppy", startStage = 1 })
    Crops.seedBox("carrot", { -2.5, 0, 3 })
    Crops.waterSource("well", { 2.8, 0, 3 })
  1. Press Play. You start with a watering can and some seeds (the farm's startItems). Walk up to the raised bed and press E (the gamepad's west button, or the on-screen Interact button on a phone) when a prompt shows over a cell: on an empty cell it plants the seeds you carry, on a plant whose soil has dried ("Water the Tomato") it waters it, and on a ripe plant it harvests it into your inventory (Tab or I opens it). The bed starts freshly watered, so its plants first ask for water after about half a game day. The front row is in reach from the front of the bed; walk round to its side or back for the back row. The crate gives carrot seeds, the well refills the can, and J opens the farming almanac. A game day is six real minutes here; carrots are ready in about three days.

Guides

Two guides ship inside this package and install with it. Open them in the editor's Docs panel by their titles, with man <path> in the shell, or with the guides tool and the path:

  • How to grow crops in my game (plants that need watering, seasons and harvests): what cropsKit is, how the farm, plots, props and growables fit together, and what to do first. man cropsKit.package/guides/how-to-grow-crops-in-my-game (guide.md)
  • Make a small farming game: from an empty world to planting, watering and harvesting: a whole small game built step by step in a new world, with the real names to install and why each choice was made. man cropsKit.package/guides/make-a-small-farming-game (guide.md)

What you get

PartWhat it is
cropsKit.apiThe one interface: local Crops = require("~cropsKit.api")
CropFarmThe farm's settings, one per scene on a synced entity: look, indicator, growth speed, saving, what new players carry
CropPlotA plot of cells on a synced entity: the plants, their water, the growing rules, the prompts; tended makes it a display plot that never dies
CropSprinklerWaters every plot cell within its radius each morning
CropWaterSourceA well, hand pump or trough that refills the watering can
CropSeedBoxA crate or market stall of seeds, optionally locked to a farming level
CropBedA hammock that sleeps to the next morning (the farm catches up over the night): at once for a player alone, once every player has used a bed when others are there
CropAlmanacA notice board that opens the farming almanac
CropGalleryA labelled gallery of growables at every stage (plus autumn, dormant and withered) in each look: one exhibit pad per growable with a name plaque, the stage under every plant and the look of every row, small growables in front and trees at the back
CropDecorScenery from the kit's art: a growable standing at a stage (a mature oak, a berry hedge) or a prop (fence, scarecrow, signpost), in the farm's look, never growing
CropHudEach player's farm strip, plant card and almanac (made by CropFarm)
44 itemsA seed and a harvest for every growable (the oak gives inventoryKit's wood), and the wateringCan
cropsKitTestsThe test suite

Every growable

GrowableIdFamilyWhat it is
WheatwheatgrainA patch of wheat that turns from green blades to gold, nodding ears.
CorncorngrainTall maize that shoots past head height, tassels out and bears two or three cobs.
CarrotcarrotrootFeathery tops over an orange root whose shoulders show as it swells. Likes it cool.
TomatotomatofruitingA staked vine that flowers, sets green fruit and ripens it red, then flowers again. Frost kills it.
PumpkinpumpkinfruitingA sprawling vine with big leaves and yellow flowers that sets one huge pumpkin. An autumn crop.
Berry BushberryBushshrubA hardy shrub that lives for years: it flowers, fruits blue, is picked and fruits again, and sleeps bare through winter.
Apple TreeappleTreetreeA fruit tree that takes two seasons to come into bearing and then lasts for years: blossom, apples, picked, apples again. Bare in winter. Deep roots ride out a dry week.
Red PoppypoppyflowerBright red cup flowers. Cut three times, then it has given its all.
SunflowersunflowerflowerA yellow giant that grows taller than a person and turns a big face to the sky. Summer's flower.
BluebellbluebellflowerArching stems of nodding blue bells. A cool-weather flower that wilts in summer heat but shrugs off winter.
MushroommushroomfungusRed-capped mushrooms on a mossy log. Wants soil that never dries, grows best in the dark, loves autumn and dies in summer heat. Three flushes per log.
Prickly PearcactussucculentA desert cactus that lives for years and fruits again and again. It never needs watering; too much water, or a long wet spell, rots it.
RicericegrainPaddy rice: grows only in a flooded paddy, wants water at all times, and bows golden when ready.
Grape VinegrapesvineA vine trained along a trellis: slow to establish, then purple bunches every few days through summer and autumn for years. Bare in winter.
OakoakTreetreeA timber tree. Chop it for wood and it grows back from the stump; it lasts as long as it is not left dry for a fortnight.
Crystal ClustercrystaloddityA geode that grows glowing crystal spires, but only in the dark, faster in the cold, and not at all in summer. It drinks nothing, and water dissolves it: keep it dry and out of the rain.
Alien PodalienPododditySomething that should not grow here: a pulsing pod on writhing tendrils. It runs the seasons backwards (loves winter, dies in summer), drinks a full can a day, feeds on rain and storms, and spends itself after four harvests.
Pixel TurnippixelTurnippixelFrom the little pixel-art crop set: a chunky purple-and-white turnip that pops out of the ground. Quick.
Pixel StrawberrypixelStrawberrypixelFrom the little pixel-art crop set: a sprite strawberry plant that flowers white and fruits red, again and again until winter.
Pixel CarrotpixelCarrotpixelFrom the little pixel-art crop set: a tuft of feathery fronds over an orange root that comes up half out of the ground when it is ready. Happy in the cold.
Pixel PumpkinpixelPumpkinpixelFrom the little pixel-art crop set: a low vine with chunky leaves and yellow trumpet flowers that swells one big ribbed pumpkin. Slow, thirsty, made for autumn.
Pixel CornpixelCornpixelFrom the little pixel-art crop set: a stalk that shoots up knee high, then tall with a tassel, and carries yellow cobs in green husks. Loves summer, dies in the frost.

Every growable has the stages below, a withered look (browned, slumped, its glow gone) and, for the ones that sleep through a season, a dormant look (bare branches, a dim crystal). Trees and leafy perennials (apple, oak, berry bush, grape vine) also have an autumn look: through autumn their leaves turn amber, rust and gold, then fall for the winter.

GrowableStages (first to ripe)
WheatSeed, Sprout, Tillering, Heading, Ripening, Golden
CornSeed, Sprout, Knee high, Tall, Tasseled, Ripe cobs
CarrotSeed, Sprout, Leafy, Bulking, Ready
TomatoSeed, Sprout, Bushy, Flowering, Green fruit, Ripe
PumpkinSeed, Sprout, Vine, Flowering, Green pumpkin, Ripe
Berry BushCutting, Young bush, Bush, Flowering, Berries
Apple TreeSapling, Young tree, Tree, Blossom, Apples
Red PoppySeed, Sprout, Stem, Bud, In bloom
SunflowerSeed, Sprout, Stalk, Bud, In bloom
BluebellBulb, Shoots, Stems, Buds, In bloom
MushroomSpawned log, Mycelium, Pins, Buttons, Caps open
Prickly PearSeed, Nub, Pads, Flowering, Fruit
RiceSeedling, Transplant, Tillering, Heading, Ripening, Golden
Grape VineCutting, Vine, Climbing, Flowering, Bunches
OakAcorn, Sapling, Pole, Young oak, Mature oak
Crystal ClusterGeode, Shards, Cluster, Spires, Radiant
Alien PodSpore, Tendrils, Bulb, Pulsing, Bursting
Pixel TurnipSeed, Sprout, Leafy, Bulb, Ready
Pixel StrawberrySeed, Sprout, Leafy, Flowering, Berries
Pixel CarrotSeed, Sprout, Fronds, Shoulders, Ready
Pixel PumpkinSeed, Sprout, Vine, Flowering, Pumpkin
Pixel CornSeed, Sprout, Knee high, Tasseled, Ripe cobs

How water, withering, regrowth and seasons work

The rules are the same for every growable; the numbers in the table below are what makes each one different. Time is in game days (24 game hours, as long as the WorldClock's dayLengthMinutes); the farm's growthSpeed multiplies every growth time.

  • Water. Each cell has a soil moisture from 0 (dust dry) to 1 (soaked). A watering (can or sprinkler) sets it to 1. Every game hour a plant drinks its share of its daily drink (times the plot's drying rate, times 1.35 in summer, 0.9 in autumn, 0.6 in winter), bare soil dries slowly too, and rain adds 0.22 an hour (0.4 in a storm) to every plot that is not sheltered.
  • Thirsty and too wet. Below its "thirsty below" level a plant stops growing and is under water stress; above its "too wet" level (the cactus and the crystal have one) it stops growing and is under stress too. Stress hours add up while it lasts and heal at half speed once the water is right again. When stress reaches the "withers after" time the plant withers: it stays, brown and slumped, until a player clears it.
  • Growth. A plant that is neither thirsty nor drowning banks growth hours at its season's rate times its light (most plants grow at full speed by day and 0.35 by night; the mushroom and the alien pod prefer night, the crystal grows only at night), times rain (the alien pod grows two times faster in rain and three times in a storm), times the plot's growth bonus. Its stage follows the banked hours; at the last stage it is ripe and waits there, still drinking.
  • Tended plots. A plot with tended on is looked after like a display garden. Its soil is kept where each plant likes it (no thirst, no drowning, whatever the rain does), nothing in it withers on its own, not even in a season the plant hates (it just stops growing), and a cell of its plant list that stands empty or withered for 12 game hours is sown again. A tended plot that loads a save holding dead plants shows its planting again at once. Players can still plant, water, harvest and clear it. Everything in this section applies in full to plots that are not tended.
  • Seasons. Each plant loves a season (x1.3 growth), likes it (x1), finds it slow (x0.6), sleeps through it (no growth, no harm, it drinks a quarter, perennials show bare) or dies in it (no growth, and after 2 days of it the plant withers from frost or heat). A change of season changes all of this at the next game hour.
  • Harvest and regrowth. Harvesting a ripe plant gives its harvest to the player who did it. A one-harvest crop leaves the cell empty. A regrowing one goes back to its regrow stage and ripens again in its regrow time; some are spent after a number of harvests and wither where they stand. The oak is chopped to a stump and regrows from it. Perennials and trees have no lifespan: they last as long as they are not left to wither.
  • Catching up. The plot's owner brings every plant up to the clock once a game hour. When the clock jumps forward (Clock.advance, a bed, a skip), the gap is simulated hour by hour with each hour's own season and night, sprinklers at their hour, and the rain of the moment for at most the first 6 hours of the gap; gaps longer than the farm's maxCatchUpDays (28) simulate only the last 28 days. When the clock goes back (setTime into the past, or a new session whose clock started again at day 1), nothing grows or withers: the plants keep exactly where they were and the count starts again from the new time.
GrowableKindDays to ripeHarvestRegrowthWater: drinks per day / thirsty below / too wet above / withers afterSpringSummerAutumnWinterLightPlots
Wheatannual43-5 wheatOne harvest, then the cell is empty0.35 / 0.20 / never / 2.5 dayslikesloveslikesdiesday x1, night x0.35tilled, raised, hydro
Cornannual62-3 cornOne harvest, then the cell is empty0.50 / 0.25 / never / 2 daysslowloveslikesdiesday x1, night x0.35tilled, raised
Carrotannual31-2 carrotOne harvest, then the cell is empty0.40 / 0.20 / never / 3 dayslovesslowlovesslowday x1, night x0.35tilled, raised, pot, hydro
Tomatoregrow52-4 tomatoBack to flowering, ripe again in 2 days; for years0.55 / 0.30 / never / 2 dayslikeslovesslowdiesday x1, night x0.35tilled, raised, pot, hydro
Pumpkinannual81 pumpkinOne harvest, then the cell is empty0.45 / 0.25 / never / 3 daysslowlikeslovesdiesday x1, night x0.35tilled, raised
Berry Bushperennial63-6 berriesBack to flowering, ripe again in 3 days; for years0.35 / 0.15 / never / 5 dayslikesloveslikessleepsday x1, night x0.35tilled, raised, pot
Apple Treetree144-8 appleBack to tree, ripe again in 5 days; for years0.25 / 0.10 / never / 8 daysloveslikeslovessleepsday x1, night x0.35tilled
Red Poppyregrow31-2 poppyBack to bud, ripe again in 2 days; spent (withers) after 3 harvests0.40 / 0.20 / never / 2 daysloveslikesslowdiesday x1, night x0.35tilled, raised, pot, hydro
Sunflowerannual41 sunflowerOne harvest, then the cell is empty0.50 / 0.25 / never / 2 dayslikeslovesslowdiesday x1, night x0.35tilled, raised, hydro
Bluebellregrow31-2 bluebellBack to buds, ripe again in 2 days; spent (withers) after 3 harvests0.40 / 0.25 / never / 2 dayslovesdieslikesslowday x1, night x0.35tilled, raised, pot, hydro
Mushroomregrow22-4 mushroomBack to pins, ripe again in 1.5 days; spent (withers) after 3 harvests0.60 / 0.45 / never / 1 dayslikesdieslovesslowday x0.5, night x1.5tilled, raised, pot, hydro
Prickly Pearperennial72-4 cactusFruitBack to flowering, ripe again in 4 days; for years0.15 / never / 0.60 / 1.5 dayslikeslovesslowsleepsday x1, night x0.35tilled, raised, pot
Riceannual63-5 riceOne harvest, then the cell is empty0.50 / 0.60 / never / 1.5 dayslikeslovesslowdiesday x1, night x0.35paddy
Grape Vineperennial92-4 grapesBack to flowering, ripe again in 4 days; for years0.30 / 0.15 / never / 5 dayslikesloveslovessleepsday x1, night x0.35tilled, raised
Oaktree83-5 woodChopped to a stump, regrows from the sapling stage in 5 days, for years0.20 / 0.08 / never / 14 daysloveslikeslikessleepsday x1, night x0.35tilled
Crystal Clusterregrow52-3 crystalShardBack to cluster, ripe again in 2 days; for years0.25 / never / 0.55 / 1.5 daysslowsleepslikeslovesday x0, night x1.4tilled, raised, pot, hydro
Alien Podregrow41-2 alienPodBack to bulb, ripe again in 2 days; spent (withers) after 4 harvests1.00 / 0.40 / never / 1 daysslowdieslikeslovesday x0.75, night x1.5; rain x2, storm x3tilled, raised, pot, hydro
Pixel Turnipannual21-2 pixelTurnipOne harvest, then the cell is empty0.40 / 0.20 / never / 2 daysloveslikeslovesdiesday x1, night x0.35tilled, raised, pot, hydro
Pixel Strawberryregrow32-3 pixelStrawberryBack to flowering, ripe again in 1.5 days; for years0.45 / 0.25 / never / 2 daysloveslovesslowdiesday x1, night x0.35tilled, raised, pot, hydro
Pixel Carrotannual2.51-2 pixelCarrotOne harvest, then the cell is empty0.40 / 0.20 / never / 2.5 dayslovesslowlovesslowday x1, night x0.35tilled, raised, pot, hydro
Pixel Pumpkinannual41 pixelPumpkinOne harvest, then the cell is empty0.55 / 0.30 / never / 2 daysslowlikeslovesdiesday x1, night x0.35tilled, raised
Pixel Cornannual3.51-2 pixelCornOne harvest, then the cell is empty0.50 / 0.25 / never / 2 dayslikeslovesslowdiesday x1, night x0.35tilled, raised, hydro

Columns: "Water" is drink per day / the moisture below which it is thirsty / the moisture above which it is too wet / how many days of stress wither it. "Light" multiplies growth by day and by night. "Plots" are the plot kinds it can be planted in.

Looks: one setting for the whole farm

Crops.setLook(name), or the CropFarm's look field. A plot can keep a look of its own (look on its CropPlot).

LookWhat it looks like
naturalReal-world plants: textured oak bark, cut-out leaf cards that glow with the light behind them, glossy fruit, real dirt, mud and weathered planks (groundMaterials, organicMaterials, woodsMaterials).
cozyThe same plants chunkier and brighter, cel-shaded with toonMaterials' toonSurface and drawn with an ink outline; toon dirt, planks and water.
pixelEvery plant rebuilt from voxels in a small fixed palette, on retroMaterials' 16-pixel dirt, planks, water and grass. The pixel crop set is voxel art in every look.

Plot kinds

Crops.plot(kind, position, opts), or the CropPlot's kind field.

KindWhat it isRules
tilledFurrowed field soil in rowsDries at the normal rate; the only plot trees can root in
raisedA plank box of rich soilDries at 0.9, grows x1.1
potA terracotta pot, one plant eachDries at 1.4; no trees, no rice
paddyA flooded field behind an earth bundA watering floods it for 3 days and it drains at 0.35; rice only
hydroA sci-fi hydroponic tray under a grow lightSheltered from rain; a watering fills its reservoir, which keeps the roots at 0.75 for 4 days; grows x1.2; no trees, no rice

Watering

WayHow
Watering canThe wateringCan item. Use it on a plant or on bare soil; it holds 10 waterings and refills at any CropWaterSource (well, pump, trough).
SprinklerA CropSprinkler (sprinkler or sprinklerTall) waters every plot cell within its radius once a day at its hour (6:00), even across a jump of the clock.
RainworldClockKit's rain and storm weather water every plot that is not sheltered, every game hour it lasts.

Showing a plant's state

Crops.setIndicator(name), or the CropFarm's indicator field.

IndicatorWhat it shows
iconA small sign floating above any plant that needs something: a blue drop when thirsty, a basket when ripe, waves when drowning, a sun in a summer too hot for it, a snowflake in a winter too cold for it, a no-entry sign in a spring or autumn it cannot stand, a sleep sign while it is dormant, a wilted leaf when withered.
ringA ring on the soil round every plant that fills as it grows: green while growing, blue while thirsty, gold when ripe, orange out of season, brown when withered.
cardA card for the plant you face: its name, stage, growth and water bars, what the season does to it, and how long until it is ripe.
noneNothing; the plant's own look is the only sign.

The farming almanac is always there for every player: J (the CropFarm's almanacKey), the Almanac button on the farm strip, or a CropAlmanac board. It lists every growable with its seasons, water, harvest, regrowth and plot kinds.

Seeds, harvests and progression

Seeds and harvests are ordinary inventoryKit items (carrotSeeds, carrot, ...), defined as data assets bound to inventoryKit.inventoryItem, so every inventory screen and everything else that uses items works with them. Planting uses the seeds in the selected hotbar slot, or else the first seeds the player carries that can grow in that plot. Harvests are food where it makes sense (eating heals through inventoryKit's heal effect).

Every harvest gives farming XP in the player's saveKit profile (5 per growing day, doubled for the oddities), and the first harvest of each growable is a discovery (Crops.discoveries()). A CropSeedBox's minLevel locks it until the player's farming level reaches it.

Components

ComponentFields
CropFarmlook, indicator, growthSpeed, persist, farmKey, maxCatchUpDays, setupInventory, screen, startItems ("item:count, ..."), almanacKey, hud
CropPlotkind, cols, rows, cellSize (0 = the kind's own), look (empty = the farm's), plotId (save name; empty = the entity's name), tended (a display plot: see below), plant (what to sow when nothing is saved: one growable per cell, - for bare soil, carrot@3 to start that cell at stage 3), startStage, startWet, active
CropSprinklerkind, radius, hour, look, active
CropWaterSourcekind (well, pump, trough), look
CropSeedBoxgrowable, count, kind (seedBox, seedStand), minLevel, look
CropBedwakeHour, look
CropAlmanaclook
CropGallerygrowables, looks, columns, bayGap, labels, plinths, buildRange
CropDecorgrowable, stage (-1 ripe), dormant, variant, prop, look

Put CropFarm and CropPlot on synced entities (Crops.farm and Crops.plot do); the props can sit on plain entities.

API

local Crops = require("~cropsKit.api")

CallDoes
Crops.farm(opts)Spawns the CropFarm (synced) with any of its fields
Crops.plot(kind, pos, opts)Spawns a CropPlot (synced): cols, rows, cellSize, look, plant, startStage, startWet, plotId, yaw, name
Crops.sprinkler(pos, opts), Crops.waterSource(kind, pos, opts), Crops.seedBox(id, pos, opts), Crops.bed(pos, opts), Crops.almanacBoard(pos, opts)Spawn the props
Crops.decor(id, pos, opts)Scenery: a growable at opts.stage, or Crops.decor(nil, pos, { prop = "fence" })
Crops.component(name)A component type by short name, for component.add / get / has wherever the package is installed
Crops.setLook(look), Crops.look()The farm's look, for everyone
Crops.setIndicator(name), Crops.indicator()How plants show their state, for everyone
Crops.setGrowthSpeed(x)How fast everything grows, for everyone
Crops.growables(), Crops.get(id), Crops.catalog()The catalog as data
Crops.define(id, def), Crops.registerArt(id, fn)Add a growable and its art
Crops.on(event, fn)Listen for farm events (below); returns a function that stops listening
Crops.propose(action, args?, cb?)Ask for a shared action: "sleep" (args.wakeHour), "rain", "clearSky" or "replant". A player alone gets it at once; with others it happens when every player has asked for it within 45 seconds (see Multiplayer)
Crops.defineAction(name, label, run)Add your own shared action; run(args) runs once, when everyone agrees
Crops.vote()The shared action being voted on now, or nil: { action, label, agreed, needed, secondsLeft, mine } (the farm strip shows it)
Crops.replantAll()Sow every plot afresh from its plant list, for everyone, straight away (for a game's own reset; players use propose("replant"))
Crops.previewSeason(season)Show only the local player the farm in another season (nil for the real one). Growth and every other player follow the real season
Crops.plots(), Crops.plotOf(target)The plots this peer knows, keyed by each plot's entity id (for id, plot in Crops.plots(), or the first one with local _, plot = next(Crops.plots())); one plot by its entity, entity id or name
Crops.cell(plot, q, r)What grows in a cell: its record plus status, stage, stageName, progress, ripe
Crops.plant(plot, q, r, id, cb), Crops.water(...), Crops.harvest(...), Crops.clear(...)Act on a cell from a script, through the same owner as a player
Crops.canLevel(), Crops.refillCan()The local player's watering can
Crops.setAlmanac(open)Open or close the almanac on this player's screen
Crops.level(), Crops.discoveries()The local player's farming level and discoveries
Crops.showcase(id, origin, look, opts)A row of one growable at every stage (local entities)
Crops.stats()Counters: plots, plants, requests, simulated hours, catch-ups, saves, loads, meshes
Crops.VERSION, Crops.LOOKS, Crops.PLOTS, Crops.INDICATORS, Crops.WATERINGS, Crops.EVENTSNames

Events

planted, watered, harvested, cleared and refused fire on the machine of the player who acted. stage, ripe and withered fire on every machine as it sees the change. look fires on the machine that changed a setting (other machines see the new look through the synced CropFarm; poll Crops.look() to follow it). caughtUp (a plot simulated a jump of the clock, or found the clock gone back: rebased = true) and loaded (a saved plot came back) fire on the plot owner's machine. Every payload names the plot and, where it applies, the cell ("q,r") and growable.

Adding your own growable

local Crops = require("~cropsKit.api")
Crops.define("radish", {
    name = "Radish", family = "root", kind = "annual",
    description = "A quick red radish.",
    stages = { { id = "seed", name = "Seed", share = 0.2 }, { id = "sprout", name = "Sprout", share = 0.3 },
               { id = "leafy", name = "Leafy", share = 0.5 }, { id = "ripe", name = "Ready", share = 0 } },
    growDays = 1.5, harvest = { item = "radish", min = 1, max = 3, verb = "Pull" },
    seasons = { spring = "love", summer = "ok", autumn = "like", winter = "hate" },
    water = { drink = 0.4, min = 0.2, stressDays = 2 },
    plots = { tilled = true, raised = true, pot = true },
    seed = { item = "radishSeeds", name = "Radish Seeds" },
})
Crops.registerArt("radish", function(g, ctx)
    -- g is a cropsKit.geo builder; draw stage ctx.stage standing on the origin
    g:slot("foliage"); g:color(0.3, 0.6, 0.2)
    for i = 1, 3 + ctx.stage * 2 do
        g:push(); g:rotateY(i * 2.4); g:rotateX(-0.6); g:leaf(0.06 + 0.04 * ctx.stage, 0.04); g:pop()
    end
    if ctx.ripe then g:slot("fruit"); g:color(0.85, 0.1, 0.2); g:sphere(0.03) end
end)

Add the radish and radishSeeds items as inventoryKit item data assets. The withered look, the cosy palette and ink and the pixel voxels come for free. Optional fields: regrow = { toStage, days, harvests, fromStump }, light = { day, night }, rainBoost = { rain, storm }, hateDays, water.max, oddity, size (footprint in metres).

Multiplayer

  • One owner decides each plot. A CropPlot sits on a synced entity; its owner (the first player in, handed on by the engine when they leave, so the farm carries on without the host) runs the growing rules once a game hour and writes the plot's cells in one synced field. Every other player draws the same plants from it; a late joiner receives it and sees exactly what everyone sees.

  • Acting goes through the owner. Planting, watering, harvesting and clearing are requests to the owner carrying the cell's revision the player saw. Two players pressing harvest at the same moment send two requests on one revision: the first harvests, the second is told someone got there first, so there is one harvest between them. The harvest goes into the inventory of the player whose request won. A player's seeds leave their own inventory before the request goes out and come back if it is refused.

  • Nothing is lost to a slow answer. A request the owner has not answered in 8 seconds (Farm.REQUEST_TIMEOUT) counts as refused, so the prompt never hangs. If the owner's yes still arrives within the next minute (a lag spike, or the host leaving mid-request), it is honoured: the harvest is given and a planting keeps its seed. A repeated or late refusal changes nothing.

  • When the host leaves. The engine hands each plot to a player who stays, and that player's machine carries on from the synced cells and the shared clock with nothing reloaded: the plants, their water and the next game hour's growth carry straight on.

  • Everything else is local and free. Prompts, cards, icons, rings and the almanac are drawn by each player from the shared cells. Sprinkler sprays play on every machine from the shared clock. The look and indicator are fields of the synced CropFarm.

  • Shared actions ask everyone. Sleeping to the morning, calling or stopping the rain and replanting the farm change the world for every player, so no player does them to the others alone. A player alone gets them at once. With others in the session the first player's request starts a vote that the farm strip shows to everyone ("Sleep until morning? 1 of 3 agree"); each player agrees by asking for the same thing (using a bed, pressing the same button), and the action happens when all of them have, within 45 seconds. The CropFarm's owner counts the vote, so it carries on when the host leaves. Seeing another season is personal instead: Crops.previewSeason changes only the local player's view.

Saving and the clock

With persist on (the default), the owner saves each plot to the world's runtime data under cropsKit/<farmKey>/<plotId>: at once after a player plants, waters, harvests or clears (so leaving straight after a harvest never brings the crop back next session), and a few seconds after the hourly growth. When the world opens again, the first owner loads it and catches the plants up to the clock (see Catching up). If the world's saved data has not reached that machine yet, the plot sows its starting plants, writes nothing for 15 seconds, and takes the save as soon as it arrives, as long as nobody has played on the plot meanwhile; a save is never overwritten by a fresh sowing. A plot whose kind or size changed starts fresh. The farm makes sense whether or not the WorldClock keeps its place between sessions (persist on the WorldClock): if the clock comes back at day 1, the plants simply carry on from where they were.

Performance

A quiet field costs next to nothing: plants are static meshes, nothing about a plant runs per frame, and each plot's owner does its arithmetic once a game hour. Meshes are built once per growable, stage, state, variant and look and shared by every plant showing them, and the engine draws static meshes as GPU-culled clusters. Each player redraws a plant only when its stage, water or state changes. New meshes are built at most 8 ms a frame (Art.frameBudgetMs), so a farm coming into view, a look change or a player joining never stalls a frame for long; a CropGallery builds a bay only when the camera comes within buildRange metres.

Measured in the desktop editor in play, on the demo farm as it ships (15 plots, 58 plants, the scenery and the gallery): the CropPlots, the CropDecor scenery and the CropGallery together cost too little to show in the engine's script profiler, which lists anything above 0.01 ms a frame, while nobody walks up to the gallery. A plot's owner does its sums once a game hour. The plant meshes for everything on screen in one look were about 500, shared by every plant showing them. The one cost that grew with the number of plants was interactKit's prompt HUD, which looked at every usable thing every frame (about 5 ms with 270 plant cells); interactKit 1.3.2 now skips far ones with a single distance check, and that fix went back to interactKit.

Tests

cropsKitTests covers the catalog (every growable has four or more stages, seasons, items and art), the rules (water, withering, seasons, light, rain, shelter, rot, plot kinds, harvest and regrowth), a live plot deciding requests including two simultaneous harvests, catching up and a clock going back, every growable and plot kind drawing in every look, the settings, and this README against the catalog. Run it with tools.use("tests", "run", { suite = "cropsKitTests" }).

Dependencies

Installed with cropsKit: worldClockKit 1.4.1 (with Soundstage), gridKit 1.0.9, interactKit 1.3.2 (with controlsKit and juiceKit), inventoryKit 1.0.9 (with pickupsKit, saveKit and their own), groundMaterials 1.0.4, organicMaterials 1.0.1, woodsMaterials 1.0.1, toonMaterials 1.0.4 and retroMaterials 1.0.2 (with materialLibraryKit).

Changes

  • 1.0.15: worldClockKit 1.6.4 is installed afresh. A stray world-owned copy of its kit module (left by an interrupted update) had been published with cropsKit 1.0.13 and 1.0.14 as a release of its own, so an install loaded two copies of that module; it is gone and the module comes from worldClockKit's own release. No cropsKit code changed; the suite runs 18 of 18.

  • 1.0.14: the worldClockKit install is recorded at worldClockKit 1.6.4 exactly as its own world publishes it; 1.0.13 had recorded its kit module as a release of its own, so an install landed two copies of that module. No cropsKit code changed; the suite runs 18 of 18.

  • 1.0.13: retroMaterials 1.0.3 and organicMaterials 1.0.8, both on the current engine library, so the retro and organic shaders share one release of the engine's shadows shader module and an install of cropsKit (alone or beside economyKit) lands one release of every package. No cropsKit code changed; the suite runs 18 of 18.

  • 1.0.12: Dependencies brought current, so a world that installs cropsKit beside economyKit holds one release of each shared kit: inventoryKit 1.0.24 (it skips an inventory left over from an earlier play session, which had shadowed the live one so that harvests failed with 'entity was despawned'), interactKit 1.6.3 (its prompts and the devices registered with it are one release again), worldClockKit 1.6.4, gridKit 1.0.13, woodsMaterials 1.0.2, groundMaterials 1.0.8, organicMaterials 1.0.7 and toonMaterials 1.0.11, and the current engine library. No cropsKit code changed; the suite runs 18 of 18.

  • 1.0.11: The package's descriptions say what cropsKit gives a creator and how to start: install it from ZeroMind, add a WorldClock, Crops.farm and Crops.plot to a scene's build.luau and press Play, with the two guides named. The start line used to leave out the WorldClock the farm grows by. Nothing in the kit, the guides or the rest of this README changed.

  • 1.0.10: Known limits no longer lists a guide search limited to your own world missing the guides (#22315): that is fixed and the report is closed. Nothing in the kit or the guides changed.

  • 1.0.9: The how-to guide's "Act on a cell from a script" recipe works as written in a fresh install: it took Crops.plots()[1], but Crops.plots() is keyed by each plot's entity id, so it found no plot and failed with "cropsKit: no plot nil". It now takes the first plot with next(Crops.plots()), says how to ask for a plot by name, and says it runs while the game plays; the API table says how Crops.plots() is keyed. The planted, watered, harvested, cleared and refused events now name the growable, as this README always said they did (they used to leave it out, so the guide's "React to the farm" recipe printed nil).

  • 1.0.8: Two guides ship with the package: "How to grow crops in my game" (what the kit is and what to do first) and "Make a small farming game" (an empty world to a playable farm with a sprinklered field, hand-watered beds, level-locked seed stalls and a bed to sleep in, every step tested in a fresh world). The first example now says that watering is offered once a plant's soil has dried, and that a bed's back row is reached from its side or back. Nothing in cropsKit's code changed.

  • 1.0.7: Installing cropsKit into a fresh world gives a working inventory again. cropsKit needs inventoryKit 1.0.9, but its author's world was still publishing 1.0.7, so a fresh install brought the 1.0.7 package with three loose 1.0.9 files beside it that could not load, and every player arrived with no hotbar, watering can or seeds. inventoryKit 1.0.9 is now published from its own world and cropsKit names that release. Nothing in cropsKit's growing, art or rules changed.

  • 1.0.6: A plant in a season it cannot stand now says which: "hot" in summer (a sun icon), "cold" in winter (a snowflake) and "unseasonal" in spring or autumn, where every such season used to read "cold"; its card says "Too hot in summer: it stops growing" and whether its gardener keeps it alive. The card's season line reads as a sentence for every plant. The package's list of what it needs names the versions it is tested with (worldClockKit 1.4.1, inventoryKit 1.0.9, groundMaterials 1.0.4, toonMaterials 1.0.4), and the README and descriptions say five or six stages and give the demo farm's real numbers.

  • 1.0.5: A showcase farm nobody can ruin, and fairness between players. A plot can be tended (a display plot: kept watered and drained, never withers, sows its own plants again), and a tended plot that loads dead plants shows its planting again at once. Sleeping, the rain and the new replant are shared actions that every player present has to agree to (Crops.propose), shown on the farm strip; a player alone still gets them at once. Crops.previewSeason shows one player the farm in another season without changing anyone else's. The farm strip folds into two rows on a phone held upright. A CropGallery builds only the bays near the camera in the editor too, and waits quietly while nothing is in range, so it costs nothing per frame. The demo starts every session on a clear morning (worldClockKit 1.4.1's persistHour and persistWeather), shows one clock, keeps its display plots tended and gives visitors a patch of their own where the rules are real.

  • 1.0.4: The pixel-art crop set is five crops: a carrot, a pumpkin and a corn join the turnip and the strawberry, each with five stages, a withered look, its own seasons and water, seeds and a harvest as inventoryKit items with their own icons. The test suite now builds the whole list: every growable at every stage and state in all three looks, every plot kind, prop and icon. The plant card says "Cut for 1 sunflower" rather than "1-1".

  • 1.0.3: The look. Seasons show on the plants: trees and leafy perennials turn amber and rust in autumn (the natural look swaps to autumn leaf cards) and stand bare through the season they sleep, in plots, in CropDecor scenery and in the gallery's new Autumn column; CropDecor scenery now follows the season too. A plot's plant list can start each cell at its own stage (carrot@1,carrot@2,carrot@3), so one bed shows a plant growing. The gallery's labels are static text meshes that cost nothing per frame: a sloped name plaque per growable, the stage name in front of every plant (read left to right) and each row's look; every growable stands on its own exhibit pad, smaller growables in front and trees at the back, with room enough that nothing overlaps.

  • 1.0.2: Multiplayer and saving, after a check of every guarantee. A player's plant, water, harvest or clear is saved at once, so leaving straight after a harvest can no longer bring the crop back next session. A plot that finds no save waits 15 seconds before writing one and takes the save if it arrives late, so a slow start never replaces a farm with fresh seedlings. An owner's answer that arrives after a request timed out is now honoured instead of dropped, so a harvest is never lost to lag or to the host leaving mid-request. New test for answers, late answers and one harvest between two players.

  • 1.0.1: The first public release.

Known limits

Each is an open report, in the engine's tracker or ZeroMind's.

  • Two engines signed in to one account are one player (#14448). Seeds, harvests and farming XP live in each player's own inventoryKit and saveKit profile, so a two-player check needs two accounts.
  • Browser figures are not in this README (#20946: an agent cannot start a browser engine). The figures in Performance come from the desktop engine.
  • A synced farm costs frame time even when nothing on it changes (#20750). The plots' synced state is paid for every frame, whether or not any plant, water or harvest changed, and every player in the session pays it, not only the player whose machine runs the plots.
  • Installing takes a while (#21420): cropsKit brings nine packages and their own dependencies (about 9,000 files with the material collections), so the first install of it into a world is slow.
  • Run-time plots and a scene reload (#21023): a scene reload can save entities made at run time into the scene. Place plots in a scene's build.luau (or the editor); Crops.plot from a running game is fine for a session, and its save comes back only when a plot with the same plotId exists again.
  • Frame rates read the machine (#19390): on a loaded machine the frame rate measures the machine as much as the farm; compare a scene with and without plants on the same machine, as above.
  • The guides may not come up in a library search yet (#22181): guides added to a package that was already published can be missing from ZeroMind's search. They install with the package all the same; open them by the paths in Guides.