Log inGet started
Package

regrowKit.package

Newest version

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)):

PresetGrows back inGood for
quick30 sgrass, pebbles, sticks
normal90 sberry bushes, small plants (the default)
slow300 strees, ore rocks
hourly1 in-game hour on worldClockKit, 150 s without itfishing spots
daily1 in-game day on worldClockKit, 600 s without itloot crates, rare nodes
neverdoes not come backone-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:

LookWhile spentWhen it grows back
shrinkchildren scaled to 25% (default)grow back smoothly over 1.5 s
fadechildren scaled to 60%grow back smoothly over 1.5 s
hidechildren hiddenshown again
noneunchangedunchanged

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:

PackageVersion

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.