regrowKit.package
README.md
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.
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: stringis"1.0.2";M.CHANNELis"regrowKit";M.EVENTSlists the event names.M.PRESETS: { [string]: { label: string, seconds: number, gameHours: number?, description: string } }andM.PRESET_ORDER: { string }.M.define(id: string, def: { label?, seconds: number, gameHours?, description? }) -> presetadds or replaces a preset.M.secondsFor(presetOrSeconds: string | number) -> numberreal seconds to grow back (-1 is never); reads worldClockKit's day length when the preset hasgameHours, falling back toseconds. An unknown id answersnormal.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;fnruns on this machine. When this machine owns the entity (or the owner reads 0), it decides at once and callsfnright away. An entity without Regrowing answersfalse.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) -> booleanowner only: spends a charge if any, setsreadyAtwhen it reaches 0, emitstakenandspent, orrefused.public:refill()owner only: fills tomaxCharges, clearsreadyAt, grows the look back, emitsregrownif 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.