# regrowKit
Things that get used up and grow back, for any multiplayer Zero game: berry bushes, trees, ore rocks, fishing spots and loot crates. Answers "how do I make bushes and trees grow back after harvesting", respawning resources, regrowing resource nodes and harvestable nodes that refill on a timer. Put a `Regrowing` component on a synced entity, pick a regrow preset and a spent look, and take charges from scripts; the entity's owner decides every take, so two players never get the same charge.
Version 1.0.2. New in 1.0.2: released from the Castaway Isle main line together with the other survival kits, on the current engine library; no behaviour change.
```lua
local Regrow = require("regrowKit.regrow")
local bush = entity.spawn("berryBush", { position = { 4, 0, 2 } })
bush:setSynced(true)
-- children of the bush are its leaves and berries (the part that shrinks)
bush.component.add(asset.resolve("regrowKit.Regrowing", "component"),
{ maxCharges = 3, regrow = "normal", spentLook = "shrink", visual = "berries" })
Regrow.take(bush, function(granted)
if granted then print("you picked a berry") else print("nothing left, come back later") end
end)
Regrow.on("regrown", function(id) print("bush " .. tostring(id) .. " is full again") end)
```
## Styles and options
Regrow presets (`regrow` field, or `Regrow.secondsFor(id)`):
| Preset | Grows back in | Good for |
| --- | --- | --- |
| `quick` | 30 s | grass, pebbles, sticks |
| `normal` | 90 s | berry bushes, small plants (the default) |
| `slow` | 300 s | trees, ore rocks |
| `hourly` | 1 in-game hour on worldClockKit, 150 s without it | fishing spots |
| `daily` | 1 in-game day on worldClockKit, 600 s without it | loot crates, rare nodes |
| `never` | does not come back | one-time loot |
`regrowSeconds` > 0 overrides the preset with real seconds. Add your own with `Regrow.define("seasonal", { label = "Seasonal", seconds = 1200 })` or `{ gameHours = 72, seconds = 1800 }` to follow the in-game clock.
Spent looks (`spentLook` field), applied to every child entity, or only the child named by `visual`:
| Look | While spent | When it grows back |
| --- | --- | --- |
| `shrink` | children scaled to 25% (default) | grow back smoothly over 1.5 s |
| `fade` | children scaled to 60% | grow back smoothly over 1.5 s |
| `hide` | children hidden | shown again |
| `none` | unchanged | unchanged |
Other fields: `charges` (-1 fills to `maxCharges` on start; synced, written by the owner), `maxCharges` (5), `readyAt` (synced `os.time()` when it grows back, 0 while not spent).
To see every preset at once, add the `RegrowGallery` component to a plain entity and press R.
## API
Module `require("regrowKit.regrow")`:
- `M.VERSION: string` is `"1.0.2"`; `M.CHANNEL` is `"regrowKit"`; `M.EVENTS` lists the event names.
- `M.PRESETS: { [string]: { label: string, seconds: number, gameHours: number?, description: string } }` and `M.PRESET_ORDER: { string }`.
- `M.define(id: string, def: { label?, seconds: number, gameHours?, description? }) -> preset` adds or replaces a preset.
- `M.secondsFor(presetOrSeconds: string | number) -> number` real seconds to grow back (-1 is never); reads worldClockKit's day length when the preset has `gameHours`, falling back to `seconds`. An unknown id answers `normal`.
- `M.on(event: string, fn) -> () -> ()` subscribes; returns unsubscribe. Events: `taken(entityId, peer, chargesLeft)`, `spent(entityId)`, `regrown(entityId)`, `refused(entityId, peer)`. They fire on the owner's machine.
- `M.take(e, fn: ((granted: boolean) -> ())?)` asks the entity's Regrowing owner for one charge for the local player; `fn` runs on this machine. When this machine owns the entity (or the owner reads 0), it decides at once and calls `fn` right away. An entity without Regrowing answers `false`.
- `M.state(e) -> { charges: number, max: number, readyAt: number, spent: boolean }?` or nil without Regrowing.
- `M._emit(event, ...)` fires an event (used by the component).
Component `Regrowing` (`asset.resolve("regrowKit.Regrowing", "component")`), public methods on `e.component.get(ref)`:
- `public:take(peer: number) -> boolean` owner only: spends a charge if any, sets `readyAt` when it reaches 0, emits `taken` and `spent`, or `refused`.
- `public:refill()` owner only: fills to `maxCharges`, clears `readyAt`, grows the look back, emits `regrown` if it was spent.
- `public:describe() -> { id, charges, max, readyAt, spent, regrow, seconds, spentLook, look, hidden, growing }`.
Component `RegrowGallery`: fields `spacing`, `charges`, `key` (`"KeyR"`), `labels`; method `public:takeAll()`.
## What it installs
Installing regrowKit brings these packages, each from its own world, at the versions it was built and tested with:
| Package | Version |
|---|---|
## Multiplayer
Put `Regrowing` on a synced entity. `charges` and `readyAt` are synced fields written only by the entity's owner (`entity:owner()`, with owner 0 treated as local), and the owner's `update` refills the node when `os.time()` reaches `readyAt`. A take from another machine travels on the multiplayer channel `regrowKit` as `("take", entityId, peer)`; the owner spends the charge and replies `("grant", entityId, peer, granted)`, which runs the asker's callback. Because only the owner decides, two players tapping the same bush never both get the last berry. Every peer draws the spent look from the synced charges, so everyone sees the same bush. Give the item only inside the `granted` callback.
## Tests
`regrowKit.testSuite` has 15 tests covering presets, `secondsFor`, `define`, spending and refilling, local `take`, events and the spent looks. Run it with `asset.resolve("regrowKit", "testSuite"):run()`.
## Guides
- `how-do-i-make-resources-grow-back-after-players-harvest-them`: the how-to.
- `example-berry-bushes-that-regrow-in-a-survival-game`: a worked example.