·
data · drop-in viewer
asset⌬ datadataprimary: values.yaml·part ofpackage toolUseKit.package·originates fromworld f58aa3fc-3…
What it does
No description provided yet.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
This asset doesn't declare a schema or structured payload.
⌬ Metadata
description
toolUseKit seed pouch: sows the tilled cells in front of the player, five tiers from a single cell to a 5x5 field; the game picks the seed in its onUse handler.Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
10items
# toolDef (toolUseKit tool contract)
One tool the player can hold and use on the grid cells in front of them. Every
`.data` asset bound to `toolDef`, in this package or anywhere in a world, is
loaded by toolUseKit at setup and becomes a tool known by its `id`.
| field | meaning |
|---|---|
| `id` | the name code uses (`Tools.equip("hoe")`) |
| `name` | what the player reads |
| `short` | optional short label for the strip on narrow (phone) screens; defaults to one per kind (Hoe, Can, Seeds, Axe, Pick, Scythe, Hammer) |
| `icon` | a short glyph or emoji drawn on the tool strip |
| `kind` | `hoe`, `wateringCan`, `axe`, `pickaxe`, `scythe`, `seedPouch`, `hammer` or `generic`; picks the model and the swing, and is what `Tools.onUse(kind, fn)` listens for |
| `description` | one line for menus |
| `swing` | override the swing animation (`chop`, `overhead`, `side`, `sweep`, `pour`, `sow`, `knock`) |
| `useTime` | seconds one use takes, the cooldown between uses |
| `ladder` | the patterns a charge climbs, smallest first |
| `energyCost` | energy one use costs, one number per tier |
| `chargeCost` | extra cost per charge level, times the tier cost |
| `tiers` | the upgrade tiers, first is tier 1 |
Each tier: `name` (Basic, Copper, Steel, Gold, Iridium...), `pattern` (the
biggest pattern a full charge reaches), `patterns` (an explicit charge list
that wins over `ladder` + `pattern`), `chargeTime` (seconds per charge
level), `color` (head colour), `accent` (trim colour), `gem` (adds a gem),
`glow` (glows), and one colour per style (`cartoon`, `pixel`, `painted`,
`realistic`, `scifi`) that wins over `color` in that style.
Patterns: `single`, `line3`, `line5`, `wide3`, `wide5`, `square3`,
`square5`, `cross`, or any name given to `Tools.definePattern`.
▲ 0↑ born
# toolUseKit
**Hold a tool and use it on the tile in front of the player.** A hoe, a
watering can, a seed pouch, an axe, a pickaxe, a scythe, a hammer, or any
tool you define as data. Tools come in upgrade tiers (Basic, Copper, Steel,
Gold, Iridium) that cover a bigger area, a use can be held to charge up to
the tier's biggest pattern (like Stardew Valley), every use costs energy,
and the game reacts through hooks. The kit knows nothing about crops, rocks
or trees, so it fits farming games, mining games, gardening, building,
cleaning or anything played on a grid.
Version 1.0.4 (`Tools.VERSION`). This README, `package.yaml` and
`Tools.VERSION` move together.
What a world gets from installing it:
- **Seven tools as data.** `tools/*.data`, bound to the `toolDef` contract,
and `Tools.defineTool` for your own. Each tool has an id, a name, a short
label, an icon, a kind, an energy cost per tier and five tiers, each with
a name, an area pattern, a charge time and colours per style.
- **175 held-tool variants.** 7 kinds x 5 tiers x 5 styles (cartoon, pixel,
painted, realistic, scifi). Every tier looks different: head colour and
metal, grip wrap, a metal collar from Steel, a gem from Gold, a glow at
Iridium. Walk past all of them in the **gallery scene**.
- **Hold to charge.** Holding use climbs a ladder of patterns (single, line
of 3, line of 5, 3x3, 5x5 or your own offsets) up to the tier's biggest.
- **Energy.** A meter with a max, optional regeneration, a low warning, an
exhausted event and a refund when nothing was hit.
- **Six target highlights** that mark every cell the next use will hit:
softOutline, pixelSquare, paintedRing, hologram, tileTint, corners.
- **Swings with juice**: the hoe chops down, the can tilts and pours, the
seed pouch flicks seeds out, the axe swings sideways, the pickaxe goes
overhead, the scythe sweeps, the hammer knocks twice; dust, splashes,
seeds, wood chips, splinters, stone chips with sparks, grass bits, and ten
sounds made for the kit.
- **Six energy meter looks**: bar, leaf, sun, pixel, hologram, none. The
meter rides with the tool strip, so one setting moves both.
- **Controls that do not clash**: E (interact), the d-pad and the gamepad
west button (hotbar and interact) and, by default, the number keys stay
free for the game and its other kits.
- **A phone HUD**: safe-area aware, 44 point touch targets, short labels and
wrapping on narrow screens, clear of the on-screen touch buttons, in
landscape and portrait.
- **Multiplayer from the start.** Every player sees everyone's held tool and
swing, late joiners included. Each player's tools, tiers and energy are
saved and come back when they rejoin.
- **A test suite** covering areas, energy, the new kinds, bindings and the
phone layout.
Hard dependencies: **none.** It uses only engine built-ins (input maps,
`runtime_data`, the UI and multiplayer surfaces), so it installs beside any
release of controlsKit, saveKit, inventoryKit, friendshipKit or barsKit.
## Quick start (5 minutes)
1. Install toolUseKit into your world.
2. Make sure your scene has a player (a fresh world's scene does).
3. Add a component to any entity in the scene, or put this in a scene
entrypoint, so it runs on every peer:
```lua
local Tools = require("~toolUseKit.api")
function awake()
Tools.setup({
cellSize = 1,
origin = { 0, 0, 0 },
style = "cartoon",
energy = { max = 270 },
hudPosition = "bottom-center",
numberKeys = false, -- true: 1-7 pick a tool (leave false beside an inventory hotbar)
startTools = { { id = "hoe", tier = 1 }, { id = "seedPouch", tier = 1 }, { id = "hammer", tier = 1 } },
})
Tools.onUse("hoe", function(ctx)
for _, cell in ctx.cells do
print("tilled", cell.x, cell.z, "at", cell.world[1], cell.world[3])
end
return true -- return false when nothing happened: the energy comes back
end)
-- the seed pouch: the game decides what is sown, on the cells the kit hands it
Tools.onUse("seedPouch", function(ctx)
local sown = 0
for _, cell in ctx.cells do
if MyFarm.isTilled(cell.x, cell.z) and MyBag.take(MyBag.selectedSeed()) then
MyFarm.plant(cell.x, cell.z, MyBag.selectedSeed())
sown += 1
end
end
return sown > 0
end)
-- the hammer: break or repair what stands on the cells
Tools.onUse("hammer", function(ctx)
local n = 0
for _, cell in ctx.cells do
local thing = MyBuild.at(cell.x, cell.z)
if thing then
if thing.broken then thing:repair() else thing:damage(ctx.tier + ctx.chargeLevel) end
n += 1
end
end
return n > 0
end)
end
```
(`MyFarm`, `MyBag` and `MyBuild` stand for your game's own systems.)
4. Press play. The player holds a hoe, a highlight marks the cell in front,
left click (or C, the right trigger, or the USE button on a phone) uses
it.
## The seven tools
| id | kind | does | area by tier (Basic, Copper, Steel, Gold, Iridium) | energy per use |
|---|---|---|---|---|
| `hoe` | hoe | tills the ground | single, line3, line5, square3, square5 | 2 |
| `wateringCan` | wateringCan | waters the ground | single, line3, line5, square3, square5 | 2 |
| `seedPouch` | seedPouch | sows; the game picks the seed in its handler | single, line3, line5, square3, square5 | 1 |
| `axe` | axe | chops wood | single, single, line3, line3, line5 | 4, 3, 3, 2, 2 |
| `pickaxe` | pickaxe | breaks rock | single, single, line3, line3, square3 | 4, 3, 3, 2, 2 |
| `scythe` | scythe | cuts grass and weeds | wide3, wide3, arc5, wide5, square3 | 1, 1, 1, 1, 0 |
| `hammer` | hammer | breaks or repairs placed things | single, single, line3, line3, square3 | 3, 3, 2, 2, 2 |
A tap hits the first pattern of the tool's ladder; holding climbs one
pattern per charge step up to the tier's biggest. A charged use costs the
tier's cost times `1 + level x chargeCost`.
Variant counts: **7 kinds x 5 tiers x 5 styles = 175 held models**, plus a
`generic` kind for tools of your own (any kind the kit does not know builds
as generic, or set `model` to hold your own mesh or bundle).
## Controls
| action | keyboard and mouse | gamepad | touch |
|---|---|---|---|
| use (hold to charge) | left click or C | right trigger | USE button |
| next tool | F or mouse wheel down | right bumper | tap the tool strip |
| previous tool | Q or mouse wheel up | left bumper | tap the tool strip |
| pick slot 1-7 | 1-7, only with `numberKeys = true` | none | tap the tool strip |
Left free on purpose: **E** and the gamepad **west** face button (the
engine's interact), the **d-pad** (games use it to pick hotbar slots),
**Tab, G, I** (inventoryKit), **R, O** (friendshipKit) and, unless you turn
`numberKeys` on, **1-9** (an inventory hotbar). The main controls are
`controls.inputMap`; the number keys are a separate `numberKeys.inputMap`
the kit only activates when the option is on, so the keys are never bound
while it is off. On a phone the USE button sits first in the touch button
column, so a small screen never folds it into the "..." button.
## The API
`local Tools = require("~toolUseKit.api")`. Everything acts on the local
player; uses run on the using player's own machine.
### Setup and looks
| function | what it does |
|---|---|
| `Tools.setup(opts)` | configure; call on every peer. Calling again changes only what you pass. Returns the settings. |
| `Tools.settings()` | the settings in use |
| `Tools.style()` / `Tools.setStyle(name)` | the held-model style, live |
| `Tools.highlight()` / `Tools.setHighlight(look)` | the target highlight (nil: the style's own) |
| `Tools.energyLook()` / `Tools.setEnergyLook(look)` | the energy meter look (nil: the style's own) |
| `Tools.controlMaps()` | the input maps the kit activates with the settings in use (`controls`, plus `numberKeys` when on) |
| `Tools.hudLayout(W?, H?, safe?)` | where the strip and meter go on a screen (defaults: the current screen and safe area) |
| `Tools.catalogue()` | styles, highlights, energy looks, patterns, tools with tiers, swings, sounds, events, options, hud positions |
| `Tools.stats()` | state for tests and debugging |
`setup` options:
| option | default | meaning |
|---|---|---|
| `cellSize` | 1 | grid cell size in metres |
| `origin` | `{0,0,0}` | where cell 0,0 starts; y is the height the highlight sits at |
| `style` | `"cartoon"` | `cartoon`, `pixel`, `painted`, `realistic`, `scifi` (also `cozy`, `voxel`, `sci-fi`...) |
| `highlight` | style's own | one of the highlight looks |
| `highlightHeight` | 0.03 | metres above `origin.y` |
| `energyLook` | style's own | one of the energy looks |
| `energy` | `{ max = 270, regenPerSecond = 0, exhaustedSlowdown = true, lowFraction = 0.2 }` | the meter (`start` sets the first value). `exhaustedSlowdown` is reserved: 1.0.x does not slow the body itself, so slow your controller from `Tools.on("exhausted", fn)` |
| `startTools` | all seven at tier 1 | `{ {id, tier} }` a new player starts with, in strip order |
| `equip` | first start tool | tool held at the start |
| `reach` | 1 | how many cells in front the target is |
| `facing` | `"cardinal"` | `"cardinal"` (4 ways) or `"eight"` |
| `spendOnMiss` | false | a use every handler said missed still costs energy |
| `allowTiredUse` | false | allow a use with too little energy (energy goes to 0) |
| `hud`, `controls`, `sound` | true | the kit's tool strip and meter, its controls, its sounds |
| `hudPosition` | `"bottom-center"` | where the tool strip and its energy meter sit together: `"bottom-center"`, `"top-left"`, `"bottom-left"`, `"top-center"`. Pick the one other kits leave free |
| `numberKeys` | false | true binds 1-7 to the strip slots; false leaves the number keys to an inventory hotbar (the slots have no keyboard keys) |
| `volume` | 0.8 | sound volume |
| `persist` | true | save tools, tiers and energy per player |
| `saveKey` | `"default"` | keep separate saves per game mode |
| `maxTier` | nil | cap every tool's tier |
### Tools as data
| function | what it does |
|---|---|
| `Tools.defineTool(def)` | add or replace a tool from code; returns the normalised def |
| `Tools.definePattern(name, offsets)` | name a pattern: `{ {side, forward} }`, forward 0 is the target cell |
| `Tools.pattern(name)` | the offsets of a pattern |
| `Tools.tool(id)` / `Tools.tools()` | a tool definition / every tool definition |
A tool def: `{ id, name, short, icon, kind, description, swing, useTime,
ladder, energyCost (number or one per tier), chargeCost, model, modelScale,
tiers }`. A tier: `{ name, pattern, patterns, offsets, chargeTime, color,
accent, gem, glow, tints = { cartoon = "#hex", ... } }`. `kind` picks the
model and swing (`hoe`, `wateringCan`, `seedPouch`, `axe`, `pickaxe`,
`scythe`, `hammer`, `generic`); `swing` overrides the animation (`chop`,
`overhead`, `side`, `sweep`, `pour`, `sow`, `knock`); `model` names a mesh
or bundle to hold instead of the built model; `short` is the strip label on
narrow screens.
A `.data` asset bound to the `toolDef` contract anywhere in your world is
loaded as a tool too (see `toolDef.dataType/README.md`).
### Owning, tiers and holding
| function | what it does |
|---|---|
| `Tools.give(toolId, tier?)` | give a tool (keeps a higher tier the player has) |
| `Tools.take(toolId)` | take it away |
| `Tools.has(toolId)` | whether the player has it |
| `Tools.getTier(toolId)` / `Tools.setTier(toolId, tier)` | read / set a tier (fires `tierChanged`) |
| `Tools.upgrade(toolId)` | one tier up |
| `Tools.list()` | the player's tools in strip order: `{ id, tier, tierName, name, icon, kind, def, equipped }` |
| `Tools.equip(toolId)` / `Tools.unequip()` / `Tools.equipped()` | hold, put away, what is held |
| `Tools.cycle(dir)` / `Tools.equipSlot(n)` | next or previous tool / the n-th tool |
| `Tools.players()` | what every player in the room holds: `{ peer, toolId, tier, style }` |
### Using
| function | what it does |
|---|---|
| `Tools.onUse(kindOrToolId, fn)` | react to uses of a kind, a tool id or `"*"`; returns an unsubscribe function |
| `Tools.use(level?, cell?, facing?)` | use the held tool now from code (AI, tutorials, tests) |
| `Tools.setTargetResolver(fn)` | replace how the target cell is found (gridKit, your own plots); `nil` restores the grid |
| `Tools.target()` | `{ cell, facing, position, forward }` |
| `Tools.previewCells(level?)` | the cells the next use would hit |
| `Tools.charge()` | `{ active, level, maxLevel, fraction, time }` |
| `Tools.costOf(toolId, tier?, level?)` | the energy a use costs |
| `Tools.worldToCell(p)` / `Tools.cellToWorld(x, z)` | grid conversions |
| `Tools.lastUse()` / `Tools.useCount()` | the last ctx / how many uses on this machine |
The `ctx` a handler gets: `player` (the body), `playerId` (peer id),
`userId`, `tool` (the def), `toolId`, `kind`, `tier`, `tierName`,
`chargeLevel` (0 is a tap), `cells` (`{ { x, z, world = {x,y,z} } }`, every
cell the use covers), `cellCount`, `facing` (`{ x, z }`), `origin` (the
target cell `{ x, z }`) and `energySpent`. Return `false` to say nothing
happened there; when every handler says so the kit fires `miss` and, unless
`spendOnMiss` is on, gives the energy back. After handlers ran, `ctx.hit`
and `ctx.refunded` are set. The seed pouch and the hammer use this same
flow: the kit hands over the cells, the game decides what is sown, broken
or repaired.
A resolver gets `{ player, position, forward, facing, reach, cellSize,
origin, defaultCell }` and returns a cell `{ x, z }` (and optionally a facing).
### Energy
`Tools.energy()`, `Tools.maxEnergy()`, `Tools.setEnergy(n)`,
`Tools.addEnergy(n)`, `Tools.restoreEnergy()`, `Tools.setMaxEnergy(n)`,
`Tools.isExhausted()`.
### Events
`Tools.on(event, fn)` returns an unsubscribe function.
| event | arguments |
|---|---|
| `use` | ctx |
| `miss` | `{ reason = "noTool" \| "tired" \| "nothing", toolId, ctx }` |
| `equip` | new id (nil when put away), old id |
| `unequip` | old id |
| `tierChanged` | toolId, new tier, old tier |
| `give` | toolId, tier |
| `energyChanged` | energy, old, max, why |
| `lowEnergy` | energy, max |
| `exhausted` | max |
| `charge` | level, maxLevel |
| `ready` | the player's tool list once their save loaded |
### Saving
`Tools.save()` writes now (it also saves a second after any change),
`Tools.resetProgress()` forgets the player's tools, `Tools.isReady()` says
whether the save has loaded. Saves live in each player's own
`runtime_data.player(id)` store under `toolUseKit/<saveKey>`, the same store
saveKit uses, so they survive leaving and rejoining. A player saved before
1.0.4 keeps their own tools; give them the seed pouch and hammer with
`Tools.give` when your game hands them out.
## Phones
The strip and the energy meter form one group, placed at `hudPosition`
inside `ui.safeArea()`: a screen's frame starts at the safe area's top-left
corner, so the kit lays out in safe-area space and never runs under a
notch, a status bar or a gesture bar. On a narrow screen (a phone in
landscape, about 693x390 points, or portrait, about 390x844) slots shrink
to 52x46 points (never under 44), labels shorten (Hoe, Can, Seeds, Axe,
Pick, Scythe, Hammer) and the strip wraps into rows when it must. With a
touch screen the group keeps clear of the on-screen buttons: it fits
between them when there is room and otherwise steps up above them (top
anchors step down). The placement is `Hud.layout(W, H, safe, opts)`, a
pure function the tests run at both phone shapes.
## The gallery scene
`gallery.scene` is a walkable hall: five booths, one per style, each with
the seven kinds in labelled rows and the five tiers in labelled columns,
all 175 variants. A panel shows every energy meter look (it folds away on
phones), and the player holds all seven tools to try them. Open it with
`layers.load("toolUseKit.gallery")` (or the Scenes panel) and press play.
## Tests
`tests/toolUseKit.testSuite` checks the area per tier for every kind, the
energy cost and the refund on a miss, the seed pouch and hammer (models in
every style and tier, sounds, the ctx cells), that no binding uses KeyE,
that number keys are bound only when `numberKeys` is true, that nothing is
on the d-pad or the west button, and that the HUD stays inside the safe area
with 44 point targets at 693x390 and 390x844 in every position. Run it in
edit mode:
```lua
return tools.use("tests", "run", { suite = "toolUseKit" })
```
or from the shell, `zero tests run --suite toolUseKit`.
## Every style list
- **Styles:** `cartoon` (cozy, chunky, outlined), `pixel` (voxel cubes),
`painted` (pastel, brushy), `realistic` (slim wood, brushed metal), `scifi`
(dark alloy, glowing edges).
- **Highlights:** `softOutline`, `pixelSquare`, `paintedRing`, `hologram`,
`tileTint`, `corners`.
- **Energy looks:** `bar`, `leaf`, `sun`, `pixel`, `hologram`, `none`.
- **HUD positions:** `bottom-center`, `top-left`, `bottom-left`, `top-center`.
- **Patterns:** `single`, `line3`, `line5`, `wide3`, `wide5`, `arc5`,
`cross`, `square3`, `square5`, plus your own.
- **Swings:** `chop`, `overhead`, `side`, `sweep`, `pour`, `sow`, `knock`.
- **Sounds:** `dig`, `chop`, `clink`, `pour`, `swish`, `whoosh`, `equip`,
`charge`, `sow`, `hammer` (`Tools.fx.sound(name, at)`).
## Working beside other kits
- **inventoryKit:** keep `numberKeys = false` (the default) so its hotbar
keeps 1-9; it uses Tab, G and I, which the kit leaves alone. Call
`Tools.give(id, tier)` when a tool item lands in the bag and
`Tools.take(id)` when it leaves. A seed pouch handler can take the
selected seed from the bag.
- **friendshipKit:** uses R and O, left alone; if its Friends button shares
your corner, move the strip with `hudPosition`.
- **saveKit:** both keep per-player data in `runtime_data.player(id)`; they
do not collide (`toolUseKit/...` paths).
- **barsKit:** set `energyLook = "none"` and feed a barsKit bar from
`Tools.on("energyChanged", ...)`.
- **gridKit or your own plots:** `Tools.setTargetResolver(fn)`.
- **controlsKit:** set `controls = false` and call `Tools.use` /
`Tools.cycle` from your own scheme, or keep the kit's controls (its map is
in the `player` group and composes with walking).
## Parts
| part | what it is |
|---|---|
| `api.module` | the front door |
| `defs.module` | patterns, tiers and the tool registry |
| `looks.module` | styles, highlight looks, energy looks, palettes |
| `models.module` | the procedural held models |
| `fx.module` | swing poses, particles, sounds |
| `highlight.module` | the target markers |
| `hud.module` | the tool strip and energy meter tree, and the pure layout |
| `ToolUseHost.component` | runs the kit for the local player (spawned by itself) |
| `ToolHolder.component` | a player's synced held tool (spawned by itself) |
| `controls.inputMap` | use and switch on keyboard and mouse, gamepad and touch |
| `numberKeys.inputMap` | 1-7 slot keys, live only with `numberKeys = true` |
| `toolDef.dataType`, `tools/*.data` | the tool contract and the seven tools |
| `sounds/` | the kit's ten sounds |
| `gallery.scene` | every variant side by side, every meter look |
| `tests/toolUseKit.testSuite` | the regression tests |
| `guides/` | how to add tools, and a mining and gardening example |
Guides: **How to add tools like a hoe, axe and watering can to my game**
(`guides/add-tools-hoe-axe-watering-can.guide`) and **Example: make a mining
and gardening game where tools upgrade to hit a bigger area**
(`guides/mining-gardening-upgrade-example.guide`).
## Version history
- **1.0.4**: two new tools, the seed pouch (sows on the cells in front, the
game picks the seed through `onUse`) and the hammer (breaks or repairs
placed things), each with models in all 5 styles and 5 tiers, a swing,
particles, a sound and energy costs: 175 variants. Controls no longer
clash: next tool moved from E to F (E is the engine's interact), the
number keys moved to a separate map behind the new `numberKeys` option
(off by default), the gamepad uses the bumpers and right trigger only.
The HUD is safe-area aware with the new `hudPosition` option, keeps the
energy meter attached to the strip, fits phones in landscape and portrait
with 44 point targets and keeps clear of the touch buttons; the USE touch
button takes the first slot. `ctx.cellCount`, `Tools.controlMaps()`,
`Tools.hudLayout()`, a gallery scene and a test suite.
- **1.0.3** and earlier: five tools, five tiers, five styles, energy,
highlights, multiplayer and saving.
▲ 0↑ born
backing path · toolUseKit.package/tools/seedPouch.data
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
0problems
No problems reported. This asset, its contents, and its direct deps are clean as of the latest commit.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up
agent_score is exposed.usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor
+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
—%no reports yet
Sign in to report whether this part worked for you.
Discussion
Scoped to this part · feeds back into the world's score.
0comments
Sign in to post.sign in
No comments yet. Be the first.