gacha
The one module a game uses: `require("gachaKit.gacha")`. Setup, banners (`defineBanner`), pulls (`pull(banner, count, cb)` asks the authority), the odds the panel shows (`odds`), the local player's pity, collection and history, events (`on`: pull, new, duplicate, refused, ...), c…
gacha
The one module a game uses: require("gachaKit.gacha"). Setup, banners (defineBanner), pulls (pull(banner, count, cb) asks the authority), the odds the panel shows (odds), the local player's pity, collection and history, events (on: pull, new, duplicate, refused, ...), currency adapters for money that is not an economyKit currency (setCurrency), per-player luck on the authority (setModifiers, setModifierSource), grants and gifts on the authority, and the screen (open, close, setPresentation, setLook). It wires the authority to economyKit's bank and the "gachaKit" multiplayer channel, and starts GachaHost by itself.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2strict
bump( ) → void
_rev( ) → number return S
now( ) → number
inPlay( ) → boolean
online( ) → boolean
myPeer( ) → number
cfg( ) → any
on(event: string, fn: (any) → void
Listen to an event: "pull" (every answered pull: { banner, results, paid }), "new" (an item the player did not own: { item, tier, name, banner }), "duplicate" ({ item, tier, dup }), "refused" ({ code, text, banner }), "state" (the player's record changed), "open" / "close" (the gacha screen), "revealed" (one result shown by the presentation), "ready" (the authority answered for the first time). "host.<event>" hears the authority's own events on its machine ("host.pull", "host.refused", "host.tamper"). Returns a function that stops listening.
| arg | type | description |
|---|---|---|
| event | string | |
| fn | (any |
emit(event: string, info: any) → void
| arg | type | description |
|---|---|---|
| event | string | |
| info | any |
setup(opts: any?) → any
Set the kit up; every machine calls it with the same options (a scene's onLoad). opts: presentation (capsuleMachine, cardPack, eggHatch, treasureChest, starPortal, clawMachine), look (cartoon, neon, pixel, fantasy), ns (save namespace), save (copy the player's collection into their saveKit profile), sound, juice, revealSpeed (1 = normal), insets ({ left, top, right, bottom } points kept clear for the game's HUD), currencies ({ { id, name, icon, start, color } } economyKit currencies to define if the game has not: tickets and shards, say), economy (options passed to Economy.setup when the game has not set economyKit up itself).
| arg | type | description |
|---|---|---|
| opts | any? |
config( ) → any return copy
_checkPresentation(p: any) → void
| arg | type | description |
|---|---|---|
| p | any |
_checkLook(l: any) → void
| arg | type | description |
|---|---|---|
| l | any |
setPresentation(p: string) → void
Every pull's presentation from now on: capsuleMachine, cardPack, eggHatch, treasureChest, starPortal or clawMachine.
| arg | type | description |
|---|---|---|
| p | string |
setLook(l: string) → void
The look of every gacha screen: cartoon, neon, pixel or fantasy.
| arg | type | description |
|---|---|---|
| l | string |
setInsets(ins: any) → void
| arg | type | description |
|---|---|---|
| ins | any |
defineBanner(def: any) → any
Define (or replace) a banner; every machine defines the same banners (the authority uses its own copy, so a player's machine cannot change prices or odds). def: { id, title, description, style ("classic" | "stars" | "gems" | "metals"), rates ({ [tier] = percent } summing to 100; the style's defaults otherwise), pool ({ { item, tier, weight?, name?, icon?, kind?, description? } }), cost ({ currency, amount } per pull), cost10 (optional price of a ten-pull), ticket (optional { currency, amount } per pull, used first when the player has enough), counts ({ 1, 10 }), pity ({ soft, hard, ramp } or false; default soft 75, hard 90, ramp 6 points), guarantee ({ every = 10, tier } or false; default: the tier below the top every 10), duplicates ({ mode = "currency" | "upgrade", currency = "shards", amounts = { [tier] = n }, maxLevel = 5 }), luck ({ perLevel = 0.10, max = 10 }), presentation, look, art ({ color, accent }) }. Returns the checked banner.
| arg | type | description |
|---|---|---|
| def | any |
removeBanner(id: string) → void
| arg | type | description |
|---|---|---|
| id | string |
banners( ) → void
The banners in the order they were defined: { { id, title, ... } }.
banner(id: string) → any
One banner as defined (checked and filled with defaults), or nil.
| arg | type | description |
|---|---|---|
| id | string |
setCurrency(id: string, adapter: any) → void
Let a currency that is not an economyKit currency pay for pulls or take duplicate refunds (big-number idle-game money, say). Call on every machine with the same id. adapter: { name, icon, color, spend = fn(key, amount, reason, peer) -> ok, text? (authority only), grant = fn(key, amount, reason, peer) -> ok, text? (authority only), balance = fn(key) -> number (authority), localBalance = fn() -> number (the local player's balance, for the screens), format = fn(n) -> string? }. A currency with no adapter goes through economyKit's bank.
| arg | type | description |
|---|---|---|
| id | string | |
| adapter | any |
currencyAdapter(id: string) → any
| arg | type | description |
|---|---|---|
| id | string |
balance(cur: string) → number
The local player's balance of a currency (adapter's localBalance, else economyKit's wallet).
| arg | type | description |
|---|---|---|
| cur | string |
currencyName(cur: string) → string
A currency's display name.
| arg | type | description |
|---|---|---|
| cur | string |
formatAmount(cur: string, n: number) → string
An amount of a currency as text ("1,250", or the adapter's own format).
| arg | type | description |
|---|---|---|
| cur | string | |
| n | number |
moveAll(kind: string, key: string, costs: { [string]: number }, reason: string, peer: number?) → any
the authority's debit/credit, routed per currency
| arg | type | description |
|---|---|---|
| kind | string | |
| key | string | |
| costs | { [string]: number } | |
| reason | string | |
| peer | number? |
setModifiers(player: any, mods: any) → any
On the authority: set a player's modifiers, saved with their record. mods: { luck = n } (0..the banner's luck.max; each level raises the higher tiers by the documented formula in gachaKit.rates.luckRates). `player` is a peer id, an account key ("u:<id>"), an avatar or nil (the local player).
| arg | type | description |
|---|---|---|
| player | any | |
| mods | any |
setModifierSource(fn: ((string) → void
On the authority: let the game compute modifiers itself, fn(key) -> { luck = n } (read from its upgrade tree, say). Asked on every pull; what it answers wins over setModifiers.
| arg | type | description |
|---|---|---|
| fn | ((string |
modifiers( ) → any
The local player's modifiers as the authority last told them ({ luck = n }).
odds(bannerId: string, opts: any?) → any
Everything the odds panel shows for a banner, for the local player (or for `state` / `luck` given): { banner, luck, tiers = { { id, name, color, rate (percent, per pull before pity), longRun (percent with pity), next (percent on this player's next pull), dup } }, items = { { item, name, tier, share (within tier), rate, longRun, next } }, rules = { lines }, pity = { c, g, toHard, soft, hard, guarantee } }.
| arg | type | description |
|---|---|---|
| bannerId | string | |
| opts | any? |
pity(bannerId: string) → any
The local player's pity counters on a banner: { c = pulls since the top tier, g = pulls since the guaranteed tier or better, n = pulls on this banner }.
| arg | type | description |
|---|---|---|
| bannerId | string |
collection(player: any?) → void
A player's collection: { [item] = { n = how many pulled, lv = level, tier, banner, at } }. With no argument, the local player's (as the authority last sent it); on the authority any player's (a peer id, account key or avatar).
| arg | type | description |
|---|---|---|
| player | any? |
owns(item: string) → void
Whether the local player owns an item, and its level.
| arg | type | description |
|---|---|---|
| item | string |
history( ) → void
The local player's last pulls, newest first: { { item, tier, banner, at } }.
progress(bannerId: string) → void
How many of a banner's items the local player owns: owned, total.
| arg | type | description |
|---|---|---|
| bannerId | string |
isReady( ) → boolean return S
key( ) → string
hostPeer( ) → number
The machine that decides pulls: economyKit's bank machine.
isHost( ) → boolean
Whether this machine is the authority (and its host is running).
_keyOfTarget(t: any) → string
| arg | type | description |
|---|---|---|
| t | any |
storeNs( ) → string
hostEnv( ) → any
keyOf(peer: number) → void
| arg | type | description |
|---|---|---|
| peer | number |
nameOf(peer: number) → void
| arg | type | description |
|---|---|---|
| peer | number |
send(peer: number, msg: any) → void
| arg | type | description |
|---|---|---|
| peer | number | |
| msg | any |
debit(key: string, costs: any, reason: string) → void
| arg | type | description |
|---|---|---|
| key | string | |
| costs | any | |
| reason | string |
credit(key: string, costs: any, reason: string) → void
| arg | type | description |
|---|---|---|
| key | string | |
| costs | any | |
| reason | string |
banner(id: string) → void
| arg | type | description |
|---|---|---|
| id | string |
now( ) → void
modsOf(key: string) → void
| arg | type | description |
|---|---|---|
| key | string |
emit(event: string, info: any) → void
| arg | type | description |
|---|---|---|
| event | string | |
| info | any |
_hostRng( ) → void
The authority's random source: dropTablesKit's seeded generator, seeded from this machine's clocks and peer id when the authority starts, so no player can predict it.
becomeHost( ) → void
stopHost( ) → void
_pushState(key: string) → void
tell a player (on the authority) that their record changed outside a pull
| arg | type | description |
|---|---|---|
| key | string |
_peers( ) → void
deliver(peer: number, msg: any) → void
| arg | type | description |
|---|---|---|
| peer | number | |
| msg | any |
toHost(msg: any) → void
| arg | type | description |
|---|---|---|
| msg | any |
route(from: number, env: any) → void
| arg | type | description |
|---|---|---|
| from | number | |
| env | any |
listen( ) → void
processInbox( ) → void
setRec(rec: any, key: string?) → void
| arg | type | description |
|---|---|---|
| rec | any | |
| key | string? |
clientReceive(msg: any) → void
| arg | type | description |
|---|---|---|
| msg | any |
pull(bannerId: string, count: number?, cb: ((any) → void
Pull `count` (1 or 10, as the banner allows) on a banner: the request goes to the authority, which takes the price and rolls. cb(info) gets { banner, results = { { item, tier, rank, name, new, dup, pity, top } }, paid, pity } or { ok = false, code, text }. Returns the request id. The open gacha screen plays the presentation for the answer.
| arg | type | description |
|---|---|---|
| bannerId | string | |
| count | number? | |
| cb | ((any |
busy( ) → boolean
Whether a pull of the local player is waiting for the authority.
canAfford(bannerId: string, count: number) → void
Whether the local player can pay for `count` pulls now (tickets or the banner's currency), and the price that would be taken: ok, costs, label.
| arg | type | description |
|---|---|---|
| bannerId | string | |
| count | number |
grant(player: any, currency: string, amount: number, reason: string?) → any
On the authority: give a player currency (tickets earned in a level, say). Goes through the currency's adapter or economyKit's bank.
| arg | type | description |
|---|---|---|
| player | any | |
| currency | string | |
| amount | number | |
| reason | string? |
give(player: any, bannerId: string, item: string) → any
On the authority: put an item in a player's collection outside a pull (a quest reward).
| arg | type | description |
|---|---|---|
| player | any | |
| bannerId | string | |
| item | string |
reset(player: any?) → any
Start a collection and pity over. On the authority: any player (or "all" in the editor deletes every saved record of this world). In the editor with no argument: your own saved record.
| arg | type | description |
|---|---|---|
| player | any? |
open(bannerId: string?, opts: any?) → boolean
Open the gacha screen on a banner (nil: the first banner). opts: presentation, look (this opening only), tab ("pull" | "odds" | "collection"). Returns false when there is no such banner.
| arg | type | description |
|---|---|---|
| bannerId | string? | |
| opts | any? |
close( ) → void
isOpen( ) → boolean return S
_open( ) → any
_queue( ) → void
_attach(id: string) → void
| arg | type | description |
|---|---|---|
| id | string |
_detach(id: string) → void
| arg | type | description |
|---|---|---|
| id | string |
_ensureHost( ) → void
Make sure this machine's GachaHost (UI, input, network) exists. Called by every call that needs it.
retryPending( ) → void
mirrorToSave(dt: number) → void
| arg | type | description |
|---|---|---|
| dt | number |
_tick(dt: number) → void
Run one frame (GachaHost calls this): follow the authority, pass messages, retry, keep the saveKit copy.
| arg | type | description |
|---|---|---|
| dt | number |
_reset( ) → void
Forget everything this machine knows (tests; a new play session).
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.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ 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".
Scoped to this part · feeds back into the world's score.