# inventoryKit
Items as data, a personal bag/hotbar/equipment inventory for every player, gear that shows on the character, loot tables and six inventory screens in three looks: one install, multiplayer-correct, saved per player. Two guides ship inside the package: a how-to for every part of the kit, and a worked example that builds a dungeon loot run from an empty world.
This README describes **inventoryKit 1.0.27**.
## Using inventoryKit with other kits: one bag per world
craftingKit, economyKit, questKit and arpgKit are built on inventoryKit, and each one **brings the inventoryKit version it was made with**. Every copy keeps its own bags, so two copies in one world means a shop, a recipe or a quest reads a bag the player never sees (a shop lists 0 of everything, a crafted item vanishes). Today the kits bring:
| kit | brings inventoryKit |
|---|---|
| questKit 1.0.23 | 1.0.27 (this version) |
| economyKit 1.2.12 | 1.0.27 (this version) |
| arpgKit 1.0.19 | 1.0.27 (this version) |
| craftingKit 1.0.4 | 1.0.7 (not moved yet) |
| inventoryKit on its own | 1.0.27 (this version) |
questKit, economyKit and arpgKit are published on this same inventoryKit (and on the same saveKit 1.3.13, pickupsKit 2.3.11, menusKit 1.3.19, controlsKit 1.3.2, SecondWind 1.4.7 and Lifeline 1.0.4), so one world can install all three and still holds one bag. interactKit and dialogueKit bring no inventoryKit, so they go with any of these.
**What to install:**
1. **You want a shop, quests or an action RPG:** install those kits (questKit, economyKit, arpgKit, together if you like) and let them bring inventoryKit. Do not install an older inventoryKit yourself as well.
2. **You want crafting:** craftingKit 1.0.4 still brings inventoryKit 1.0.7, so use it on its own until it is published on 1.0.26.
3. **You want only the inventory** (with interactKit or dialogueKit if you like): install the newest **inventoryKit** on its own.
**The check, after every install:** in the engine's shell,
```
find /zero/source -type d -name inventoryKit.package
```
must print **exactly one line**. Two or more lines means two bags: remove the copy you installed yourself (`zero zeromind uninstall --path /zero/source/inventoryKit.package`), or the extra kit. With inventoryKit 1.0.14 or later in the world, `require("~inventoryKit.inventory").copiesAdvice()` says the same in plain words (which versions, which kits brought them, what to do), and the first Play in a world with more than one copy prints that advice in the log.
## Install
Search for **inventoryKit** in the editor's ZeroMind panel and install it, or from the engine's shell:
```
zero zeromind installAsset --guid e5580df4-1900-4b90-a890-3f5a30501f2a
```
It lands at `/source/inventoryKit.package` and brings pickupsKit and saveKit along (allow under a minute; installs with several dependencies are slow, #21420). Then use it as below; there is nothing to place in a scene. Code reaches the kit as `require("inventoryKit.inventory")` when it sits at the top of your world, or as `require("~inventoryKit.inventory")` wherever it is installed (also under `deps/`, when another kit such as craftingKit, economyKit or questKit brought it).
Going to use craftingKit, economyKit or questKit too? Read *Using inventoryKit with other kits* above first: install that kit instead of this one, and check for one copy.
## First example
Paste this into a brand-new world's scene entrypoint (`scenes/main.scene/entrypoint.luau`) and press Play:
```luau
local Inventory = require("inventoryKit.inventory")
function onLoad()
-- every peer: the screen style, the look, and what a new player starts with
Inventory.setup({ screen = "rpgGrid", look = "fantasy",
startItems = { { "sword", 1 }, { "dagger", 1 }, { "staff", 1 }, { "amulet", 1 }, { "healthPotion", 3 } } })
end
function onHostLoad()
-- once, on the host: shared things in the world
Inventory.spawnItem("helmet", 1, { 0, 0, 4 }) -- walk over it to pick it up
Inventory.spawnChest({ 3, 0, 6 }, "commonChest") -- walk up and press E to roll the table
end
```
You start with one item of every rarity but common (a rare sword, an uncommon dagger, an epic staff, a legendary amulet) and three potions, so the first time you open the bag every rarity frame shows. Tab or I opens the inventory (on a phone, the BAG button on the hotbar). Drag items between slots with the mouse or a finger, drag one out of the window to drop it, double-click (or tap Use) to drink or equip, and 1-8 / F pick and use hotbar slots.
## Guides
Two guides ship in the package, in `inventoryKit.package/guides/`, and come with every install. Open one in the editor's **Docs** panel (search its name, or what you want to do, such as "equip a sword in the player's hand"), or in the engine shell with `zero guides read <name>`. To read one before installing: `zm show @e5580df4-1900-4b90-a890-3f5a30501f2a:inventoryKit.package/guides/<name>.guide/guide.md`.
- **[How to make an inventory system with loot and equipment](how-to-make-an-inventory-system-with-loot-and-equipment)** (`how-to-make-an-inventory-system-with-loot-and-equipment`): what the kit is and how its parts fit together, defining your own items, giving and taking items, the six screens and three looks and how a world swaps between them with one change, drag and drop, equipping into the hand or another attachment point, loot tables and rarity, dropping and picking up, and multiplayer (your own inventory, saved and back when you return, gear everyone sees).
- **[Example: a dungeon loot run from an empty world](example-dungeon-loot-run-open-chests-collect-loot-equip-the-best-sword)** (`example-dungeon-loot-run-open-chests-collect-loot-equip-the-best-sword`): a short dungeon built from installed kits only. interactKit's chests and doors, a key that opens the iron door, weighted loot tables, the best sword found going into the character's hand, and an economyKit shopkeeper who buys the rest.
Related guides in other kits, by name once the kit is installed, or with `zm show` from any world: interactKit's *How to make doors, switches, locks and chests* (`zm show @9502f89c-a43c-4039-bc41-5caf5fb81521:guide.md`) and *Example: an escape room puzzle with switches and locked doors* (`zm show @b261312c-d5b9-4b9c-a76e-72850a294a5c:guide.md`), and questKit's *How to add quests to my game* (`zm show @915ee882-7aef-4388-803f-cb96a4160fbe:guide.md`) and *Example: a quest chain from an empty world* (`zm show @f06a2f9d-29a2-41e5-b242-9e21043e5db1:guide.md`). craftingKit (`db435e42-06aa-407e-8537-106d444d0a5c`) and dialogueKit (`c4f39ad3-2a14-4f7d-b409-aed7fdbe8e77`) have no guides yet; their READMEs are the reference.
## What is in it
`Inventory.catalogue()` returns all of this as data: `{ screens, looks, frames, items, lootTables, slots, rarities, kinds, events, version }`.
- **Screen styles** (`Inventory.setScreen(id)`): `rpgGrid` (classic RPG grid), `survivalList` (survival list with weight), `hotbar` (hotbar on its own), `radial` (radial wheel), `paperDoll` (paper-doll equipment), `minimal`. Each has a phone layout, and every screen fits phones held either way, clear of the on-screen touch buttons. `Inventory.setCompare(true)` shows all six side by side with the live inventory.
- **Looks** (`Inventory.setLook(id)`): `fantasy` (painted icons, leather and gilt), `scifi` (line-art icons, glass and neon), `cartoon` (the painted icons on chunky, bright panels with thick ink outlines, star badges on rare and better, sparkles on legendary).
- **Rarity frames**: `common`, `uncommon`, `rare`, `epic`, `legendary` in each look (15 frames, `fantasy.epic`, `cartoon.legendary` …). Each slot also glows softly in its item's rarity colour, so the rarity reads at a glance even at phone size.
- **Equipment slots**: `head`, `chest`, `legs`, `feet`, `hands`, `mainHand`, `offHand`, `accessory`. A bag (24 slots by default) and a hotbar (8).
- **30 starter items**, each with a fantasy icon, a sci-fi icon and a 3D model:
- weapons: `sword`, `axe`, `bow`, `dagger`, `staff`, `spear`
- armour: `helmet`, `chestplate`, `greaves`, `boots`, `gloves`, `shield`, `ring`, `amulet`
- consumables: `healthPotion` (heals 40), `manaPotion`, `bread` (heals 15), `bandage` (heals 25), `bomb` (blast), `scroll` (speed for 10 s)
- materials: `wood`, `ironOre`, `gem`, `cloth`, `herb`, plus `arrows` and `goldCoins`
- keys: `ironKey`, `keycard` (sci-fi), `bossKey`
- **5 sample loot tables**: `commonChest`, `goblinDrop`, `dragonBoss`, `herbPatch`, `mysteryBox`.
- **Components**: `WorldItem` (an item on the ground), `LootChest`, `Mannequin` (dress a non-player humanoid), `ItemRack` (a labelled display grid). The kit places `PlayerInventory` and `InventoryHost` by itself.
## Add an item
Add one data asset anywhere in your world, bound to the `inventoryKit.inventoryItem` contract; the kit finds it by itself. `myGame/items/fireSword.data/values.yaml`:
```yaml
contract: inventoryKit.inventoryItem
values:
id: fireSword
name: "Flame Blade"
kind: weapon # weapon armour consumable material key ammo currency misc
slot: mainHand # empty for items that are not worn
maxStack: 1
rarity: epic
iconFantasy: myGame.icons.fireSword
iconScifi: myGame.icons.fireSword
model: myGame.models.fireSword
size: 1.0 # longest side in metres; the kit scales the model to it
useEffect: "" # heal mana speed bomb event
```
Worn gear is placed by a table per equipment slot, tuned for the engine's standard humanoid rig; on another rig, adjust an item's `hold` (position, rotation, scale).
From code instead: `Inventory.defineItem({ id = "fireSword", name = "Flame Blade", kind = "weapon", slot = "mainHand", rarity = "epic" })`. The contract's README lists every field (`useAmount`, `useDuration`, `hold` for fine placement, `wearOn` for another socket, `tags`).
## Add a loot table
A data asset bound to `inventoryKit.lootTable`:
```yaml
contract: inventoryKit.lootTable
values:
id: spiderNest
name: "Spider Nest"
kind: enemy
rolls: 1 # picks per roll (rollsMax for a range)
nothingWeight: 40 # chance of nothing
entries:
- { item: cloth, weight: 40, min: 1, max: 3 }
- { item: gem, weight: 5 }
- { item: ironKey, guaranteed: true }
- { table: goblinDrop, weight: 10, min: 1, max: 2 } # rolls another table
```
An entry with `table:` instead of `item:` rolls that table (`min`..`max` times) and adds what it gives; it can be weighted or `guaranteed` like any entry, and tables nest up to 6 deep. A table that would roll itself again further down is skipped (`roll` returns the reason as its second value). The sample dragon boss always rolls the common chest once on top of its own picks.
Then `Inventory.roll("spiderNest")` returns `{ { id, count } }`, `Inventory.spawnLoot("spiderNest", pos)` drops it in the world, and `Inventory.spawnChest(pos, "spiderNest")` makes a chest for it. Chance per pick = weight / total weight.
Measured, 1000 rolls each (seed 7), expected → got:
| Table | Results |
|---|---|
| mysteryBox | healthPotion 20 → 20.7%, bread 20 → 21.3%, wood 20 → 16.7%, bow 12.5 → 13.0%, greaves 12.5 → 13.5%, helmet 5 → 3.1%, gem 5 → 5.6%, chestplate 2 → 2.5%, staff 2 → 2.7%, amulet 1 → 0.9% |
| commonChest (2-3 picks, 2503) | goldCoins 30 → 30.5%, healthPotion 20 → 20.4%, bread 15 → 14.3%, arrows 10 → 10.6%, bandage 10 → 9.8%, axe 5 → 4.6%, dagger 5 → 5.1%, bow 3 → 2.8%, sword 2 → 1.8% |
| goblinDrop | nothing 50 → 49.5%, goldCoins 25 → 25.2%, bread 10 → 10.9%, arrows 8 → 8.3%, dagger 4 → 3.9%, ironKey 3 → 2.2% |
| dragonBoss (3 picks, 3000; bossKey, gold and one commonChest roll always) | helmet 20 → 17.9%, shield 20 → 21.1%, sword 20 → 20.3%, chestplate 15 → 15.7%, staff 12 → 12.0%, ring 8 → 7.9%, amulet 5 → 5.1% |
| herbPatch | herb 70 → 69.4%, wood 20 → 18.9%, gem 10 → 11.7% |
Re-measure any table with `require("inventoryKit.loot").measure(id, 1000, seed)`.
## Add a screen style
Every style is a function in `inventoryKit.screens` (`STYLE.<name>(view) -> widget tree`) built from the same `slot()` widget, so it gets drag and drop, taps, tooltips and rarity frames for free. Copy `minimal` as a start, give it a new name, add it to `Screens.STYLES` and `Inventory.SCREENS`/`SCREEN_INFO`, and `Inventory.setScreen("yourStyle")` picks it.
## API
`Inventory.setup(opts)` (screen, look, bag, hotbar, save, saveKey, hud, openKeys, controls (false: its own keys and pad buttons stand down), startItems, dropDistance, pickupRadius, manaMax, saveKitHud) · `setScreen` · `setLook` · `catalogue` · `on(event, fn)` (change, add, remove, move, equip, unequip, use, drop, pickup, refused, open, screen, look, loot, ready, select, mana).
Local player: `give(id, n)` · `take` · `move(from, to)` · `split` · `equip` · `unequip` · `select` · `use(address)` · `drop(address, n)` · `state()` · `at(address)` · `count(id)` · `has` · `equipment(player?)` · `players()` · `isReady()`.
World: `spawnItem(id, n, pos)` · `spawnLoot(table, pos)` · `spawnChest(pos, table)` · `openChest` · `roll(table)`.
Screens: `setOpen` · `toggle` · `setCompare` · `toast` · `setInsets({ left, right, top, bottom })` (keep the kit's screens clear of your own UI) · `screenSpace()` (the free part of the screen, the touch buttons, the hotbar's top). Addresses: `"hotbar:3"`, `"bag:12"`, `"equip:head"`.
## Phones and the web build
The engine lays UI out on a canvas about 1280 points wide whatever the screen. On a screen held upright (a phone in portrait) every inventoryKit screen, the hotbar strip, messages and the side-by-side view are laid out for a 430-point phone and scaled up to fill it (`require("inventoryKit.screens").frame()` reports the size and scale, and a game's own UI can use it the same way). Each style has its own phone layout, and the side-by-side view shows them in one scrolling column. Slots are dragged with a finger: onto another slot, onto an equipment slot, or off the panel to drop the item into the world. An `ItemRack` lays itself out for each player's own screen: one grid of `portraitColumns` (5) on a phone held upright, so the whole rack fits the narrow view. Timers use the engine's wall clock (`getTime()`), so they run the same on desktop and in the browser.
On a touch screen the engine draws its own buttons (Jump, Interact, the "..." fan) along the right edge, and a touch that begins on one belongs to that button. The kit reads where they are (`Inventory.screenSpace()`) and keeps the hotbar, messages, the chest prompt and the side-by-side view to their left; the open inventory panel is shrunk to fit the free part of the screen, above the hotbar. A game reserves room for its own UI with `Inventory.setInsets({ left = 160 })`: the gallery keeps its style column that way.
Checked at 1170 x 2532 (a phone held upright) and 2532 x 1170 (held sideways) with the touch buttons showing: all six styles in the fantasy and sci-fi looks fit the screen with their headings visible, nothing overlaps the touch buttons, the hotbar or the gallery's column, and finger drags bag to bag, bag to the head slot, shield to head (refused), and off the panel (dropped) all do what they should.
## How multiplayer works
- Each player's inventory lives on a synced entity that player's own engine spawns and owns. Only the owner writes it, so nobody else can move things in it.
- Every change goes through pure rules first (`inventoryKit.rules`, built on the engine's slot inventory). An impossible move (a helmet into a hand, more than a stack holds, an item you don't have) is refused with a reason and changes nothing anywhere.
- Worn gear goes through the engine's slot system: the character gets an `Assembly`, and each equipped item fills that character's own `Humanoid` sockets (`righthand`, `head`, `leftfoot` ...); every item model declares the sockets it fits in its metadata. The character's owner fills the sockets, the fill is synced, every engine builds the same part, and each engine fits it (place, turn, size by the slot's wear table). A player's character is found through the scene's players registry, and only items that fit their slot are worn, whatever arrives. In edit mode (the training dummy's preview) and for any socket the slot system refuses, the kit seats the model itself.
- An inventory travels between engines with its slots keyed by number as text, so slots after an empty one arrive too.
- Items on the ground carry pickupsKit's `Pickup`, which decides the grab with one winner however many touch it; inventoryKit listens for the collect and adds the item to the collector's own inventory. This works with pickupsKit installed under `deps/`, as an install of inventoryKit puts it. Should pickupsKit ever be unable to recognise players, the engine that owns the item decides the grab itself the same way: it marks the item taken first, then tells the winner's engine. Chests are rolled by their owner, once per opening.
- A dropped item belongs to the player who dropped it and leaves the world with them. Shared things the host placed leave with the host too; the gallery's next host puts back whatever is missing within two seconds (see its `keepShared`).
- Each player's inventory, hotbar and equipment are saved in their saveKit profile and come back when they rejoin. Profiles are per account: two engines signed in to the same account (two tabs, or the editor and a browser) share one profile, whichever saves last wins, and the two collide as one player (#14448). Test two players with two accounts, or use `Inventory.setup({ save = false })` on one of them.
- A respawning world item comes back only once nobody stands on it, so standing still never farms it.
- Shared things (world items, chests) are spawned once by the host from `onHostLoad`, at world positions. Keep synced entities at the root of the scene: a synced entity under a plain scene group does not keep that parent on other engines.
Tested with two players (the desktop editor and the web build in Chrome, in one room): one player walked over a sword, dragged it from the bag to the hotbar and onto the main hand, and the other engine drew it in that character's right hand; the other engine's direct write into that player's inventory (sword off, amulet on) changed nothing; a shield dragged onto the head slot was refused with "a shield goes in offHand, not head" and nothing moved; after leaving and rejoining twice, hotbar, bag and equipment were all back.
## What it installs
- **inventoryKit 1.0.27**: modules, components, 2 data contracts, 30 items, 5 tables, 60 icons, 30 item models plus chest, stand and plinth models, 2 materials, 2 input maps, 2 guides, a test suite (`inventoryKitTests`).
- **pickupsKit 2.3.11** (one-winner grabs; health through SecondWind for potions, food and bandages; speed power-ups for scrolls) and **saveKit 1.3.13** (per-player saves), with what they bring: SecondWind, Lifeline, MatchFlow, juiceKit, menusKit and controlsKit. inventoryKit turns saveKit's XP bar off unless you pass `saveKitHud = true`.
- Engine parts it builds on: `@builtin::modules.extras.inventory` (slot rules), UI drag and drop, the slot system (`Assembly`, `Part` fits, `Humanoid` socket roles) for worn gear, the touch controls' layout, and pickupsKit's `Pickup` for grabs.
## Tests
`tools.use("tests", "run", "inventoryKitTests")` in edit mode (shell: `zero tests run inventoryKitTests`) runs **10 tests**: impossible moves are refused and change nothing; stacks fill, split and merge; equipping uses the item's own slot and the save form brings an inventory back unchanged; the form an inventory travels between engines in keeps slots after an empty one; 1000 rolls of the mystery box land within 5 points of every weight; nested loot tables roll their sub-tables and skip loops; the catalogue lists 6 screens, 3 looks, 15 rarity frames, the 5 sample tables and the 30 starter items with both icons and a model that can be spawned; every screen style builds in all three looks at desktop and phone sizes; the kit finds its own copy among every copy of inventoryKit in the world and says whether the world holds one bag; and both guides ship, link each other and are named in this README. The suite needs no player and no waits.
For 1.0.16 (descriptions only) the suite ran 10 of 10 twice in a row in this world, and twice in a new world holding only inventoryKit installed from ZeroMind.
For 1.0.15 (descriptions only) the suite ran 10 of 10 twice in a row in this world.
For 1.0.14 the suite ran 10 of 10 twice in a row in this world and twice in a new world holding only inventoryKit installed from ZeroMind, where the first example above was played as written. The copy check was run in a new world holding inventoryKit, craftingKit, economyKit and questKit: it found the four copies (1.0.13, 1.0.10, 1.0.9 and 1.0.7) and named the three kits.
For 1.0.13 (guides and README only) the suite ran 9 of 9 twice in a row in this world. The versions above were checked by installing economyKit 1.2.4, craftingKit 1.0.4 and questKit together in a new world: `deps/` held three copies of inventoryKit (1.0.10, 1.0.7 and 1.0.9), and `require("~craftingKit.crafting").inventory() == require("~economyKit.economy").inventory()` was false.
For 1.0.12 the suite ran 9 of 9 twice in a row in this world (Pack Rat) and twice in a new world holding only inventoryKit installed from ZeroMind, where the first example above was played as written. The dungeon example guide was followed word for word in another new world with interactKit and economyKit installed (economyKit brought inventoryKit), alone, through to a sale and back after Stop and Play. Phone layouts were checked on the desktop engine at phone sizes (a browser engine cannot be started from an agent's side, #20946).
## Known limits
Each limit here is an open public issue you can look up.
- **Two engines on one account collide as one player (#14448)**, and share one saved inventory. Test two players with two accounts.
- **The web build's frame rate in busy scenes (#20750)**, such as the showroom with several players.
- **Installing takes under a minute (#21420)** because of the dependencies (42 seconds in a new world).
- **Attaching things yourself to a second character on the same rig** with `Humanoid:attach` seats them on the first character's bones (#21244). inventoryKit's worn gear is not affected: it fills each character's own sockets through the slot system.
- **Your own generated item art:** there is no way yet to shrink a generated texture's stored source (#21247), so a freshly generated model can add around 13 MB to a world. The kit's own art was shrunk by hand (its NOTES say how).
- **Right after a new version is pushed,** ZeroMind's search can show the previous version's description for a while (#19258).
- **Links from these guides into another package's guide** can take a few tries in the Docs panel (#22513); the `zm show` lines given beside each one always work.
## Changes
- **1.0.27**: built on saveKit 1.3.13 and menusKit 1.3.19, whose files all name one controlsKit release, so installing inventoryKit lands exactly one controlsKit, one menusKit and one saveKit (1.0.26 still landed three controlsKit copies through menusKit 1.3.17). No behaviour changed.
- **1.0.26**: built on saveKit 1.3.12, menusKit 1.3.17 and controlsKit 1.3.2, the first releases of those kits that install as one copy each (controlsKit 1.3.1 still pointed some of its own files at 1.3.0, so 1.0.25 landed two controlsKit releases). InventoryHost names its own input maps relatively (`asset.resolve("~.inventoryMap", "inputMap")`). No behaviour changed.
- **1.0.25**: built on saveKit 1.3.11 and menusKit 1.3.16 (the newest releases), the same releases questKit, economyKit and arpgKit are now published on, so one world can install all of them with one inventoryKit, one saveKit and one menusKit. The kit table above says which kit brings which inventoryKit. No inventoryKit code changed; the world also moved to the current engine library.
- **1.0.24**: An inventory left over from an earlier play session no longer shadows the live one. Its entity was despawned without unregistering, and `state`, `count`, `at` and `equipment` could answer from it instead of the player's live inventory, so a farm or shop that checks what a player holds refunded purchases and failed harvests with 'entity was despawned'. Each lookup now skips and forgets any inventory whose entity no longer exists. Built on pickupsKit 2.3.11 and saveKit 1.3.10 with their current SecondWind, juiceKit, MatchFlow, Lifeline, menusKit and controlsKit, and the current engine library, so a world that installs inventoryKit beside economyKit or cropsKit holds one release of each. Suite: 14 of 14.
- **1.0.23**: A finger's tap on a slot now always works the slot. On a touch screen the engine delivers a tap to a `button` widget but not to a slot box with an `onClick`, so in an open bag (and on the hotbar strip) taps on items never picked them up. The inventory host now reads the touch itself: a short tap that lifts over a slot picks the item, places it or selects the hotbar slot, exactly as a click does, and a tap the engine did deliver is not worked twice. Checked at 844 x 390 and density 3 with simulated touches: tap the chestplate in the hotbar, tap the chest slot, and it is equipped.
- **1.0.22**: The `controls` test no longer assumes the setting is on: it switches it off and on and puts back the value the world chose, so the suite passes in a game that runs with `controls = false`.
- **1.0.21**: On a touch screen a slot answers a tap and nothing else (no double tap, hover tooltip or drop), the shape every widget that takes a finger reliably has: in 1.0.20 a finger still could not pick up an item, only place one. Checked at phone size and density: tap an item, tap the hand slot, and it is equipped.
- **1.0.20**: Phones. A finger now picks and places items: on a touch screen (`Inventory.isTouch()`) slots carry no drag, because a finger on a draggable widget starts a drag and never makes the tap the hint asks for (tap an item, tap a slot). And the open panel takes whichever placement shows it bigger: the whole width, scaled to stay above the touch buttons at the bottom, or the column beside them; before, a tall panel that reached a bottom-corner button was always squeezed into the column. One new test (14).
- **1.0.19**: The open bag uses the phone's whole width. Touch buttons in the top corner (a pause or bag button) now push the panel down below them instead of narrowing it across its whole height; only buttons beside or below the panel narrow or stop it. On a phone held upright with a corner pause button the bag went from a 226-point panel with 24-point slots to the full width with 40-point slots. One new test (13).
- **1.0.18**: `controls` setting. `Inventory.setup({ controls = false })` stands the kit's own keys and pad buttons down (Tab and I, the 1-8 hotbar keys, the pad's Y, X, B, Select and shoulders), so a game that drives the bag through its own control scheme (an action RPG whose X is attack and whose shoulders are skills) has no second action on its buttons; `true`, the default, brings them back while the game runs. One new test (12).
- **1.0.17**: Item resolvers for rolled items. `Inventory.addItemResolver(name, fn)` answers item ids that no data asset or `defineItem` made: `fn(id)` returns the same fields as `defineItem`, and every peer builds the same item from the id the first time it sees it (in a bag, on the ground, in a hand). A kit that rolls random stats (gearKit) encodes the roll in the id (ids are letters, digits, `_` and `-`), so rolled gear travels between players, saves and loads with no extra sync. `removeItemResolver(name)` takes one off. New test: a resolver answers an unknown id and a second resolver under the same name replaces it.
- **1.0.16**: Descriptions only. The package's store description is rewritten to say plainly what the kit gives a creator, how to install it (with the install command) and what to do with craftingKit, economyKit or questKit. Nothing changed in how the kit plays.
- **1.0.15**: Descriptions only. The short descriptions the package and its looks and screens modules carry for ZeroMind still described two looks and ten frames; they now describe the three looks and fifteen frames of 1.0.14. Nothing changed in how the kit plays.
- **1.0.14**: A third look, `cartoon` (the painted icons on chunky, bright panels with thick ink outlines; star badges on rare and better, sparkles on legendary), behind the same `look` setting, so a world still swaps with one change; 15 rarity frames. Polish on every screen in every look: each filled slot glows softly in its item's rarity colour so the rarity reads at a glance at phone size, stack counts sit on a dark pill so they read over any icon, and the slot under the pointer (hovering, or dragging over it) lights up. New `Inventory.copies()` and `Inventory.copiesAdvice()` list every copy of inventoryKit in a world and say in plain words whether it holds one bag, and the first Play in a world with several copies prints that advice in the log. The README opens with *Using inventoryKit with other kits*: which inventoryKit each kit brings, what to install, and the one-line check. The showroom's switcher has the Cartoon look. New test: the copy check.
- **1.0.13**: Guides and README only. craftingKit 1.0.4, questKit and economyKit 1.2.4 each bring a different inventoryKit (1.0.7, 1.0.9 and 1.0.10), so any two of them in one world keep two bags. The dungeon example's *Going further* told readers to add craftingKit (and questKit) to a world that already has economyKit and said the crafted sword lands in the same bag; it does not, it lands in a second copy's bag. The example now says not to combine them yet and how to tell, and the how-to guide (*Working with the other kits*, *One copy*) and this README name the versions each kit brings, the `find` check and a one-line Luau check. Nothing changed in code.
- **1.0.12**: Guides and README only. The dungeon example now installs interactKit and economyKit and lets economyKit bring inventoryKit: installing inventoryKit 1.0.11 yourself next to economyKit 1.2.4 (made with 1.0.10) left a second copy of inventoryKit, so the shopkeeper could not see the bag. The how-to guide and this README say why a world needs exactly one copy and how to check. Nothing changed in how the kit plays.
- **1.0.11**: Two guides ship in the package: *How to make an inventory system with loot and equipment* and *Example: a dungeon loot run from an empty world*. The README gains a Guides section and a Tests section, names the kit's current dependencies (pickupsKit 2.3.8, saveKit 1.3.2), and its Known limits cite only open issues: pickupsKit now recognises players when installed under `deps/` and saveKit with its HUD off no longer leaves an empty screen over the game, so both are gone from the list. Built on @builtin 278f02f. New test: both guides ship, link each other and are named here. Nothing changed in how the kit plays.
- **1.0.10**: built on pickupsKit 2.3.8 and saveKit 1.3.2, so a world that gets inventoryKit as a dependency (under `deps/`) loads it: pickupsKit 2.3.7 named its own modules through `@root::pickupsKit`, which fails anywhere but a world's source root.
- **1.0.9**: The hotbar strip on a phone held upright wraps its slots into two rows (or more) when one row would make them smaller than a fingertip beside the on-screen touch buttons, instead of shrinking them; it lays itself out for the width it is really given.
- **1.0.8**: Items added or changed while the world runs are picked up. The item list was read once per session, so item data written later (a package with its own items installed into an open world, an item edited in the editor, or a change from another participant) stayed invisible, with blank icons, until the engine restarted. Writing any item data asset now marks the list stale and the next read loads it again. Nothing else changed.
- **1.0.7**: Performance: worn gear no longer asks the engine's slot system for every socket several times a second. Each query walks the whole skeleton (about 2.4 ms), so a player in a full set cost about 3 ms a frame on every engine; a fitted part is now remembered and the slot system is asked again only when that part is rebuilt or the equipment changes (0.07 ms a frame). Nothing else changed.
- **1.0.6**: Description and README only, no code changes: the library description now says what the kit gives you and how to install it, the README has an Install section, phone wording covers both orientations, and the pickupsKit limit matches what a fresh install does (its Pickup works there; the kit's own grab stays as the fallback).
- **1.0.5**: Phones in both orientations: the kit reads the engine's touch buttons and keeps every screen clear of them; the open panel shrinks to fit the free part of the screen above the hotbar (in landscape its top was cut off), the hotbar, messages and prompt centre in the free span, and a game can reserve room with `Inventory.setInsets` (new, with `Inventory.screenSpace`). Worn gear now goes through the engine's slot system (`Assembly` filling `Humanoid` sockets; item models declare the sockets they fit; gloves fill the forearms and the amulet the neck so a weapon and gloves never compete). Items on the ground use pickupsKit's `Pickup` wherever pickupsKit recognises players, with the kit's own grab as the fallback; a respawning item still waits until nobody stands on it. Loot table entries can roll another table (`table:`), nested up to 6 deep with loops skipped; the dragon boss sample rolls the common chest. Player names no longer go through pickupsKit. Known limits now each cite a filed report. New test: nested loot tables.
- **1.0.4**: Phones and the web. On a screen held upright every screen, the hotbar and the side-by-side view are laid out for a phone and scaled up (they were desktop layouts shrunk to a third); each style shows its own phone layout in the side-by-side view, drawn lighter there so six at once stay quick. Dragging with a finger onto an empty equipment slot now equips (the release over the slot's silhouette reached nothing). The hotbar strip, messages and the chest prompt are centred again (anchored areas ignore `pivot`). `ItemRack` gains a portrait layout (`portraitColumns`, `portraitSpacingX`, `portraitSpacingY`, `portraitBaseHeight`) and sizes each name label to its column so long names never run into their neighbours. Timers run on `getTime()`, the same clock in the browser as on desktop. New `Screens.frame()`.
- **1.0.3**: Fixed four things found by playing with two players. Other players' gear now shows: every engine finds a player's character through the players registry (the synced character reference arrived empty on other engines), which also lets the host hand world items to joining players. A player's bag now reaches other players complete: the inventory travels with its slots keyed by text, because a numbered list with an empty slot in it lost everything after the gap. An inventory left behind by a player who has gone is tidied up again, gear included (it raised an error every frame). A respawning item waits until nobody stands on it, so standing still no longer farms it. New test: the wire form keeps slots after a gap.
- **1.0.2**: Fixed: in a fresh world, walking over an item picked nothing up. pickupsKit's Pickup, installed under `deps/`, cannot tell a player from anything else there (its `PlayerAvatar` check names a component the installing world does not hold) and logs an error every frame. Items on the ground are now handed out by inventoryKit itself, owner-decides with one winner, and inventoryKit adds no pickupsKit component any more.
- **1.0.1**: Fixed: 1.0.0 could not be installed. Its spear model was published without its mesh, and the engine refuses an install with an incomplete asset. The spear is complete again, and the test suite now checks that every item's model can be spawned, not just found by name.
- **1.0.0**: First release.
# ArpgCamera
The action-RPG camera behaviour (Diablo / Torchlight style). Set it as a `Camera`'s `behavior`; it follows `Camera.follow` (bound per player at spawn) or `target`. It looks down at `pitch` degrees from compass heading `yaw`, follows with a critically damped lag (`follow`), leans `lookAhead` metres toward where the hero moves, and zooms between `minDistance` and `maxDistance` through `zoom` (0..1), which `ArpgHero` writes from the mouse wheel, the gamepad's shoulder triggers or a two-finger pinch. Needs no sibling components.
# ArpgGame
One dungeon run, the same for every player. Put it on a SYNCED entity (`Arpg.place` does). Every peer builds the dungeon from `seed` and `theme` with procLevelKit; the room host spawns every room's monsters (aiKit brains with a leash to their room, SecondWind health), rolls their loot on death (gearStatsKit gear, potions and gold as inventoryKit items anyone sees and the first to touch gets), marks rooms cleared, opens the exit once all are clear, ends the run when a hero reaches it, and starts new runs (new seed, optionally one depth deeper). Settings: seed, theme, rooms, heroClass, hud, difficulty, enemyMix, boss, newSeedEachRun, autoStart. Read-only synced state: runId, depth, phase, cleared, alive, exitOpen, kills, startedAt, endedAt.
# ArpgHero
The player's hero. Goes on the PlayerPrototype's body beside the CharacterController (`Arpg.place` puts it there), so every joining player gets one; only the body's owner runs it. Click the ground to walk a real path there (hold to keep following the cursor), click a monster to walk up and attack it, push WASD or a stick to run camera-relative, tap on a phone. Attacks and four skills are the class's abilitiesKit abilities, aimed at the cursor with a mouse and at the nearest monster otherwise. Applies the class (stats, loadout, speed), gives starting gear, binds gearStatsKit so equipped gear changes the stats, tracks gold and XP, and walks into the open exit. Fields: heroClass, level, xp, gold (synced), assist, clickMarker.
# ArpgHud
The local player's screens. On a plain entity (`Arpg.place` adds one). Draws the skill bar (abilitiesKit's AbilityBar in the layout's shape and the theme's style), the room tracker (rooms cleared, monsters left, depth, gold), short messages, and the start screen with the class picker, the death screen (rise again / new dungeon) and the win screen (time, kills, gold, level, best gear; delve deeper / new dungeon). `layout` = classic, modern, minimal, mobile or auto (mobile on phones).
# arpgKit.abilities
Adds the ARPG's own attacks to abilitiesKit's catalogue so they cast, cool down and show on the ability bar like any other: `arpgCleave` (warrior arc), `arpgStab` (rogue), `arpgArrow` (archer), `arpgArcaneBolt` (mage), `arpgWarCry` and `arpgVolley`, with the `arpgCleave` and `arpgVolley` behaviours. `ensure()` is safe to call many times; `def(body, slot)` reads the ability in a loadout slot.
# arpgKit.api
The kit's front door: `local Arpg = require("arpgKit.api")`. The catalogue (`classes`, `enemies`, `themes`, `huds`, `lootTiers`, `catalogue()`, `define*`), `Arpg.place(opts)` that puts the whole game into a scene build (run, HUD, player prototype with hero and camera, spawn), and live calls on a running game (`setTheme`, `setHud`, `setClass`, `newRun`, `on`, `game`, `level`, `rooms`, `hero`).
# arpgKitTests
The arpgKit suite. It checks that the catalogue holds the kit's variety (4 classes, 7 enemy types, 6 themes, 4 HUD layouts, 4 loot tiers); that every class's attack and four skills exist in abilitiesKit; that every enemy type becomes an aiKit preset under every theme with its leash; that every theme's procLevelKit tile set, styleKit look blocks and HUD skin are installed; that seed 7 gives the same six rooms (start room first, exit in the last), the same monsters in every room and the boss in the last, build after build; that a kill's drops are the same for the same seed and are real gearStatsKit, potion or gold items; that deeper loot tiers drop gear more often and of better rarity; and that the version, README and both guides agree.
It runs in edit mode with no player. Movement, combat, pickup and multiplayer are play tests (see the world README's test notes).
Run it: `zero tests run arpgKitTests`.
Eight tests in all.
# arpgKit.bagPad
The open bag on a gamepad. With the bag open, the left stick or the d-pad moves a cursor over the bag and equipment slots (found by their on-screen rectangles, so it works in every inventoryKit screen layout), A equips gear from the bag, takes equipped gear off or uses a potion, and Y drops. The cursor is inventoryKit's picked slot, so the bag highlights it and gearStatsKit shows its compare card. Called by ArpgHero while the bag is open on a pad.
# arpgKit.classes
The hero classes a world picks from with one word: `warrior` (sword, cleave, charge, slam), `archer` (bow, arrows, poison darts, dash, volley), `mage` (staff, arcane bolt, fireball, frost nova, blink) and `rogue` (daggers, stab, dash, invisibility). Each is plain data: base stats for abilitiesKit, a basic attack and four skills, a starting weapon base for gearStatsKit, colour and attack range. `define(raw)` adds or replaces one (missing fields come from `base`). Read by ArpgHero and the HUD's class picker.
# arpgKit.combat
How the heroes fight. Every class weapon is a weaponsKit weapon held in the hero's hand and fired from code at the monster the player picked, so the room host checks each hit and every player sees the swing or the arrow in flight. The warrior runs on comboKit's `arpg` move set (Light I, II, III, Heavy Finisher, Charged Heavy, Whirlwind, Leap Strike) on comboKit's own 60 fps machine. gearStatsKit's stats scale every shot and apply life on hit, life steal, thorns, resistances, health regen and max mana.
Called by arpgKit's ArpgHero (equip, attach, update) and by the class abilities in `arpgKit.abilities` (fire, press).
# arpgKit.enemies
The monster types a dungeon fills its rooms with: grunt, brute (big and slow), archer, caster (shoots and heals), swarmling (packs of five), elite (champion) and the room boss. Each is an aiKit preset plus what the ARPG adds: XP, loot rolls and bonus, the leash radius after which it gives up and walks home, and a room-budget cost. `ensurePreset(id, theme)` registers the theme-tinted aiKit preset and returns its name; `define(raw)` adds your own type. Read by ArpgGame.
# arpgKit.feel
What a fight, a drop and a pickup feel like, on every player's machine. Nothing here is synced: each machine plays what it sees. Built on juiceKit (shake, hit-stop, flashes, sparks), soundstage (sounds and music) and the health, ability and inventory kits' own events.
- **Hits:** a sound on every hit on a monster (punch, a metal ring on a crit, a magic hit for spells), a critical burst on crits, and hit feedback for the skills that ship none of their own (force push, frost nova, nova). `arpgHitMedium` is the medium hit the warrior's Cleave and the mage's Arcane Bolt use.
- **The hero hit:** juiceKit's `hurt` (red vignette, a kick, a short freeze) and a thud. **Kills:** a death burst and a growl.
- **Loot:** a drop lands with a pop, dust and a sound by rarity; rare, epic and legendary gear stands under a pulsing beam of its rarity's colour, with its own light, until someone picks it up. A pickup plays a coin, potion or gear sound and a sparkle on the hero.
- **Music:** the look's soundstage music set (crypt: horror, ice and ruins: fantasy, sci-fi, cartoon, pixel: chiptune; a theme's `music` field overrides), `explore` between fights, `action` with rising intensity while fighting, `menu` on the start, death and win screens.
- juiceKit's look follows the dungeon look (a theme's `juiceLook` overrides).
`Feel.start()` once and `Feel.tick(dt)` every frame (ArpgCamera does both); `Feel.setView(view)` from the HUD; `Feel.stop()`.
# arpgKit.input
The hero's controls on every device through controlsKit's `arpg` scheme (move, moveTo, attack, skill1-4, potion, interact, inventory), plus what the scheme leaves to the game: the mouse pointer, the device used last, camera zoom from the wheel, and whether a press landed on the game's own UI. Used by ArpgHero.
# arpgKit.look
Each dungeon look's light, applied on every player's machine after a level is built. It darkens the ambient and moon light, makes the level's torches warm, bright and flickering, dims its room fills so light pools, sets the hero's carried light, and adds fog (so the void past the walls goes to the look's dark), bloom and a colour grade.
- `Look.apply(theme)`: light the built level in a theme's look (ArpgCamera calls it on `levelBuilt`).
- `Look.tick(dt)`: flicker the torches; call once a frame (ArpgCamera does).
- `Look.lightFor(theme)`: the settings a theme resolves to. A theme overrides any of them with a `light` table in `Arpg.defineTheme`: `ambient`, `ambientI`, `moon`, `moonI`, `fill`, `torch`, `torchI`, `torchR`, `flicker`, `hero`, `heroI`, `heroR`, `fog`, `fogDensity`, `bloom`, `bloomThreshold`, `contrast`, `saturation`, `brightness`.
- `Look.presets()`, `Look.clear()`.
# arpgKit.loot
What falls out of a monster. Four loot tiers that get better deeper in: `shallow` (rooms near the start), `middle`, `deep` and `vault` (the boss room). Each tier sets the chance of gold (and how much), of a potion (health or mana), and of a piece of gear, which gearStatsKit rolls from the tier's drop table (`tier1`..`tier4`) at a higher item level for deeper tiers. `tierForRoom(room, rooms)` picks the tier, `roll(tier, level, seed, rolls?, bonus?)` returns the kill's drops (same seed, same drops), `measure(tier, level, n?)` reports gold, potions and gear per kill and the rarity spread, and `define(raw)` adds a tier. ArpgGame calls it when a monster dies and drops the result as inventoryKit items.
# arpgKit.progress
Hero progression: kills give XP through saveKit (level, XP bar, level-up ribbon and per-player saving come from there) and every level adds real stats through abilitiesKit modifiers (+12 max health, +5% damage, +2 armour per level, `PER_LEVEL`). `attach(body, pub)` starts it for the local hero, `addXP(n)`, `view()`.
# arpgKit.rooms
Turns a built procLevelKit dungeon into the run's plan, identical on every peer for a seed: `plan(level)` orders the rooms by walking distance (start room first, exit room last), `spawns(level, rooms, seed, mix)` decides which monsters stand where in each room (a light pack in the start room, growing budgets, one elite from room 3, the boss with adds in the last room), `roomAt(level, rooms, pos)` says which room a point is in. Pure data; ArpgGame spawns from it.
# arpgKit.setup
One-time authoring helpers, run from the console in edit mode. Called by people setting up a world, never by the game.
- `require("arpgKit.setup").prepare()`: readies a new world's scene for arpgKit, whichever way the world started. A new world arrives either with Zero's empty-world template (a default player and its spawn point, ground, sun, ambient light, sky, two lamp posts and a crate; left in, the engine spawns players as that default player instead of the hero) or with no scene loaded at all. `prepare` makes the `main` scene when none is loaded (keeping a `build.luau` already written there, else writing the quick start's), deletes the template, and sets the scene to give each joining user a player, keeping arpgKit's own player and spawn. Run it after writing `build.luau`. Returns `{ created, cleared, players }`.
- `clearStarter()`: deletes only the template entities, through the engine's entityOps tool; the scene saves itself.
- `starterLeft()`: the template entities still in the scene, changing nothing.
- `foreignSpawns()`: every player spawn besides arpgKit's own `Start` (ArpgGame warns in play when there is one).
# arpgKit.skins
HUD skins (gothic, holo, cartoon, pixel: colours, panel edges, type, the abilitiesKit bar style and saveKit theme they map to) and the HUD layouts a world switches with one word: `classic` (Diablo globes), `modern` (hotbar), `minimal` (pills) and `mobile` (big buttons on an arc). `defineLayout(raw)` adds one. Read by ArpgHud.
# arpgKit.state
Shared state on this peer: the running ArpgGame's synced fields and host calls, the built level, its rooms and theme, the local hero, and the kit's event bus (`on(name, fn)` / `emit`: levelBuilt, theme, kill, loot, roomCleared, exitOpen, levelUp, heroDied, heroRevived, classChanged, hudChanged, gold, cast, castRefused). Used by every component of the kit; games reach it through `Arpg.on`.
# arpgKit.themes
The six dungeon looks a world switches between with one word: `crypt` (stone crypt), `ice` (ice cave), `ruins` (overgrown ruins), `scifi` (sci-fi station), `cartoon` and `pixel`. A theme picks procLevelKit's tile set, a styleKit look-block stack, the enemy palette and the skins of the HUD, inventory and gear cards; it never moves the layout. `define(raw)` adds one.
# gearStatsKit
Diablo style item stats for inventoryKit items, with stats that **really apply when equipped**. Roll a "Rare Blazing Sword of the Tempest" at item level 12, find **Doomwhisper** on floor 8, wear three pieces of the **Raiment of the Ashen Warlord** and watch the set bonus light up: every line on every card is an abilitiesKit modifier on your character the moment you put the item on, and gone the moment you take it off.
- **26 affixes** (prefixes and suffixes) over **25 stats**: damage, attack speed, crit chance and damage, fire / frost / lightning damage, area size, life on hit, life steal, max health, health regen, armour, thorns, three resistances, move speed, cooldown reduction, mana, resource regen, gold find, magic find, experience.
- **5 rarities** (common, uncommon, rare, epic, legendary), item levels 1 to 50, two naming themes (fantasy and sci-fi).
- **8 fixed-stat uniques** and **3 item sets** (10 pieces) with 2, 3 and 4 piece bonuses, all as data files.
- **4 loot tiers** that improve the deeper you go and drop uniques and set pieces from tier 2 up.
- **6 looks** (fantasy parchment, sci-fi holo, chunky pixel, bright cartoon, clean minimal, horror) and **6 card styles** (classic tooltip, side by side, compact line, hero card, diff only, minimal mobile), all in one list (`Gear.styles()`) and each switched with one call (`Gear.useStyle(id)`), live.
- A character stats panel (C) that flashes what changed, laid out for desktop and phones. Two guides and a 16-test suite inside.
This README describes **gearStatsKit 1.0.4**.
## Coming from gearKit
gearStatsKit is the successor of gearKit 1.0.1 and keeps its API: change `require("gearKit.api")` to `require("gearStatsKit.api")` and a game keeps working. Rolled ids (`gk-...`) are the same format and rebuild the same items. What differs:
- The modifier source on abilitiesKit characters, the item resolver name and the contracts are `gearStatsKit` (`gearStatsKit.gearAffix` and so on). A game's own `.data` files bound to `gearKit.gearAffix` must name `gearStatsKit.gearAffix`.
- `Gear.card` draws the current **card style** (default `classic`, the gearKit card). Pass `style` to pick one per call.
- `Gear.compare`, `Gear.bonusesOf` and the stats HUD now include unique items and **set bonuses**.
- `Gear.attackDamage` adds fire, frost and lightning damage to the hit.
- New: uniques (`gu-<id>` ids), sets, 12 more stats and affixes, the horror look, card styles, `Gear.setCardStyle`, `Gear.hitEffects`, `Gear.mitigate`, gold, magic find and experience helpers. Everything is listed under API.
- The test suite is `gearStatsKitTests`.
## Install
```
zero zeromind installAsset 2a0a3574-98ee-4fa3-b225-319b325392f6
```
or search ZeroMind for **gearStatsKit**. It brings **inventoryKit 1.0.27** (bags, equipment, items on the ground) and **abilitiesKit 1.1.5** (stats and modifiers; brings SecondWind, barsKit, juiceKit and controlsKit). Keep one copy of inventoryKit and SecondWind per world: `find /zero/source -name 'inventoryKit.package' -o -name 'SecondWind.package'` should print one line each. If an older install left copies under `deps/*/versions`, `zero zeromind removeUnusedDeps` clears them.
## Quick start
In a world with players, in the scene entrypoint (`scenes/main.scene/entrypoint.luau`):
```luau
local Inventory = require("inventoryKit.inventory")
local Gear = require("gearStatsKit.api")
function onLoad()
Inventory.setup({ screen = "rpgGrid", look = "fantasy" })
-- the compare card for gear on the ground, the stats panel on C, the local character bound
Gear.setup({ look = "fantasy", cardStyle = "classic", lookSwitcher = true, styleSwitcher = true })
Inventory.give(Gear.roll({ base = "sword", rarity = "common", level = 1, seed = 1 }))
-- one sword of each rarity, a unique and two set pieces to walk over
for i, r in Gear.RARITIES do
Inventory.spawnItem(Gear.roll({ base = "sword", rarity = r, level = 10, seed = i }), 1, { -6 + i * 2, 0, 5 })
end
Inventory.spawnItem("gu-doomwhisper", 1, { 0, 0, 8 })
Inventory.spawnItem("gu-ashenHelm", 1, { -2, 0, 8 })
Inventory.spawnItem("gu-ashenPlate", 1, { 2, 0, 8 })
end
```
Press Play and walk up to a sword: the card shows it against what you hold, with green and red deltas and an UPGRADE / DOWNGRADE / SIDEGRADE verdict with the power change. Walk over it to pick it up, equip it from the bag, press C: the stats panel flashes the stats that changed. Put on two Ashen Warlord pieces and the set block on their tooltip lights the 2-piece bonus. Enemies drop with `Gear.rollDrop({ level = 12, depth = floor, luck = Gear.dropLuck() })`.
This world's showcase scene (`scenes/main.scene`) is that loot room with every rarity, unique and set piece laid out.
## Guides
Two guides ship in `gearStatsKit.package/guides/` and install with the package (`zero guides read <name>`):
- **[How to give items stats that apply when equipped](how-to-give-items-stats-that-apply-when-equipped)** (`how-to-give-items-stats-that-apply-when-equipped`): rolled items, rarity and affixes, uniques and sets, binding a character, what changes in abilitiesKit, comparing, looks, card styles, adding content as data, multiplayer.
- **[Example: loot with random stats and gear comparison from an empty world](example-loot-with-random-stats-and-gear-comparison-from-an-empty-world)** (`example-loot-with-random-stats-and-gear-comparison-from-an-empty-world`): a loot room built step by step, with drops from tier tables, a unique and a set.
## Affixes (26)
Values are at item level 1 before quality; `perLevel` grows them with item level and rarity multiplies them (1.0 to 1.65). An item never rolls two affixes on the same stat, and takes at most two prefixes and two suffixes.
| id | name (fantasy / sci-fi) | type | stat | range | rolls on | min item level |
|---|---|---|---|---|---|---|
| `arcane` | Arcane / Capacitive | prefix | Max Mana | 8 to 20 | weapon, armour, jewelry | 1 |
| `blazing` | Blazing / Plasma | prefix | Fire Damage | 2 to 6 | weapon, jewelry | 1 |
| `brutal` | Brutal / Overdriven | prefix | Crit Damage | 10 to 25% | weapon, jewelry | 3 |
| `cruel` | Cruel / Overclocked | prefix | Damage | 5 to 10% | weapon, jewelry | 1 |
| `glacial` | Glacial / Cryo | prefix | Frost Damage | 2 to 6 | weapon, jewelry | 1 |
| `keen` | Keen / Calibrated | prefix | Crit Chance | 1.5 to 3.5% | weapon, jewelry | 1 |
| `leeching` | Leeching / Leech Loop | prefix | Life Steal | 1 to 3% | weapon, jewelry | 5 |
| `serrated` | Serrated / Hardlight | prefix | Damage | 2 to 5 | weapon | 1 |
| `sturdy` | Sturdy / Plated | prefix | Armour | 4 to 9 | armour | 1 |
| `swift` | Swift / Hyperthreaded | prefix | Attack Speed | 4 to 8% | weapon, armour, jewelry | 1 |
| `thorned` | Thorned / Barbed | prefix | Thorns | 3 to 8 | armour | 1 |
| `thundering` | Thundering / Arc | prefix | Lightning Damage | 1 to 8 | weapon, jewelry | 1 |
| `vampiric` | Vampiric / Siphoning | prefix | Life on Hit | 1 to 3 | weapon, jewelry | 1 |
| `ofFortune` | of Fortune / Mk Lucky | suffix | Magic Find | 4 to 10% | armour, jewelry | 4 |
| `ofGreed` | of Greed / Mk Profit | suffix | Gold Find | 5 to 15% | weapon, armour, jewelry | 1 |
| `ofGrounding` | of Grounding / Insulated | suffix | Lightning Resistance | 5 to 12% | armour, jewelry | 1 |
| `ofLearning` | of Learning / Mk Uplink | suffix | Experience | 3 to 8% | armour, jewelry | 1 |
| `ofTheBear` | of the Bear / Mk II | suffix | Max Health | 8 to 18 | armour, jewelry | 1 |
| `ofTheFox` | of the Fox / Mk III | suffix | Move Speed | 3 to 6% | armour, jewelry | 1 |
| `ofTheSage` | of the Sage / Prime | suffix | Cooldown Reduction | 3 to 7% | weapon, armour, jewelry | 1 |
| `ofTheSalamander` | of the Salamander / Thermal | suffix | Fire Resistance | 5 to 12% | armour, jewelry | 1 |
| `ofTheSpring` | of the Spring / Mk IV | suffix | Resource Regen | 5 to 12% | armour, jewelry | 1 |
| `ofTheTempest` | of the Tempest / Mk Wide | suffix | Area Size | 5 to 12% | weapon, jewelry | 6 |
| `ofTheTroll` | of the Troll / Nanite Weave | suffix | Health per Second | 1 to 3 | armour, jewelry | 1 |
| `ofTheWolf` | of the Wolf / X-Series | suffix | Damage | 1 to 4 | jewelry | 1 |
| `ofTheYeti` | of the Yeti / Cryo-Rated | suffix | Frost Resistance | 5 to 12% | armour, jewelry | 1 |
## Uniques (8)
Fixed stats: every copy has exactly these lines, at this item level. Their id is `gu-<id>`. Loot tables drop them on legendary rolls from their tier up.
| name | id | base | item level | from tier | lines |
|---|---|---|---|---|---|
| Doomwhisper | `gu-doomwhisper` | sword | 32 | 3 | +48 Damage, +25% Damage, +8% Crit Chance, +4% Life Steal |
| Winter's Grasp | `gu-wintersGrasp` | staff | 30 | 3 | +22 Damage, +30 Frost Damage, +15% Cooldown Reduction, +40 Max Mana, +20% Area Size |
| Stormcaller | `gu-stormcaller` | bow | 34 | 3 | +30 Damage, +35 Lightning Damage, +18% Attack Speed, +40% Crit Damage |
| Bulwark of the Last King | `gu-lastKingsBulwark` | shield | 36 | 4 | +120 Armour, +150 Max Health, +40 Thorns, +20% Fire Resistance, +20% Frost Resistance |
| Greedfinger | `gu-greedfinger` | ring | 28 | 2 | +60% Gold Find, +35% Magic Find, +4% Crit Chance |
| Emberheart | `gu-emberheart` | amulet | 30 | 3 | +25 Fire Damage, +30% Fire Resistance, +8 Health per Second, +15% Experience |
| Wanderer's Striders | `gu-wanderersStriders` | boots | 26 | 2 | +40 Armour, +22% Move Speed, +5 Health per Second, +25% Frost Resistance |
| Crown of the Hollow Saint | `gu-hollowSaintCrown` | helmet | 38 | 4 | +70 Armour, +90 Max Health, +30% Resource Regen, +20% Experience, +15% Magic Find |
## Sets (3)
A set bonus is on while that many different pieces are worn, applied with the pieces' own stats, and off the moment a piece comes off. A piece's tooltip lists every piece (worn ones lit) and every bonus (inactive ones greyed). Set pieces drop on epic and legendary rolls (`setChance`).
**Raiment of the Ashen Warlord** (4 pieces, item level 24): Ashen Warlord's Visor (helmet: +55 Armour, +60 Max Health, +15% Fire Resistance), Ashen Warlord's Cuirass (chestplate: +110 Armour, +80 Max Health, +15 Thorns), Ashen Warlord's Grip (gloves: +35 Armour, +8% Attack Speed, +10 Fire Damage), Ashen Warlord's Greaves (greaves: +60 Armour, +6% Move Speed, +15% Fire Resistance).
- 2 pieces: +20% Fire Resistance, +60 Armour
- 3 pieces: +15% Damage, +3% Life Steal
- 4 pieces: +40 Fire Damage, +50 Thorns
**Vestments of the Stormseer** (3 pieces, item level 30): Stormseer's Rod (staff: +20 Damage, +18 Lightning Damage, +30 Max Mana), Stormseer's Eye (amulet: +10% Cooldown Reduction, +25% Lightning Resistance, +10% Experience), Stormseer's Treads (boots: +30 Armour, +10% Move Speed, +15% Resource Regen).
- 2 pieces: +15% Cooldown Reduction, +40 Max Mana
- 3 pieces: +40 Lightning Damage, +25% Area Size
**Shadowstalker's Guise** (3 pieces, item level 20): Shadowstalker's Fang (dagger: +18 Damage, +5% Crit Chance, +2% Life Steal), Shadowstalker's Wraps (gloves: +25 Armour, +10% Attack Speed, +20% Crit Damage), Shadowstalker's Signet (ring: +3% Crit Chance, +20% Gold Find, +5% Move Speed).
- 2 pieces: +8% Crit Chance
- 3 pieces: +60% Crit Damage, +15% Attack Speed
## Every look and card style in one place
`Gear.styles()` is the one list a game asks for: every look and every card style, each `{ id, kind = "look" or "card", label, description, active }`. `Gear.useStyle(id)` switches to any of them with one call (the ids never clash), live, on the card, the stats panel and the HUD buttons:
```lua
for _, s in Gear.styles() do print(s.kind, s.id, s.label) end
Gear.useStyle("horror") -- the horror look
Gear.useStyle("sideBySide") -- the side by side compare card
```
`Gear.setup({ look = ..., cardStyle = ... })` and the `look` and `cardStyle` fields on the GearHost component set both at start.
## Looks (6)
`Gear.setLook(id)` re-skins the card, the stats panel and the HUD buttons instantly.
| id | look |
|---|---|
| `fantasy` | Parchment and gold leaf with serif type. |
| `scifi` | A translucent holo panel with cyan corner brackets. |
| `pixel` | Chunky 8-bit: hard edges, a thick white border, a hard drop shadow and monospace type. |
| `cartoon` | A bright cream panel with a thick ink outline, round corners and bouncy type. |
| `minimal` | A flat white card with hairlines and one accent. |
| `horror` | Rotting black parchment soaked in blood: a dripping red edge, bone-white serif text, a crimson glow. |
## Card styles (6)
Every tooltip and compare layout is listed in one place, `Gear.cardStyles()` (id, label, description), and switched with ONE setting: `Gear.setCardStyle(id)`, the same as `Gear.setup({ cardStyle = id })` or the `cardStyle` field on the `GearHost` component. The HUD redraws the card in the new style the same frame. Every style works in every look, and when comparing every style keeps the UPGRADE / DOWNGRADE / SIDEGRADE verdict and the power change.
| id | label | what it shows |
|---|---|---|
| `classic` | Classic tooltip | The full Diablo style tooltip: icon and name, main stat, every line, set block, compare rows and the verdict bar. |
| `sideBySide` | Side by side | The equipped item and the new item in two columns, with the stat deltas and the verdict under them. |
| `compact` | Compact line | One line: icon, name, item level and a verdict pill with the power change, plus the three biggest deltas. |
| `hero` | Hero card | A big showcase card: rarity banner, large icon, centred name and main stat, every line, flavour, set and verdict. |
| `diff` | Diff only | Only what changes: the name, one row per changed stat and the verdict. |
| `mobile` | Minimal mobile | Made for phones: the verdict first, large type and a two-column grid of finger-sized stat tiles. |
## Stats and how they apply
Every gear stat goes to an abilitiesKit stat as a flat or a percent modifier (source `"gearStatsKit"`), combined as (base + flat) x (1 + percent / 100). gearStatsKit defines the abilitiesKit stats abilitiesKit lacks (marked *).
| gear stat | abilitiesKit stat | modifier | gear stat | abilitiesKit stat | modifier |
|---|---|---|---|---|---|
| `damage` | `weaponDamage`* | flat | `maxHealth` | `maxHealth` (to SecondWind) | flat |
| `damagePercent` | `damage` (multiplier) | percent | `healthRegen` | `healthRegen`* (HP/s) | flat |
| `attackSpeed` | `attackSpeed`* | percent | `armor` | `armor` | flat |
| `critChance` | `critChance`* (base 5%) | flat | `thorns` | `thorns`* | flat |
| `critDamage` | `critDamage`* (base 150%) | flat | `fireResist`, `coldResist`, `lightningResist` | same* (max 75) | flat |
| `fireDamage`, `coldDamage`, `lightningDamage` | same* | flat | `moveSpeed` | `moveSpeed` (to the controller) | percent |
| `areaSize` | `areaSize`* (base 1x) | percent | `cooldownSpeed` | `cooldownSpeed` | percent |
| `lifeOnHit` | `lifeOnHit`* | flat | `maxResource` | `maxResource`* (mana) | flat |
| `lifeSteal` | `lifeSteal`* (%) | flat | `resourceRegen` | `resourceRegen` | percent |
| `goldFind`, `magicFind`, `xpBonus` | same* (%) | flat | | | |
A game's own combat reads them through `Gear.attackDamage(e, base)` = (base + weaponDamage + fire + frost + lightning) x damage, `Gear.rollHit(e, base)` (adds the crit), `Gear.hitEffects(attacker, dealt, defender)` (life on hit + life steal heal, thorns), `Gear.mitigate(e, amount, element)` (resistances, armour), `Gear.goldMultiplier(e)`, `Gear.xpMultiplier(e)` and `Gear.dropLuck(e)` (magic find as `rollDrop` luck).
## API
`local Gear = require("gearStatsKit.api")`.
**Rolling and items**
- `Gear.VERSION`, `Gear.RARITIES`, `Gear.LOOKS`, `Gear.CARD_STYLES`
- `Gear.roll(opts?) -> id`: opts `{ base?, slot?, kind?, rarity?, level? (1..50), seed?, rarityWeights?, theme? }`. Deterministic.
- `Gear.rollDrop({ level, depth?, luck?, seed?, table?, theme? }) -> id?`: nil is no drop. Without `table`, depth 1-2 `tier1`, 3-5 `tier2`, 6-9 `tier3`, 10+ `tier4`. Can return a unique or a set piece.
- `Gear.uniqueId(uniqueId, theme?) -> "gu-<id>"`, `Gear.tierFor(depth?, level?)`
- `Gear.describe(id) -> desc?`: `{ id, base, name, rarity, rarityLabel, color, level, slot, kind, theme, stats, implicit, affixes, power, icon, ... }`; uniques add `fixed = true, unique, flavor`, set pieces `set, setName`.
- `Gear.isGear(id) -> boolean`
**Comparing and cards**
- `Gear.compare(newId, oldId?) -> { rows = { { stat, label, new, old, delta, better } }, power, oldPower, powerDelta, verdict }`
- `Gear.equippedFor(slot, player?)`, `Gear.compareEquipped(id, player?)`
- `Gear.card(id, { compareTo? (id or true), style?, look?, width?, title?, hint?, id?, equipment? }) -> widget tree`
- `Gear.styles() -> { { id, kind, label, description, active } }` (every look and card style in one list), `Gear.useStyle(id) -> "look" | "card" | nil`
- `Gear.cardStyles() -> { { id, label, description } }`, `Gear.setCardStyle(id) -> boolean`, `Gear.cardStyle()`
- `Gear.setLook(id) -> boolean`, `Gear.look()`, `Gear.setTheme(name)`, `Gear.theme()`
**Sets**
- `Gear.setInfo(setId, equipment?, theme?) -> { id, name, color, pieces = { { id, itemId, name, worn } }, worn, bonuses = { { count, stat, value, label, active } } }`
- `Gear.setBonuses(equipment) -> { [setId] = setInfo }`
**Applying**
- `Gear.bind(entity, { equipment = fn? }?)`, `Gear.autoBind(on?)`, `Gear.unbind(entity)`, `Gear.refresh(entity?)`, `Gear.bound()`, `Gear.localCharacter()`
- `Gear.applyEquipment(entity, { [slot] = id }) -> ok, bonuses|why`
- `Gear.totals(entity?)`, `Gear.baseTotals(entity?)`, `Gear.bonuses(player?)`, `Gear.bonusesOf(equipment)` (item stats plus active set bonuses)
- `Gear.attackDamage`, `Gear.rollHit`, `Gear.hitEffects`, `Gear.mitigate`, `Gear.goldMultiplier`, `Gear.xpMultiplier`, `Gear.dropLuck`
**Content**
- `Gear.defineBase(raw)`, `Gear.defineAffix(raw)`, `Gear.defineUnique(raw)`, `Gear.defineSet(raw)`, `Gear.defineTable(name, raw)`, `Gear.defineStat(name, raw)`, `Gear.defineTheme(name, raw)`, `Gear.reload()`
- `Gear.catalogue() -> { bases, affixes, uniques, sets, rarities, stats, looks, cardStyles, themes, tables, version }`
**HUD**
- `Gear.setup({ compare, statsPanel, statsOpen, look, theme, cardStyle, hotkey = "C", radius = 4, autoBind = true, lookSwitcher, styleSwitcher, statsButton = true, hover = true }) -> settings`: in play it starts the `GearHost` HUD (compare card for the nearest gear on the ground and the hovered inventory slot, stats panel, look and card style switchers).
- `Gear.toggleStats()`, `Gear.setStatsOpen(open)`, `Gear.isStatsOpen()`, `Gear.config()`
- `Gear.on(event, fn) -> stop`: `applied`, `look`, `cardStyle`, `theme`, `stats`
## Data
- `gearBase.dataType`: the 14 bases (sword, axe, bow, dagger, staff, spear, helmet, chestplate, greaves, boots, gloves, shield, ring, amulet).
- `gearAffix.dataType`: `id, stat, type, min, max, perLevel, round, kinds, slots, weight, minLevel, nameFantasy, nameScifi`.
- `gearUnique.dataType`: `id, name, nameScifi, base, rarity, level, set, minTier, weight, flavor, stats = { { stat, value } }`.
- `gearSet.dataType`: `id, name, nameScifi, color, pieces, bonuses = { { count, stat, value } }`.
- `gearLootTable.dataType`: `id, name, nothingWeight, common .. legendary, levelBonus, bases, tier, uniqueChance, setChance`. `tier1` (no uniques), `tier2` (15% of legendaries are uniques, 6% of epic and legendary drops are set pieces), `tier3` (30%, 15%), `tier4` (50%, 25%).
Adding affixes or bases changes what existing rolled ids rebuild into; add content before release, or under new ids. Uniques and sets never change unless their data does.
## Phones and multiplayer
The HUD lays itself out inside inventoryKit's free screen space and scales up on a phone held upright; the `mobile` card style is made for it. Rolled and unique ids need no sync (the id is the item); each engine binds only its own player's character, and abilitiesKit lets only a character's owner change its stats.
## Tests
`zero tests run gearStatsKitTests` (edit mode, no player) runs **16 tests**: roll determinism, the resolver round trip, rarity affix counts, 20+ affixes covering every stat family, every affix applying and unapplying exactly, uniques fixed, set bonuses on and off at 2 / 3 / 4 pieces, tier odds with uniques and sets deep, compare verdicts, every look, every card style in every look, setCardStyle switching live, every style in one list with useStyle, the catalogue, README and version, guides.
## Changes
- **1.0.4**: built against inventoryKit 1.0.27 (saveKit 1.3.13, menusKit 1.3.19, controlsKit 1.3.2, pickupsKit 2.3.12) and abilitiesKit 1.1.5, the releases questKit, economyKit and arpgKit ship with, so a world holds one inventoryKit and one controlsKit; every file naming them is recorded again; package.yaml states those versions; current engine library. No stat behaviour changed.
- **1.0.3**: The compare card is drawn above an open inventory window instead of under it, and on a desktop it sits beside the window when there is room, otherwise over the window's left side (the character figure), clear of the bag slots the pointer is on. Before, at 1920 x 1080 with the paper doll open, half the card was hidden behind the Character window.
- **1.0.2**: `Gear.styles()` lists every look and card style in one list and `Gear.useStyle(id)` switches to any of them. The compare card also shows for a slot picked in the bag (a tap on a phone, or a game's pad cursor), not only for the one under the mouse.
- **1.0.1**: README and guides name the real install guid.
- **1.0.0**: First release, the successor of gearKit 1.0.1: 26 affixes, uniques, sets, the horror look and six card styles.