Log inGet started
Package

gatherKit.package

Newest version

README.md

gatherKit

Gather spots for any survival or crafting game: walk up, press the prompt, get items in your bag; spots run out and grow back. For creators asking "how do I add resource gathering to my game", "how do I let players punch trees for wood", "how do I make gather nodes" or "how do I let players pick berries in a survival game". Fifteen resources (palms, rocks, berry bushes, driftwood, grass, fishing pools, bananas, mushrooms, clam beds, reeds, flint, fallen coconuts, seaweed, ore veins and ferns), each with what one pick gives, a tool that doubles it, how many picks it holds and how fast it grows back. Works in multiplayer: every pick is decided by the spot's owner, so two players never get the same one.

Version 1.0.4. New in 1.0.4: released from the Castaway Isle main line together with the other survival kits, on the current engine library; no behaviour change. New in 1.0.3: the gallery rebuilds when a resource changes, so a game's mode giving every spot one regrow pace shows at once.

Quick start

In build.luau (or any script that builds your scene), on synced entities:

local spot = asset.resolve("gatherKit.GatherSpot", "component")
local palm = entity.spawnSynced("Palm1", { position = { 12, 0, 40 } })
palm.component.add(spot, { resource = "palm" })
local bush = entity.spawnSynced("Bush1", { position = { 16, 0, 38 } })
bush.component.add(spot, { resource = "bush" })

-- anywhere, to react to what players gather
local Gather = require("~gatherKit.gather")
Gather.on("gathered", function(item, n, resourceId) print("got", n, item, "from", resourceId) end)

Walk up to the palm, press E (pad X, or tap): wood and palm leaves land in your bag and a toast says what you got. After five punches the palm shrinks back and its prompt reads "Grows back soon"; five minutes later it grows back.

Resources and options

ResourceLabelOne pick givesTool (doubles)PicksRegrowProp
palmPalm tree1-2 wood, 0-1 palmLeaf, 1 coconut (35%)stoneAxe5slowpalmCoconutStraight
rockLoose stones1-2 stonestonePick6normalrockBeach
bushBerry bush1-3 berries, 0-1 fibernone4normalhibiscusBush
driftwoodDriftwood1-3 woodstoneAxe2slowdriftwoodLog
grassTall grass1-2 fibernone5quickbeachGrass
fishingFishing pool1 rawFish, 1 crabMeat (30%)spear3hourlya shallow pool
bananaBanana plant1-2 banana, 0-1 palmLeafnone3slowpalmYoung
mushroomMushroom patch1-2 mushroom, 1 fiber (25%)none3normaltropicalUndergrowth
clamBedClam bed1 crabMeat, 0-1 seaweed, 1-2 shell (50%)spear3hourlyshellScatter
reedsReeds1-2 reed, 1 fiberstoneAxe4quickseaOats
flintFlint scatter1 flint, 0-1 stonestonePick3slowpebbleScatter
coconutPileFallen coconuts1-2 coconutnone2slowcoconutPile
seaweedSeaweed1-2 seaweed, 1 fiber (40%)none4quickseaweedLine
oreVeinOre vein1-2 stone, 1 ore (60%)stonePick4dailyrockBasalt
fernFern1-2 fiber, 0-1 palmLeafnone3quickfernTropical

Regrow presets come from regrowKit: quick 30 s, normal 90 s, slow 5 min, hourly 1 in-game hour (150 s without worldClockKit), daily 1 in-game day (600 s without it), never. A resource may give a number of seconds instead.

GatherSpot fields: resource (default palm), propScale (default 1), prompt (default true; off leaves the prompt to you). To change how a spot runs out, put your own regrowKit Regrowing on the entity before GatherSpot (its maxCharges, regrow, spentLook hide, shrink, fade or none); GatherSpot keeps one that is already there.

Items: gatherKit defines the materials and tools it gives (stone, fiber, palmLeaf, wood, flint, ore, reed, shell, mushroom, stoneAxe, stonePick) in inventoryKit only when no other kit has. Foods (coconut, berries, banana, rawFish, crabMeat, seaweed) are survivalNeedsKit's, so they are edible when it is installed; without it gatherKit adds plain versions.

API

gather module

local Gather = require("~gatherKit.gather")

CallWhat it does
Gather.VERSION"1.0.0"
Gather.RESOURCES{ [id] = { label, verb, gives = { { item, min, max, chance? } }, tool?, charges, regrow, prop, category } }
Gather.RESOURCE_ORDERResource ids in display order.
Gather.define(id, def)Add or replace a resource; gives may be { item = , min = , max = , chance = } or { item, min, max, chance }. Errors naming what is wrong. Returns the stored resource.
Gather.roll(id, withTool, rng?)One pick, rolled without touching any bag: { { id, count } }. rng returns 0..1 (default math.random); a chance passes when rng() < chance; the tool doubles every count.
Gather.give(id, withTool)Roll a pick into the local player's inventoryKit bag (leftovers drop at their feet). Emits gathered per item; returns what was given. Does nothing outside play or without inventoryKit.
Gather.hasTool(id)Whether the local player carries the resource's tool.
Gather.items()Every item id the resources give or use as a tool, sorted; defines the ones inventoryKit lacks.
Gather.describe(got)"+2 Wood +1 Palm Leaf" for a list from give or roll.
Gather.on(event, fn)Listen; returns unsubscribe. gathered(item, n, resourceId), picked(resourceId, entityId), empty(resourceId, entityId).
Gather.ITEMS, Gather.FOOD_FALLBACKThe item definitions gatherKit adds when missing.

Components

ComponentWhat it does
gatherKit.GatherSpotOn a synced entity: draws the resource's tropicalProps prop as a child gatherProp, adds a regrowKit Regrowing (resource charges and regrow) if there is none, and an interactKit prompt reading the verb, or "Grows back soon" when spent. Using it takes a charge through regrowKit.take, then gives the pick, toasts it (navUiKit) and plays juiceKit dust.
gatherKit.GatherGalleryEvery resource as a working spot in one labelled row (gives, tool, picks, regrow). Local and temporary; safe in any scene.

Multiplayer

Put GatherSpot on synced entities. The prop and prompt are drawn on every peer; the Regrowing charges are synced and written only by the entity's owner. A player pressing the prompt asks the owner through regrowKit.take; the owner spends one charge and answers that player alone, and only then does that player's own engine roll the pick into their own bag. Two players pressing at once get one charge each while charges last, never the same one. The spent look and the "Grows back soon" prompt follow the synced charges, so everyone sees the same bush.

Tests

asset.resolve("gatherKit", "testSuite"):run() runs 17 tests: every resource complete with valid items, tools and props; roll with fixed random sources (min, max, chance, tool doubling); define; events; give outside play doing nothing safely; items defining its materials; GatherSpot adding a Regrowing with the resource's charges, its prop and prompt; GatherGallery; and the README and version against the code.

Guides

  • How do I add resource gathering to my survival game (gatherKit.package/how-do-i-add-resource-gathering-to-my-survival-game.guide): the ideas, the resources, tools, regrowing, multiplayer and your own resources.
  • Example: punch palms and pick berries on an island (gatherKit.package/example-punch-palms-and-pick-berries-on-an-island.guide): a worked example from an empty island to a gathering loop with a stone axe.

What it installs

Installing gatherKit brings these packages, each from its own world, at the versions it was built and tested with:

PackageVersion
inventoryKit1.0.26
interactKit1.6.3
regrowKit1.0.2