Lucky Capsule: Gacha Pulls, Rarity Tiers and Pity Kit
README.md
gachaKit: Lucky Capsule
gachaKit 1.0.0 gives any multiplayer Zero game a gacha: players spend in-game currency or tickets they earned in the game to pull characters, outfits, course toys or any item ids your game defines from banners, with rarity tiers, exact odds that are always on screen, soft and hard pity, a 10-pull guarantee, duplicate conversion and six pull presentations in four looks. There is no way to buy currency with real money anywhere in the kit.
What you get:
- Banners as data.
Gacha.defineBanner{ id, cost, pool, style, pity, guarantee, duplicates }. Items are any ids your game understands. - Four rarity styles, one setting:
classic(Common / Rare / Epic / Legendary),stars(1 to 5 Stars),gems(Quartz, Jade, Sapphire, Amethyst, Ruby),metals(Bronze, Silver, Gold, Platinum, Diamond). Each has default rates; a banner can set its own (they must sum to 100). - Pity: soft pity (from pull
softsince the last top tier, its chance rises byramppoints per pull), hard pity (pullhardis always the top tier), a guarantee (everypulls in a row hold at least onetieror better), kept per player, per banner, saved, and shown as a counter on the banner screen. - Odds always visible, and real. The banner screen always shows every tier's chance; the Odds panel lists every tier and every item with its exact chance per pull, its long-run chance with pity, and the chance on this player's next pull, plus the pity rules in words. Every number is computed from the same tables the roll uses (
gachaKit.rates), and the test suite checks them against 100,000 seeded pulls. - Duplicates turn into a currency (Shards by default, amount per tier) or into item levels (
mode = "upgrade", up tomaxLevel, then currency). - Six presentations, one setting:
capsuleMachine,cardPack,eggHatch,treasureChest,starPortal,clawMachine, each in four looks:cartoon,neon,pixel,fantasy. The reveal escalates with rarity: glow colour, charge shake, light beams for the two top tiers, more sparks per tier, a white flash, a stage jolt and confetti for the top tier, and a sound per tier (seven generated sounds ship in the kit). Skip button, tap to speed up, a 10-pull summary with NEW and duplicate badges. - Cheat-proof multiplayer. The roll happens on the authority only: the machine that runs economyKit's bank. A player's machine sends a request; the authority names the account from the sender, checks the banner and count against its own definitions, takes the price from the wallet (all or nothing), rolls with its own random source, updates that player's pity and collection, saves them and answers. Each player has their own collection, pity and coins, saved per player in the world's runtime data (and copied into their saveKit profile, which the authority never trusts).
- Your own money too. A currency that is not an economyKit currency (an idle game's big-number coins) plugs in with
Gacha.setCurrency(id, { spend, grant, balance, localBalance }), called on the authority. - Luck: a per-player modifier the game sets on the authority (
Gacha.setModifiers(player, { luck = n })or asetModifierSourcecallback) that raises the higher tiers by a documented formula; the odds panel shows the player's own modified odds. - Input: keyboard and mouse, gamepad (the UI's focus navigation plus shortcuts), touch, and phone layouts held upright.
- A showcase: this world's main scene runs
gachaKit.demo: six demo banners, free in-game demo currency, and a panel that switches every presentation and look live, with a gallery of all six machines.
Install: search ZeroMind for "gachaKit" (or "gacha", "loot box with pity", "capsule toy machine") and install the package; it brings economyKit (with inventoryKit, saveKit, menusKit, navUiKit, controlsKit) and dropTablesKit with it.
Guides ship inside the package:
- How to add a gacha with rarity tiers and pity to my game (
gachaKit.package/guides/how-to-add-a-gacha-with-rarity-tiers-and-pity): every part and setting. - Make a capsule toy game where players pull for collectibles (
gachaKit.package/guides/make-a-capsule-toy-game-with-gacha-pulls): an example game from an empty world.
Your first banner
In a world with gachaKit installed, put this in scenes/main.scene/entrypoint.luau and press Play:
local Economy = require("economyKit.economy")
local Gacha = require("gachaKit.gacha")
function onLoad()
Economy.setup({ currencies = { "coins" }, wallet = "corner" })
Economy.defineCurrency({ id = "shards", name = "Shards", icon = "gems", start = 0 })
Gacha.setup({ presentation = "capsuleMachine", look = "cartoon" })
Gacha.defineBanner({
id = "toys", title = "Toy Capsules", style = "classic",
cost = { currency = "coins", amount = 10 },
pool = {
{ item = "duck", name = "Rubber Duck", tier = "common" },
{ item = "spring", name = "Spring", tier = "common" },
{ item = "barrel", name = "Barrel", tier = "rare" },
{ item = "rocket", name = "Rocket Boots", tier = "epic" },
{ item = "goldStair", name = "Golden Stair", tier = "legendary" },
},
pity = { soft = 60, hard = 80 },
})
Gacha.open("toys")
end
The banner screen opens over the game. Every new wallet holds 100 coins (economyKit's coins default), so Pull x10 (100 coins) works once; press it and watch ten capsules drop. Close with Esc, B or the cross; Gacha.open("toys") from a button, a key or a trigger brings it back. Stop and Play again: your collection, pity counter and coins are still there.
Integration API
local Gacha = require("gachaKit.gacha"). Call setup and define banners on every machine (a scene's onLoad): the authority uses its own copy, so a player's machine cannot change prices or odds.
Define banners for your own characters, outfits and toys
Gacha.defineBanner({
id = "heroes", title = "Star Friends", description = "Characters from beyond the stairs.",
style = "stars", -- classic | stars | gems | metals
rates = { star1 = 50, star2 = 30, star3 = 14.4, star4 = 5, star5 = 0.6 }, -- optional; sum 100
cost = { currency = "coins", amount = 160 }, -- per pull
cost10 = { currency = "coins", amount = 1440 }, -- optional ten-pull price
ticket = { currency = "tickets", amount = 1 }, -- optional: tickets pay first when the player has enough
counts = { 1, 10 }, -- pull sizes offered
pity = { soft = 74, hard = 90, ramp = 6 }, -- or false
guarantee = { every = 10, tier = "star4" }, -- or false; default: the tier below the top every 10
duplicates = { mode = "upgrade", currency = "shards", maxLevel = 5, amounts = { star5 = 600 } },
luck = { perLevel = 0.10, max = 10 },
presentation = "starPortal", look = "neon", -- optional per banner
pool = {
{ item = "pip", name = "Pip the Intern", tier = "star1" },
{ item = "stairlord", name = "The Stair Lord", tier = "star5", icon = "myGame.icons.stairlord", weight = 1 },
-- weight: share inside its tier (default 1); icon: a texture asset (otherwise a token with initials)
},
})
Defaults: rates from the style; pity soft 75, hard 90, ramp 6 points; guarantee the tier below the top every 10 pulls; duplicates into shards (5 / 15 / 50 / 200 / 600 by tier for five tiers, the top four for four tiers). Wrong definitions fail at defineBanner with the field named (rates that do not sum to 100, unknown tiers, a rated tier with no items).
Grant tickets and currency the player earned
Tickets are an ordinary economyKit currency (Economy.defineCurrency({ id = "tickets", icon = "tickets", start = 0 })). Give them where the game decides rewards, on the authority:
if Gacha.isHost() then Gacha.grant(player, "tickets", 1, "dailyClimb") end -- player: peer id, account key or avatar
From a player's machine, Gacha.grant goes through economyKit's rules (Economy.setup{ clientGrants = { dailyClimb = { max = 5, perMinute = 10 } } }).
A currency that is not an economyKit currency
Gacha.setCurrency("bonks", { -- on every machine, same id
name = "Bonks",
spend = function(key, amount, reason, peer) return MyIdle.trySpend(key, amount) end, -- authority: true / false, "why"
grant = function(key, amount, reason, peer) MyIdle.give(key, amount); return true end,
balance = function(key) return MyIdle.balanceOf(key) end, -- authority: lets a mixed price stay all-or-nothing
localBalance = function() return MyIdle.myBalance() end, -- the local player's, for the screens
format = function(n) return MyIdle.short(n) end, -- optional "1.2M"
})
Gacha.defineBanner({ id = "toys", cost = { currency = "bonks", amount = 2.5e6 }, ... })
Open the screen
Gacha.open("heroes") -- the banner's own presentation and look
Gacha.open("heroes", { presentation = "eggHatch", look = "fantasy", tab = "odds" })
Gacha.setPresentation("clawMachine") -- every pull from now on
Gacha.setLook("pixel")
Gacha.close(); Gacha.isOpen()
Gacha.setInsets({ left = 180 }) -- keep clear of your HUD
Keys: P / 0 pull x1 / x10, O odds, C collection, Q / E banners, Tab skip, Enter / Space continue, Esc back. Gamepad: d-pad and A move and press (the UI's focus navigation), LT / RT pull x1 / x10, X odds, Y skip, LB / RB banners, B back. Touch: tap the buttons, tap the presentation to speed it up.
Pull from code and read the result
Gacha.pull("heroes", 10, function(res)
if res.ok == false then print(res.text) return end -- "Not enough Coins: you need 40 more"
for _, r in res.results do print(r.item, r.tier, r.new, r.dup and r.dup.kind) end
end)
Gacha.canAfford("heroes", 10) -- ok, costs (tickets first)
Gacha.busy() -- a request is waiting for the authority
Read the collection
Gacha.collection() -- { [item] = { n = copies, lv = level, tier, banner, at } } for the local player
Gacha.collection(peerOrKey) -- any player's, on the authority
Gacha.owns("stairlord") -- true, level
Gacha.progress("heroes") -- owned, total
Gacha.history() -- the last 40 pulls, newest first
Gacha.pity("heroes") -- { c = pulls since top tier, g = pulls since guarantee tier, n = pulls }
Gacha.odds("heroes") -- everything the odds panel shows (per pull, with pity, your next)
Apply what an item does in your game (unlock a character, equip an outfit, place a toy) from the collection, and listen for changes:
Gacha.on("new", function(e) MyGame.unlock(e.item) end) -- { item, tier, name, banner, rank, top }
Gacha.on("duplicate", function(e) end) -- { ..., dup = { kind = "currency" | "level", ... } }
Gacha.on("pull", function(e) end) -- { banner, results, paid, credited, pity }
Gacha.on("refused", function(e) end) -- { code, text, banner }
Gacha.on("state", function(rec) end) -- the player's record changed (also on joining)
Gacha.on("host.pull", function(e) end) -- on the authority, every player's pulls
Each on returns a function that removes the listener; call it in your scene's onUnload.
Luck (per player, set by the game)
-- on the authority
Gacha.setModifiers(player, { luck = 3 }) -- saved with the player's record
Gacha.setModifierSource(function(key) return { luck = MyTree.luckOf(key) } end) -- or derive it; wins over the saved value
The formula (gachaKit.rates.luckRates): with step s = luck.perLevel (0.10) and L = luck (clamped to luck.max, 10), every tier of rank r above the lowest gets its rate times 1 + s * L * (r - 1) / (T - 1) (T tiers): the top tier gains s·L of its rate (luck 5: x1.5, 0.6% to 0.9%), lower tiers proportionally less, and the lowest tier takes what is left so the rates still sum to 100. Pity and the guarantee work the same on the modified rates. The odds panel always shows the player's own modified numbers and says that luck is included.
Starting over
Gacha.reset(player) on the authority forgets a player's pity and collection; in the editor Gacha.reset() deletes your saved record and Gacha.reset("all") every saved record of the world.
How the odds are computed
- Per pull: a tier's rate (with luck); an item's rate is its tier's rate times its share of the tier (its weight over the tier's total weight).
- Your next pull:
rates.tierDist(banner, { c, g }): the top tier's chance is the base rate, plusramppoints for every pull fromsofton, and 1 athard; whenevery - 1pulls have passed without the guarantee tier or better, the tiers below it drop to 0 and their share goes to the tiers from it up to (not including) the top, in proportion to their rates. The rest of the probability is shared by the lower tiers in proportion to their rates. - With pity (long run): a top-tier result resets both counters, so pulls fall into independent cycles;
rates.effectivepropagates the exact distribution through one cycle and divides each tier's expected count by the expected cycle length. This is the number 100,000 simulated pulls converge to, and the test checks it does, for every tier and item. - The roll itself picks the tier and then the item through dropTablesKit's weighted
pick, from tables built from these same distributions.
Tests
gachaKitTests (12 tests): rarity styles, banner checks, pity distributions, base rates vs 100k pulls, long-run rates with pity vs 100k pulls, hard pity and the guarantee for an always-unlucky player, luck formula and 100k pulls at luck 5, odds panel numbers equal the roll's tables, duplicates (currency and upgrade), the authority refusing a player who lacks funds (and forged counts, banners and unknown machines) without changing their wallet or record, retries never charged twice and tickets paying first, pity per player and banner kept across a reloaded host with a forged record put back, per-player luck on the authority. tools.use("tests", "run", { suite = "gachaKitTests" }).
Known limits
- The authority runs on a player's machine (economyKit's bank machine, the lowest peer): Zero rooms have no dedicated server. A player alone in a world is their own authority, so a modified client playing alone can change its own pulls; in a shared room it cannot.
- The presentations are drawn as UI over the game (not 3D props in the world), so they look the same on every device and phone; a game that wants a 3D machine in its level opens the screen from its own prop (
Gacha.open). - Items without an
iconshow a token with their initials in the tier colour; give pool entriesicontextures for art. - The economyKit wallet display sits under the gacha backdrop while the screen is open; the screen shows the balances it needs itself.