Log inGet started
World

Castaway Isle: Island Survival and Crafting Kit

Branchmain
Branchesmain
Commit2a168afc93

README.md

recipeKit

Recipes and a craft menu for any crafting game. If you are asking "how do I add crafting to my game", this is the small, standalone answer: define recipes (what they need, what they give, whether they need a fire or a workbench, or whether the game places them in the world), and open a craft menu that works with mouse, touch and gamepad. Crafting reads and changes the player's own inventoryKit bag. Ready packs cover survival crafting out of the box: recipes for a stone axe, a torch, a stone pick, a fishing spear, a coconut flask, a campfire, cooking at a fire, and walls, floors and roofs.

Version 1.0.6. New in 1.0.6: 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.5: on a gamepad the d-pad and the left stick move the highlight through every recipe (each row names the row above and below it for the engine's focus moves, so focus never jumps to Close; holding repeats), and the list fits the screen on any size: it shows as many rows as fit in 90% of the screen's height (MAX_HEIGHT) and scrolls with the highlight, with "more above / below" markers you can tap or click and a mouse wheel that scrolls. New in 1.0.4: a gamepad drives the craft menu through the engine's own menu navigation (d-pad or stick moves, south crafts, east closes) and the highlighted recipe follows the focused row; while open the menu holds Back, and with menuBackKit installed Escape and Start close it before the pause menu. Gamepad buttons are read through its own padButtons input map first (Menu.padDown), since some clients deliver a pad press only through input maps. On a touch screen the craft menu reads finger taps itself, so tapping a recipe crafts it and tapping Close closes it (a tap can only hover a button in some builds).

Example

local Recipes = require("recipeKit.recipes")
local Menu = require("recipeKit.menu")

Recipes.loadPack("survivalBasics")
Recipes.define("rope", { label = "Rope", needs = { fiber = 3 }, result = { "rope", 1 }, category = "tools" })
Recipes.setStationCheck(function(station) return station ~= "fire" or myGame.nearFire() end)
Recipes.onPlace(function(id, recipe) return myGame.placeInFront(recipe.place, function() return Recipes.pay(id) end) end)

-- on the player's body: C or pad Select opens the menu
body.component.add(asset.resolve("recipeKit.CraftMenu", "component"), { theme = "rustic", layout = "list" })

Styles and options

optionvalues
themerustic (default, brown and gold), scifi, cartoon, pixel, minimal, cozy. Each sets colours, corner radius and font.
layoutlist (one column list, default), grid (two column grid)
titlethe menu's title, default Crafting
categoriesonly show recipes of these categories, e.g. { "cooking" }; nil shows all
packssurvivalBasics (stone axe, stone pick, torch, fishing spear, coconut flask, campfire to place), cooking (cooked fish, grilled crab, roasted root, fish stew, all at a fire), building (wall, floor, roof to place)
cost scaleRecipes.setScale(k): every cost times k, rounded up; 0 makes everything free

Station recipes. A recipe with station = "fire" (or "workbench", or any name) can only be made where your station check says yes. The menu marks it "(at a fire)" and a refusal toasts "Stand by a fire". Without a check every station passes.

Place recipes. A recipe with place = "campfire" gives no item: once the checks pass, craft calls your onPlace(id, recipe) handler, which builds it and takes the cost with Recipes.pay(id) when it really places. Return false, "why" to refuse.

The menu. Each recipe is a button with its cost; what you cannot make yet is greyed out; the selected row has a highlight border; a Close button closes it. The mouse pointer is freed while the menu is open and the game gets it back when it closes.

Controls.

inputwhat it does
mouse or touchclick or tap a row to craft it; hovering a row highlights it; Close closes
keyboardUp and Down arrows or W and S move the highlight (Left and Right too in the grid), Enter or E crafts the highlighted row, Escape closes. Held keys repeat after 0.35 s. menu.keyboard(false) turns the keys off.
gamepadd-pad moves (left and right too in the grid), south (A) crafts, east (B) closes
open and closeC or pad Select with the CraftMenu component, or menu.toggle() from your own controls

API

recipes module (require("recipeKit.recipes"))

callwhat it does
VERSION"1.0.4"
define(id, def)define or replace a recipe. def = { label, needs = { item = n }, result = { item, n }?, place = string?, station = string?, category = string? }; needs a result or a place. Returns the stored recipe.
remove(id)remove a recipe; returns whether it existed
get(id)the recipe or nil
list(category?)recipes in definition order
orderthe id list behind list
setOrder(ids)put these ids first, in this order
categories()categories in use
loadPack(name)define a ready pack; returns its ids
setScale(k), scale()cost multiplier (ceil, 0 is free)
costOf(id){ item = n } after scaling
costText(id)"2 stone, 1 fiber" or "free"
missing(id)what the local player lacks: { item = n }
missingText(miss)"Needs 2 stone, 1 fiber"
canMake(id)(true) or (false, why), including the station check
setStationCheck(fn)fn(station) -> boolean; nil restores the default (every station passes)
atStation(station?)the station check's answer
onPlace(fn)fn(id, recipe) -> (ok, why?), the game's handler for place recipes
pay(id)take the scaled cost from the bag; refuses (takes nothing) when short
craft(id)check, pay, give the result (Inventory.give(item, n, true)) or call the place handler, toast and emit. Returns (ok, why?)
on(event, fn)listen; returns an unsubscribe function. Events: crafted(id), refused(id, why), defined(id)
toast(text, opts?)a navUiKit toast when navUiKit is installed
reset()remove every recipe and listener and restore the defaults

menu module (require("recipeKit.menu"))

callwhat it does
THEMES, THEME_ORDER, THEME_KEYSthe six themes, their order, and the keys every theme sets
LAYOUTS{ { id = "list", columns = 1 }, { id = "grid", columns = 2 } }
setup({ theme, layout, title, categories })pick the look; unknown names are refused
config()the current settings
open(), close(), toggle(), isOpen()show and hide the menu
move(delta)move the highlight, wrapping at either end
nextIndex(sel, n, delta)pure: the row delta steps on among n, wrapping
dirDelta(dir, columns)pure: how far up, down, left, right move with this many columns (left and right are 0 in a list)
repeatStep(rec, down, now, delay?, rate?)pure: key repeat, true on the press and then every rate s once held delay s
keyboard(on?)turn the menu's keyboard handling on or off; returns the setting
indexOf(id)the row a recipe sits on
selected()the highlighted row
pick()craft the highlighted recipe (a click and a key on the same press craft once)
items()the recipes the menu shows
refresh()redraw when open
tree()the widget tree as it would draw now
step()every frame: poll keys and pad (presses fire once, held moves repeat), highlight the hovered row and redraw twice a second
padDown(button)whether a pad button is held on any pad

packs module (require("recipeKit.packs"))

PACKS[name] = { label, description, order, recipes } and ORDER.

Components

  • CraftMenu: on the player's body; only its owner acts. Fields theme (rustic), layout (list), openKey (KeyC, empty for none), padButton (select, empty for none), title (Crafting). A game with its own controls (controlsKit actions) sets openKey = "" and padButton = "" and calls menu.toggle() itself.
  • RecipeGallery: on any entity; opens the menu in each theme in turn with a button panel to switch theme and layout. Local only.

Multiplayer

Crafting is local to each player's own bag: missing, pay and craft read and change only the local player's inventoryKit inventory, which inventoryKit replicates and saves. The menu is drawn on each player's own screen, and CraftMenu acts only on the engine that owns the body. Recipes are plain data: define the same ones on every peer (from a scene entrypoint or a module every peer requires). What a place recipe builds is the game's to replicate.

Tests

recipeKit.testSuite checks defining, listing and ordering, cost scaling (including 0 and rounding up), missing with no bag, the station check, refusals, the place handler, packs, the menu (open, close, move wrapping, grid moves, key repeat, row clicks, the click and key guard, themes) and events. Run it with asset.resolve("recipeKit", "testSuite"):run().

Guides

  • How do I add crafting recipes and a craft menu to my game (recipeKit.package/how-do-i-add-crafting-recipes-and-a-craft-menu-to-my-game.guide)
  • Example: craft a stone axe and a torch on a survival island (recipeKit.package/example-craft-a-stone-axe-and-a-torch-on-a-survival-island.guide)

What it installs

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

PackageVersion
inventoryKit1.0.26
menuBackKit1.0.1