Log inGet started
World

Gearwright (replaced by gearStatsKit): old item stats kit

Branchmain
Branchesmain
Commit88eee65b91

README.md

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):

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>.

Stats and how they apply

gear statcard readsabilitiesKit statmodifier
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"armorflat
moveSpeed"+5% Move Speed"moveSpeed (to the controller)percent
cooldownSpeed"+5% Cooldown Speed"cooldownSpeedpercent
resourceRegen"+8% Resource Regen"resourceRegenpercent
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.