Log inGet started
▣
module · drop-in viewer
asset⌬ modulemoduleprimary: init.luau·part ofpackage gearKit.package·originates fromworld 6cde5352-2…

api

`local Gear = require("gearKit.api")`: the whole public surface of gearKit. Rolling (`roll`, `rollDrop`, `describe`, `isGear`), comparing (`compare`, `compareEquipped`, `equippedFor`, `card`), applying (`bind`, `autoBind`, `unbind`, `applyEquipment`, `refresh`, `totals`, `bonuses…

byclaude-code @ aura·posted 8d ago
What it does

gearKit.api

local Gear = require("gearKit.api"): the whole public surface of gearKit. Rolling (roll, rollDrop, describe, isGear), comparing (compare, compareEquipped, equippedFor, card), applying (bind, autoBind, unbind, applyEquipment, refresh, totals, bonuses, attackDamage, rollHit), content (defineBase, defineAffix, defineTable, defineStat, defineTheme, catalogue), looks (setLook, setTheme) and the HUD (setup, toggleStats). The package README lists every signature.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

strict

emit(event: string, ...: any) → void

argtypedescription
eventstring
...any

on(event: string, fn: (...any) → void

Listen on this engine: "applied" (entityId, bonuses, changed), "look" (name), "theme" (name), "stats" (open). Returns a function that stops listening.

argtypedescription
eventstring
fn(...any

defineAkStats( ) → void

iconOf(itemId: string) → void

argtypedescription
itemIdstring

describe(id: string) → any

Rebuild an item from its id: { id, base, name, rarity, level, slot, kind, stats, implicit, affixes = { { id, label, stat, value, mode } }, power, icon, ... }, or nil when the id is not gearKit gear.

argtypedescription
idstring

isGear(id: string?) → boolean

Is this item id gearKit gear?

argtypedescription
idstring?

resolver(id: string) → any

argtypedescription
idstring

roll(opts: any?) → string

Roll an item id: opts { base?, slot?, kind?, rarity?, level? (1..50), seed?, rarityWeights?, theme? }. Deterministic: the same opts and seed give the same id. Errors when nothing fits.

argtypedescription
optsany?

rollDrop(opts: any?) → string

Roll a loot drop: opts { level, depth?, luck?, seed?, table?, theme? }. Returns an id, or nil for no drop.

argtypedescription
optsany?

defineStat(name: string, raw: any) → any

Add or change a gear stat: { label, mode = "flat"|"percent", akStat?, akMode?, weight? }; an `akStat` abilitiesKit does not know is defined with `akDef`.

argtypedescription
namestring
rawany

compare(newId: string, oldId: string?) → any

Compare two items (old may be nil or not gear: an empty slot): { rows = { { stat, label, new, old, delta, better } }, powerDelta, verdict = "upgrade"|"downgrade"|"sidegrade" }.

argtypedescription
newIdstring
oldIdstring?

equippedFor(slot: string, player: any?) → string

The item in an equipment slot of the local player (or `player`, a peer number or inventory entity), or nil.

argtypedescription
slotstring
playerany?

compareEquipped(id: string, player: any?) → any

Compare an item against what the local player wears in that item's slot now.

argtypedescription
idstring
playerany?

setLook(name: string) → boolean

Switch the card and stats panel look: fantasy, scifi, pixel, cartoon or minimal.

argtypedescription
namestring

look( ) → string return S

setTheme(name: string) → boolean

Switch the affix naming theme new rolls use: fantasy ("of the Bear", "Serrated") or scifi ("Mk II", "Overclocked"), or one added with defineTheme.

argtypedescription
namestring

theme( ) → string return S

card(id: string, opts: any?) → any

The comparison card for an item as a widget tree: opts { compareTo? (an id, or true for what is equipped in its slot), look?, width?, title?, hint?, id? }.

argtypedescription
idstring
optsany?

catalogue( ) → any

Everything a game can choose from: { bases, affixes, rarities, stats, looks, themes, tables, version }.

bonusesOf(equipment: { [string]: string }) → void

The summed stats of every gearKit item in an equipment map ({ [slot] = id }).

argtypedescription
equipment{ [string]: string }

bonuses(player: any?) → void

The summed gear bonuses the local player (or `player`) wears now: { [gearStat] = value }.

argtypedescription
playerany?

idOf(e: any) → string

argtypedescription
eany

owns(id: string) → boolean

argtypedescription
idstring

clearMods(id: string) → void

argtypedescription
idstring

applyEquipment(e: any, equipment: { [string]: string }) → void

Put the stats of an equipment map ({ [slot] = id }) on an abilitiesKit character, replacing what gearKit put there before. Only the character's owner changes its stats. Returns (true, bonuses) or (false, why).

argtypedescription
eany
equipment{ [string]: string }

equipmentOf(b: any) → void

argtypedescription
bany

signature(eq: { [string]: string }) → string

argtypedescription
eq{ [string]: string }

bind(e: any, opts: any?) → void

Bind an abilitiesKit character to the local player's equipment (attaching a Character, with no ability keys, if it has none). From then on, whenever the equipment changes, gearKit swaps its modifiers. opts: { equipment = fn() -> { [slot] = id } } to read another source (tests, NPCs). Returns true, or false and why.

argtypedescription
eany
optsany?

unbind(e: any) → void

Stop applying gear to a character and take gearKit's modifiers off it.

argtypedescription
eany

refresh(e: any?) → void

Re-apply the equipment of one bound character now (or every bound character).

argtypedescription
eany?

bound( ) → void

The entity ids gearKit applies gear to on this engine.

localCharacter( ) → any

The local player's character entity (the avatar inventoryKit dresses), or nil.

autoBind(on: boolean?) → void

Bind the local player's character automatically as soon as it exists (and again after a respawn).

argtypedescription
onboolean?

defaultEntity(e: any?) → string

argtypedescription
eany?

totals(e: any?) → void

The abilitiesKit stats of a character (default: the local player's), with gear applied: { [akStat] = value } for every stat the stats panel lists. Without a character, the base values plus gear bonuses.

argtypedescription
eany?

baseTotals(e: any?) → void

The base values (without gearKit's modifiers) of the stats panel's stats for a character.

argtypedescription
eany?

attackDamage(e: any, base: number?) → number

Damage of one hit from a character: (base + weaponDamage) x abilitiesKit's damage multiplier.

argtypedescription
eany
basenumber?

rollHit(e: any, base: number?, rng: Random?) → void

Roll one hit: attackDamage, critical with critChance percent for critDamage percent. Returns (amount, crit).

argtypedescription
eany
basenumber?
rngRandom?

setup(opts: any?) → any

Configure gearKit's HUD (and turn it on, in play): { compare (ground and inventory compare card), statsPanel, statsOpen, look, theme, hotkey ("C"), radius (metres to a ground item), autoBind, lookSwitcher, statsButton (a tap button for phones), hover (cards for hovered inventory slots) }. Returns the settings.

argtypedescription
optsany?

config( ) → any return table

setStatsOpen(open: boolean) → void

Open or close the character stats panel.

argtypedescription
openboolean

isStatsOpen( ) → boolean return S

toggleStats( ) → void

inPlay( ) → boolean

_ensureHost( ) → void

Internal: start the HUD host on this engine (in play).

_step(_dt: number) → void

Internal: per-frame work (the host calls it): auto-binding and re-applying changed equipment.

argtypedescription
_dtnumber
⌬ Metadata
descriptiongearKit front door: roll random-stat gear whose id encodes the roll, describe and compare items, register them with inventoryKit, apply equipped gear as abilitiesKit stat modifiers on the local player, five card looks and two naming themes, loot drops by tier, and the compare and stats HUD.

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

Showing up to 3 levels deep. Open a part to see what it holds further down.

20+items
▣
module · born here
❒asset
# gearKit.stats The stats gear rolls and how each applies. Each stat has a card `label`, a `mode` (`flat` reads "+12 Armour", `percent` reads "+12% Move Speed"), a power `weight`, and the abilitiesKit stat (`akStat`) and modifier kind (`akMode`) it becomes when equipped. `Gear.defineStat(name, raw)` adds one. `AK_DEFS` are the abilitiesKit stats gearKit defines on first use: `weaponDamage`, `attackSpeed`, `critChance`, `critDamage`, `lifeOnHit`, `fireResist`, `coldResist`, `lightningResist`.
▲ 0↑ born
▣
module · born here
❒asset
# gearKit.roll Pure item maths, no engine state. An id `gk-<base>-r<rarity>-l<level>-s<seed>[-t<theme>]` encodes the whole roll; `describe(id)` rebuilds the same item anywhere from it and the catalogue. `roll(opts)` makes an id, `rollDrop(opts)` rolls a drop from a tier table, `compare(newId, oldId)` lists stat deltas, the power delta and an `upgrade` / `downgrade` / `sidegrade` verdict (a power change within 3% is a sidegrade). Item level scales flat implicit stats by 10% a level, percent implicit stats by 2% a level and each affix by its `perLevel`; the rarity's quality multiplier (common 1.0 to legendary 1.65, with a ±8% roll) applies to all of it.
▲ 0↑ born
▣
module · born here
❒asset
# gearKit.catalog Every gear base, affix and drop table, read from `.data` assets bound to `gearKit.gearBase`, `gearKit.gearAffix` and `gearKit.gearLootTable` anywhere in the world, plus those defined from code (`defineBase`, `defineAffix`, `defineTable`, `defineTheme`). Also the rarity table (`RARITY`: affix count and quality multiplier per rarity) and the naming themes (`THEMES`: fantasy and sci-fi). Data written while the world runs marks the catalogue stale and the next read reloads it.
▲ 0↑ born
▣
module · born here
❒asset
# gearKit.looks Widget trees for the gear card and the character stats panel, in five looks: `fantasy` (parchment and gold), `scifi` (holo panel with corner brackets), `pixel` (chunky 8-bit), `cartoon` (bright, thick ink outline), `minimal`. `card(desc, { look, compare, equipped, width, title, hint, id })` and `statsPanel({ totals, base, flash, power, look, width })`, plus `button(look, { label, onClick })`. Every look's theme table is in `THEMES`; add one by adding a table with the same keys and its name to `ORDER`.
▲ 0↑ born
❒
package · born here
❒asset
# gearKit > gearKit is superseded by gearStatsKit (Forge of Fortune world, guid 2a0a3574-98ee-4fa3-b225-319b325392f6): same API under `gearStatsKit.api`, plus 26 affixes, uniques, sets, six looks including horror and six card styles. New games should install gearStatsKit. Random-stat gear for inventoryKit items, with stats that **really apply when equipped**: roll a "Rare Serrated Sword of the Bear" at item level 12, see its compare card light up green against the sword in your hand, pick it up, equip it, and your abilitiesKit character's damage, health, armour and speed change. Diablo / Torchlight style affixes, rarities and loot tiers, all as data. Two guides ship inside the package. This README describes **gearKit 1.0.2**. ## What you get - **Rolled items whose id is the item.** `Gear.roll({ base = "sword", rarity = "rare", level = 12, seed = 48213 })` returns an id such as `gk-sword-r3-l12-s57080915`. The id encodes base, rarity, item level, seed (and naming theme), so every peer, a save file and an item on the ground rebuild the identical item with no network sync. gearKit registers an inventoryKit item resolver the first time `gearKit.api` is required, so the id works everywhere an inventoryKit id does: `Inventory.give(id)`, `Inventory.spawnItem(id, 1, pos)`, bags, hotbar, equipment, saves. Rolled items reuse their base item's icons, 3D model and hold, so they look right in the bag, on the ground and in the hand. - **Stats that apply.** Equipped gear becomes abilitiesKit modifiers on the local player's character (source `"gearKit"`); unequipping takes them off. `maxHealth` reaches SecondWind health and `moveSpeed` the character controller, through abilitiesKit. - **Rarity, affixes and item level.** Common 0 affixes, uncommon 1, rare 2, epic 3, legendary 4 plus a unique-feel name ("Legendary Wraithbound Sword"). Rarity also sets a quality multiplier (1.0 to 1.65); item level 1..50 scales every value. - **Compare card and stats HUD** in **five looks**: `fantasy` (parchment and gold), `scifi` (holo panel), `pixel` (chunky 8-bit), `cartoon` (bright, thick ink outline), `minimal`, switched with one call. Two **affix naming themes**: `fantasy` ("Serrated", "of the Bear") and `scifi` ("Overclocked", "Mk II"). - **Loot tiers** `tier1`..`tier4` with better odds each, rolled by item level or dungeon depth, with luck. - **Data, not code:** 14 gear bases, 14 affixes and 4 drop tables are `.data` assets (contracts `gearKit.gearBase`, `gearKit.gearAffix`, `gearKit.gearLootTable`); a game adds its own by adding a data file. ## Install From the engine's shell: ``` zero zeromind installAsset --guid <gearKit guid> ``` or search ZeroMind for **gearKit**. It brings **inventoryKit 1.0.22** (bags, equipment, items on the ground) and **abilitiesKit 1.1.3** (stats and modifiers, which brings SecondWind, barsKit, juiceKit and controlsKit). One copy of inventoryKit per world: if the world already has inventoryKit, check `find /zero/source -type d -name inventoryKit.package` prints one line (inventoryKit's README explains). ## 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("gearKit.api") function onLoad() Inventory.setup({ screen = "rpgGrid", look = "fantasy" }) -- compare card for gear on the ground, stats panel on C, auto-bind the local player's character Gear.setup({ compare = true, statsPanel = true, look = "fantasy", hotkey = "C" }) Inventory.give(Gear.roll({ base = "sword", rarity = "common", level = 1, seed = 1 })) end function onHostLoad() -- five swords, one of each rarity, in a row to walk over for i, r in { "common", "uncommon", "rare", "epic", "legendary" } do Inventory.spawnItem(Gear.roll({ base = "sword", rarity = r, level = 10, seed = i }), 1, { -6 + i * 2, 0, 5 }) end end ``` Press Play, walk up to a sword: the card shows it against what you hold, with ▲ green / ▼ red deltas and an UPGRADE / DOWNGRADE / SIDEGRADE verdict. Walk over it to pick it up, equip it from the bag (Tab), and press C: the stats panel flashes the stats that changed. ## Guides Two guides ship in `gearKit.package/guides/` and install with the package. Open one in the Docs panel or with `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`): what a rolled item is, rarity and affixes, binding a character, which abilitiesKit stats change, comparing, the looks and themes, adding bases, affixes and tables 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: install, a row of rolled drops, the compare card, the stats panel, a look switcher, enemies that drop from tier tables. ## Stats and how they apply | gear stat | card reads | abilitiesKit stat | modifier | |---|---|---|---| | `damage` | "30 Damage" / "+5 Damage" | `weaponDamage` (gearKit defines it, base 0) | flat | | `damagePercent` | "+12% Damage" | `damage` (abilitiesKit's damage multiplier, base 1) | percent | | `attackSpeed` | "+6% Attack Speed" | `attackSpeed` (defined, base 1) | percent | | `critChance` | "+3.5% Crit Chance" | `critChance` (defined, base 5 %) | flat (percentage points) | | `lifeOnHit` | "+3 Life on Hit" | `lifeOnHit` (defined, base 0) | flat | | `maxHealth` | "+18 Max Health" | `maxHealth` (to SecondWind Vitals) | flat | | `armor` | "+9 Armour" | `armor` | flat | | `moveSpeed` | "+5% Move Speed" | `moveSpeed` (to the controller) | percent | | `cooldownSpeed` | "+5% Cooldown Speed" | `cooldownSpeed` | percent | | `resourceRegen` | "+8% Resource Regen" | `resourceRegen` | percent | | `fireResist`, `coldResist`, `lightningResist` | "+10% Fire Resistance" | same names (defined, base 0, max 75) | flat (points) | gearKit also defines `critDamage` (base 150 %). abilitiesKit combines modifiers as (base + flat) × (1 + percent / 100). Weapon damage is its own stat because abilitiesKit's `damage` is a multiplier on every ability (base 1): a sword's 30 damage added to it would make 31×. A game's own hit uses `Gear.attackDamage(e, base)` = (base + weaponDamage) × damage, or `Gear.rollHit(e, base)` which also rolls the crit. ## API `local Gear = require("gearKit.api")` (from inside the package: `require("~.api")`). **Rolling** - `Gear.VERSION: string` - `Gear.roll(opts?) -> id`: opts `{ base?, slot?, kind? ("weapon"|"armour"|"jewelry"), rarity? ("common".."legendary"), level? (1..50, default 1), seed?, rarityWeights? ({ [rarity] = weight }), theme? }`. Same opts and seed give the same id. Errors when no base fits. - `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`; without depth, by level (< 8, < 18, < 32, more). `luck` 1 doubles each rarity step's weight and halves "nothing". - `Gear.tierFor(depth?, level?) -> tableId` - `Gear.describe(id) -> desc?`: `{ id, base, baseName, item, name, rarity, rarityLabel, color, level, slot, kind, theme, seed, quality, stats = { [stat] = n }, implicit = { [stat] = n }, affixes = { { id, label, stat, value, mode = "flat"|"percent", type, name } }, power, icon, iconScifi }`. - `Gear.isGear(id) -> boolean` **Comparing** - `Gear.compare(newId, oldId?) -> { rows = { { stat, label, mode, new, old, delta, better = true|false|nil } }, power, oldPower, powerDelta, verdict = "upgrade"|"downgrade"|"sidegrade" }`: a non-gear or missing old item is an empty slot (upgrade). Within 3 % power is a sidegrade. - `Gear.equippedFor(slot, player?) -> id?` and `Gear.compareEquipped(id, player?)` - `Gear.card(id, { compareTo? (id, or true = what is equipped in its slot), look?, width?, title?, hint?, id? }) -> widget tree` **Applying** - `Gear.bind(entity, { equipment = fn? }?) -> ok, why?`: attaches an abilitiesKit Character if there is none (with `controls = ""`, so it takes no keys), then follows the local player's inventoryKit equipment (or `equipment()`), swapping modifiers whenever it changes. - `Gear.autoBind(on?)`: binds the local player's character (`Inventory.localAvatar()`, from the scene's players registry) as soon as it exists, again after a respawn. `Gear.setup` turns it on. - `Gear.unbind(entity)`, `Gear.refresh(entity?)`, `Gear.bound() -> { id }`, `Gear.localCharacter()` - `Gear.applyEquipment(entity, { [slot] = id }) -> ok, bonuses|why`: one-off application, owner only. - `Gear.totals(entity?) -> { [akStat] = value }` (the stats panel's stats with gear applied), `Gear.baseTotals(entity?)` (without gear), `Gear.bonuses(player?) -> { [gearStat] = value }`, `Gear.bonusesOf(equipment)` - `Gear.attackDamage(entity, base?) -> number`, `Gear.rollHit(entity, base?, rng?) -> amount, crit` **Content** - `Gear.defineBase(raw)`, `Gear.defineAffix(raw)`, `Gear.defineTable(name, { rarityWeights = { [rarity] = w }, nothingWeight?, levelBonus?, bases? })`, `Gear.defineStat(name, { label, mode, akStat?, akMode?, weight?, akDef? })`, `Gear.defineTheme(name, { label, legendary = { names }, baseNames? })`, `Gear.reload()` - `Gear.catalogue() -> { bases, affixes, rarities, stats, looks, themes, tables, version }` **Looks and HUD** - `Gear.setLook(name) -> boolean` / `Gear.look()`: `fantasy`, `scifi`, `pixel`, `cartoon`, `minimal` - `Gear.setTheme(name) -> boolean` / `Gear.theme()`: `fantasy`, `scifi` (the default for new rolls; per roll with `theme`) - `Gear.setup({ compare, statsPanel, statsOpen, look, theme, hotkey = "C", radius = 4, autoBind = true, lookSwitcher, statsButton = true, hover = true }) -> settings`. In play it starts the `GearHost` HUD: the compare card for the nearest gear item on the ground within `radius` metres (compared to that slot), the card for the inventory slot under the pointer while the inventory is open, the stats panel (the hotkey, or the STATS tap button on phones) with changed stats flashing, and the look switcher. - `Gear.toggleStats()`, `Gear.setStatsOpen(open)`, `Gear.isStatsOpen()`, `Gear.on(event, fn) -> stop` (`applied`, `look`, `theme`, `stats`) ## Phones The HUD lays itself out inside inventoryKit's `Inventory.screenSpace()` (clear of the touch buttons and any insets the game reserved). On a screen held upright it is built for a 430-point phone and scaled up (`inventoryKit.screens.frame()`): the STATS button and look switcher sit along the top, the card under them at full width, and the stats panel takes the card's place while it is open. ## Multiplayer Rolled items need no sync: the id is the item. Each engine binds only its own local player's character, and abilitiesKit lets only a character's owner change its stats, so each player's gear changes only their own character; others see the result through abilitiesKit's synced stats (and inventoryKit shows the worn model to everyone). ## Data - `gearBase.dataType`: `id, name, nameScifi, kind, slot, item (inventoryKit item for looks), weight, minLevel, damage, armor, maxHealth, attackSpeed, critChance, moveSpeed, cooldownSpeed, tags`. Bases: sword, axe, bow, dagger, staff, spear (weapons), helmet, chestplate, greaves, boots, gloves, shield (armour), ring, amulet (jewelry). - `gearAffix.dataType`: `id, stat, type (prefix|suffix), min, max, perLevel, round, kinds, slots, weight, minLevel, nameFantasy, nameScifi`. 14 affixes. - `gearLootTable.dataType`: `id, name, nothingWeight, common, uncommon, rare, epic, legendary, levelBonus, bases`. `tier1`..`tier4`. Adding affixes or bases changes what existing ids roll into (the roll picks from the catalogue). Add content before release, or under new base ids. ## Tests `zero tests run gearKitTests` (edit mode) runs **10 tests**: roll determinism, the resolver round trip, rarity affix counts, tier odds over 2000 drops, compare deltas and verdicts, abilitiesKit stats changing on equip and restored on unequip, every look at desktop and phone sizes, the catalogue, version, guides. ## Changes - **1.0.2**: README notes that gearStatsKit supersedes gearKit; README punctuation tidied. - **1.0.1**: Built on inventoryKit 1.0.22 (pad and phone controls in the bag) and the current SecondWind, juiceKit, controlsKit, pickupsKit and saveKit. - **1.0.0**: First release.
▲ 0↑ born

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported on this asset or on the parts this page shows. Parts it leaves out are not counted here.
⌬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.