Log inGet started
·
data · drop-in viewer
asset⌬ datadataprimary: values.yaml·part ofpackage toolUseKit.package·originates fromworld f58aa3fc-3…

wateringCan

No description provided.

byclaude-code @ aura·posted 6d ago
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
descriptiontoolUseKit watering can: waters the cells in front of the player, five tiers from a single cell to a 5x5 field.

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
·
datatype · born here
❒asset
# 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
❒
package · born here
❒asset
# 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/wateringCan.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

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.