Log inGet started
World

Forge of Fortune: Diablo-Style Item Stats, Affixes, Sets and Uniques Kit

README.md

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

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

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.

idname (fantasy / sci-fi)typestatrangerolls onmin item level
arcaneArcane / CapacitiveprefixMax Mana8 to 20weapon, armour, jewelry1
blazingBlazing / PlasmaprefixFire Damage2 to 6weapon, jewelry1
brutalBrutal / OverdrivenprefixCrit Damage10 to 25%weapon, jewelry3
cruelCruel / OverclockedprefixDamage5 to 10%weapon, jewelry1
glacialGlacial / CryoprefixFrost Damage2 to 6weapon, jewelry1
keenKeen / CalibratedprefixCrit Chance1.5 to 3.5%weapon, jewelry1
leechingLeeching / Leech LoopprefixLife Steal1 to 3%weapon, jewelry5
serratedSerrated / HardlightprefixDamage2 to 5weapon1
sturdySturdy / PlatedprefixArmour4 to 9armour1
swiftSwift / HyperthreadedprefixAttack Speed4 to 8%weapon, armour, jewelry1
thornedThorned / BarbedprefixThorns3 to 8armour1
thunderingThundering / ArcprefixLightning Damage1 to 8weapon, jewelry1
vampiricVampiric / SiphoningprefixLife on Hit1 to 3weapon, jewelry1
ofFortuneof Fortune / Mk LuckysuffixMagic Find4 to 10%armour, jewelry4
ofGreedof Greed / Mk ProfitsuffixGold Find5 to 15%weapon, armour, jewelry1
ofGroundingof Grounding / InsulatedsuffixLightning Resistance5 to 12%armour, jewelry1
ofLearningof Learning / Mk UplinksuffixExperience3 to 8%armour, jewelry1
ofTheBearof the Bear / Mk IIsuffixMax Health8 to 18armour, jewelry1
ofTheFoxof the Fox / Mk IIIsuffixMove Speed3 to 6%armour, jewelry1
ofTheSageof the Sage / PrimesuffixCooldown Reduction3 to 7%weapon, armour, jewelry1
ofTheSalamanderof the Salamander / ThermalsuffixFire Resistance5 to 12%armour, jewelry1
ofTheSpringof the Spring / Mk IVsuffixResource Regen5 to 12%armour, jewelry1
ofTheTempestof the Tempest / Mk WidesuffixArea Size5 to 12%weapon, jewelry6
ofTheTrollof the Troll / Nanite WeavesuffixHealth per Second1 to 3armour, jewelry1
ofTheWolfof the Wolf / X-SeriessuffixDamage1 to 4jewelry1
ofTheYetiof the Yeti / Cryo-RatedsuffixFrost Resistance5 to 12%armour, jewelry1

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.

nameidbaseitem levelfrom tierlines
Doomwhispergu-doomwhispersword323+48 Damage, +25% Damage, +8% Crit Chance, +4% Life Steal
Winter's Graspgu-wintersGraspstaff303+22 Damage, +30 Frost Damage, +15% Cooldown Reduction, +40 Max Mana, +20% Area Size
Stormcallergu-stormcallerbow343+30 Damage, +35 Lightning Damage, +18% Attack Speed, +40% Crit Damage
Bulwark of the Last Kinggu-lastKingsBulwarkshield364+120 Armour, +150 Max Health, +40 Thorns, +20% Fire Resistance, +20% Frost Resistance
Greedfingergu-greedfingerring282+60% Gold Find, +35% Magic Find, +4% Crit Chance
Emberheartgu-emberheartamulet303+25 Fire Damage, +30% Fire Resistance, +8 Health per Second, +15% Experience
Wanderer's Stridersgu-wanderersStridersboots262+40 Armour, +22% Move Speed, +5 Health per Second, +25% Frost Resistance
Crown of the Hollow Saintgu-hollowSaintCrownhelmet384+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:

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.

idlook
fantasyParchment and gold leaf with serif type.
scifiA translucent holo panel with cyan corner brackets.
pixelChunky 8-bit: hard edges, a thick white border, a hard drop shadow and monospace type.
cartoonA bright cream panel with a thick ink outline, round corners and bouncy type.
minimalA flat white card with hairlines and one accent.
horrorRotting 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.

idlabelwhat it shows
classicClassic tooltipThe full Diablo style tooltip: icon and name, main stat, every line, set block, compare rows and the verdict bar.
sideBySideSide by sideThe equipped item and the new item in two columns, with the stat deltas and the verdict under them.
compactCompact lineOne line: icon, name, item level and a verdict pill with the power change, plus the three biggest deltas.
heroHero cardA big showcase card: rarity banner, large icon, centred name and main stat, every line, flavour, set and verdict.
diffDiff onlyOnly what changes: the name, one row per changed stat and the verdict.
mobileMinimal mobileMade 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 statabilitiesKit statmodifiergear statabilitiesKit statmodifier
damageweaponDamage*flatmaxHealthmaxHealth (to SecondWind)flat
damagePercentdamage (multiplier)percenthealthRegenhealthRegen* (HP/s)flat
attackSpeedattackSpeed*percentarmorarmorflat
critChancecritChance* (base 5%)flatthornsthorns*flat
critDamagecritDamage* (base 150%)flatfireResist, coldResist, lightningResistsame* (max 75)flat
fireDamage, coldDamage, lightningDamagesame*flatmoveSpeedmoveSpeed (to the controller)percent
areaSizeareaSize* (base 1x)percentcooldownSpeedcooldownSpeedpercent
lifeOnHitlifeOnHit*flatmaxResourcemaxResource* (mana)flat
lifeSteallifeSteal* (%)flatresourceRegenresourceRegenpercent
goldFind, magicFind, xpBonussame* (%)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.