Forge of Fortune: Diablo-Style Item Stats, Affixes, Sets and Uniques Kit
- ..
- .metadata1.2 KB
- GearHost.component
- README.md21.6 KB
- affixes
- api.module
- bases
- cards.module
- catalog.module
- gearAffix.dataType
- gearBase.dataType
- gearLootTable.dataType
- gearSet.dataType
- gearStatsKitTests.testSuite
- gearUnique.dataType
- guides
- looks.module
- package.yaml450 B
- rng.module
- roll.module
- sets
- stats.module
- tables
- uniques
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.gearAffixand so on). A game's own.datafiles bound togearKit.gearAffixmust namegearStatsKit.gearAffix. Gear.carddraws the current card style (defaultclassic, the gearKit card). Passstyleto pick one per call.Gear.compare,Gear.bonusesOfand the stats HUD now include unique items and set bonuses.Gear.attackDamageadds 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>):
- 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): 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:
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_STYLESGear.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. Withouttable, depth 1-2tier1, 3-5tier2, 6-9tier3, 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 addfixed = true, unique, flavor, set piecesset, 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 treeGear.styles() -> { { id, kind, label, description, active } }(every look and card style in one list),Gear.useStyle(id) -> "look" | "card" | nilGear.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|whyGear.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 theGearHostHUD (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 andGear.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.