inc
The one interface an idle or upgrade-shop game calls: `local Inc = require("incrementalKit.inc")`. `Inc.setup` takes the game's currencies, upgrades (cost curve, max level, effect on a stat or a generator's output per second, requirements, category, main or prestige shop), milest…
inc (incrementalKit)
The one interface an idle or upgrade-shop game calls: local Inc = require("incrementalKit.inc"). Inc.setup takes the game's currencies, upgrades (cost curve, max level, effect on a stat or a generator's output per second, requirements, category, main or prestige shop), milestones, stats and prestige rules. Then Inc.earn(currency, amount, source) credits with every multiplier, Inc.buy(id, 1 | 10 | 25 | "max") buys at the exact total price, Inc.stat(name) reads a stat summed from upgrades, milestones and prestige, Inc.prestigePreview() / Inc.prestige() reset for a permanent multiplier, Inc.idleRate() / Inc.claimOffline() handle idle and offline earnings, Inc.record(name, value) keeps bests, Inc.effectChange(id) says what the next level changes in real numbers ("Shove 3 -> 4 (+33%)"), upgrades sharing exclusive = "group" are a choice with Inc.respec(group) to undo it, and Inc.on(event, fn) listens to bought, earned, prestige, milestone, unlock, offline and respec. Progress is saved per player in their own data store and stays separate for every player in a multiplayer world. Inc.ui is the screens module.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2incrementalKit.inc: upgrades, prices, currencies, prestige, idle earnings, milestones and records for idle / incremental / upgrade-shop games, saved per player. local Inc = require("incrementalKit.inc") Inc.setup({ currencies = { coins = { name = "Coins", icon = "coin" }, shards = { name = "Shards", kind = "prestige" } }, upgrades = { { id = "power", name = "Stronger Push", baseCost = 10, curve = "exponential", effect = { stat = "pushPower", op = "add", perLevel = 1 } }, { id = "drone", name = "Coin Drone", baseCost = 50, produces = { currency = "coins", perSecond = 1 } }, }, prestige = { currency = "shards", from = "coins", formula = "sqrt", divisor = 1e6 }, }) Inc.earn("coins", 25, "distance") -- multipliers applied, returns what was credited Inc.buy("power", 10) -- x10 at the exact total price Inc.stat("pushPower") -- base + upgrades + milestones + prestige Each machine holds and saves its own player's progress only (in that player's own data store), so several players in one world each keep their own game. Call the kit on the machine of the player who earned or bought.
persistG( ) → void
now( ) → number
inPlay( ) → boolean
on(name: string, fn: (any) → void
Listen to an event (see Inc.EVENTS). fn receives a table describing it. Returns a handle for Inc.off.
| arg | type | description |
|---|---|---|
| name | string | |
| fn | (any |
off(h: any) → void
Stop listening (the handle Inc.on returned).
| arg | type | description |
|---|---|---|
| h | any |
emit(name: string, data: any) → void
| arg | type | description |
|---|---|---|
| name | string | |
| data | any |
bump( ) → void
rev( ) → number return rev end
A number that changes whenever anything the screens show changes (for a game's own UI to redraw on).
fillDefaults(t: any, d: any) → void
| arg | type | description |
|---|---|---|
| t | any | |
| d | any |
normCondition(c: any) → void
| arg | type | description |
|---|---|---|
| c | any |
normEffects(e: any) → void
| arg | type | description |
|---|---|---|
| e | any |
addUpgrade(u: any) → void
| arg | type | description |
|---|---|---|
| u | any |
addMilestone(m: any) → void
| arg | type | description |
|---|---|---|
| m | any |
setup(opts: any) → void
Configure the kit: currencies, upgrades, milestones, prestige, stats, offline, numbers, namespace. Re-callable; keeps the loaded profile.
| arg | type | description |
|---|---|---|
| opts | any |
config( ) → any return cfg end
The configuration setup was given (with defaults filled in).
need( ) → void
defineUpgrade(u: any) → void
Add or replace one upgrade after setup.
| arg | type | description |
|---|---|---|
| u | any |
defineMilestone(m: any) → void
Add or replace one milestone after setup.
| arg | type | description |
|---|---|---|
| m | any |
blankProfile( ) → any
savePath( ) → string
cardPath( ) → string
sget(path: string) → any
| arg | type | description |
|---|---|---|
| path | string |
sset(path: string, v: any) → void
| arg | type | description |
|---|---|---|
| path | string | |
| v | any |
hasIdentity( ) → boolean
migrate(rec: any) → any
| arg | type | description |
|---|---|---|
| rec | any |
_tryLoad( ) → void
save(_reason: string?) → void
Save now (it also saves by itself a few seconds after any change). Returns ok, error.
| arg | type | description |
|---|---|---|
| _reason | string? |
status( ) → string return status end
Load state: "idle", "memory" (no player identity yet, nothing saved), or "ready".
useStore(store: any?) → void
Swap the place progress is saved (tests, a second simulated profile): store = { get(path), set(path, v) } or nil for the player's own data. Reloads the profile from it.
| arg | type | description |
|---|---|---|
| store | any? |
memoryStore(id: string?) → any
A store that lives in memory (for tests and simulated players).
| arg | type | description |
|---|---|---|
| id | string? |
reset( ) → void
Wipe this player's progress (everything, prestige included) and start over.
profile( ) → any need
The raw saved profile (read only, please).
condOk(c: any) → boolean
| arg | type | description |
|---|---|---|
| c | any |
allOk(list: { any }) → boolean
| arg | type | description |
|---|---|---|
| list | { any } |
humanize(id: string) → string
Requirement text: every condition reads as a sentence a player understands ("Deepest dive: reach 250 m (best: 76 m)", "Upgrade Coin Drone to level 3 (now 1)"). A condition's own `text` / `label` wins: a string with {want}, {have} and {name} in it, or a function(have, want, name) -> string. Records, counters and stats take their display name and unit from setup{ records = { bestDepth = { name = "Deepest dive", unit = "m", goal = "Reach {want} deep" } } } (and `counters` / `stats` the same way); an id with no entry reads as words ("bestDepth" -> "Best depth").
| arg | type | description |
|---|---|---|
| id | string |
withUnit(n: number, unit: string?) → string
| arg | type | description |
|---|---|---|
| n | number | |
| unit | string? |
fillText(tpl: any, have: string, want: string, name: string, haveN: number, wantN: number) → string
| arg | type | description |
|---|---|---|
| tpl | any | |
| have | string | |
| want | string | |
| name | string | |
| haveN | number | |
| wantN | number |
defOf(kind: string, id: string) → any
| arg | type | description |
|---|---|---|
| kind | string | |
| id | string |
condProgress(c: any) → void
(have, want, sentence) for one condition
| arg | type | description |
|---|---|---|
| c | any |
say(haveN: number, wantN: number, name: string, unit: string?, default: string, goal: any?) → void
| arg | type | description |
|---|---|---|
| haveN | number | |
| wantN | number | |
| name | string | |
| unit | string? | |
| default | string | |
| goal | any? |
progressOf(conds: { any }) → any
Progress toward a list of conditions: { done, share (0..1), text } where text names the first unmet one.
| arg | type | description |
|---|---|---|
| conds | { any } |
applyEffect(acc: any, e: any, level: number) → void
| arg | type | description |
|---|---|---|
| acc | any | |
| e | any | |
| level | number |
aggregate( ) → any
prestigeMultiplier( ) → number
The prestige multiplier on every earning (1 before the first prestige).
stat(name: string) → number
A stat's value: (base + every "add") * every "mul"/"pct", then ^ every "pow", from upgrades, milestones and (for "earn") prestige.
| arg | type | description |
|---|---|---|
| name | string |
stats( ) → void
Every stat any upgrade, milestone or setup names, with its value.
multiplier(currency: string, source: string?) → number
The multiplier Inc.earn applies for a currency and source: earn * earn.<currency> * source.<source>.
| arg | type | description |
|---|---|---|
| currency | string | |
| source | string? |
walletChanged(currency: string, info: any?) → void
| arg | type | description |
|---|---|---|
| currency | string | |
| info | any? |
useWallet(currency: string, provider: any?) → void
Keep a currency's balance in an outside wallet: provider = { balance = fn(id) -> number, spend = fn(id, amount, reason[, done]) -> boolean, give = fn(id, amount, reason[, done]), whole = bool, async = bool, ready = fn() -> bool, subscribe = fn(onChange) -> unsubscribe, rev = fn() -> any }. An `async` provider answers through done(ok, info), info.text saying why it refused. nil hands the currency back to the kit's own profile.
| arg | type | description |
|---|---|---|
| currency | string | |
| provider | any? |
useEconomyKit(map: { [string]: string }, economy: any) → void
Keep the named currencies in economyKit wallets: map = { [incrementalKit currency] = economyKit currency }. `economy` is economyKit's `economy` module (the game requires it and passes it in). Gains go through Economy.grant (the game allows the reason "incrementalKit" in Economy.setup's clientGrants, with a max and perMinute that fit its biggest prestige gain), spends through Economy.spend, and both wait for the bank's answer: an upgrade bought with a bridged currency is granted only once the bank took the money ("bought"), a refusal fires "buyRefused" with the bank's reason, and the shown balance follows the wallet's balanceChanged events. Amounts are whole numbers (fractions wait until they add up to one). Returns the currencies it bridged.
| arg | type | description |
|---|---|---|
| map | { [string]: string } | |
| economy | any |
isReady( ) → boolean return type
balance(_id: string) → void
| arg | type | description |
|---|---|---|
| _id | string |
spend(_id: string, amount: number, reason: string?, cb: ((boolean, any) → void
Economy.spend and Economy.grant are requests to the bank: the answer comes through cb
| arg | type | description |
|---|---|---|
| _id | string | |
| amount | number | |
| reason | string? | |
| cb | ((boolean, any |
give(_id: string, amount: number, reason: string?, cb: ((boolean, any) → void
| arg | type | description |
|---|---|---|
| _id | string | |
| amount | number | |
| reason | string? | |
| cb | ((boolean, any |
rev( ) → void
the wallet record can also arrive through the shared store, which fires no event
walletOf(currency: string) → any
The outside wallet a currency uses, or nil when it is kept in the kit's own profile.
| arg | type | description |
|---|---|---|
| currency | string |
held(currency: string) → number return held
How much pending spends from an outside wallet hold back (0 when nothing is waiting).
| arg | type | description |
|---|---|---|
| currency | string |
isPending(id: string) → boolean return pendingBuys
Whether a purchase of this upgrade is waiting for its wallet's answer.
| arg | type | description |
|---|---|---|
| id | string |
currencies( ) → void
Every currency definition, in display order: { id, name, kind, icon, color }.
currency(id: string) → any need
A currency's definition.
| arg | type | description |
|---|---|---|
| id | string |
balance(id: string) → number
How much of a currency the player holds.
| arg | type | description |
|---|---|---|
| id | string |
earned(id: string) → void
Lifetime total of a currency earned (never goes down), and this run's total.
| arg | type | description |
|---|---|---|
| id | string |
owe(id: string, amount: number) → void
| arg | type | description |
|---|---|---|
| id | string | |
| amount | number |
walletGive(id: string, amount: number, source: string?) → void
Give to an outside wallet. What an authoritative wallet refuses or never answers is kept in the profile as owed and handed to it again a few seconds later, so a prestige gain is never lost.
| arg | type | description |
|---|---|---|
| id | string | |
| amount | number | |
| source | string? |
payOwed( ) → void
Hand what outside wallets are still owed (refused or unanswered gains) back to them.
walletOwed( ) → void
What outside wallets are still owed, { [currency] = n }: gains a wallet refused or never answered, given again every few seconds while playing.
credit(id: string, amount: number, source: string?, silent: boolean?, quiet: boolean?) → void
| arg | type | description |
|---|---|---|
| id | string | |
| amount | number | |
| source | string? | |
| silent | boolean? | |
| quiet | boolean? |
earn(currency: string, amount: number, source: string?) → number
Earn an amount with every multiplier applied (global, prestige, per currency, per source). Returns what was credited.
| arg | type | description |
|---|---|---|
| currency | string | |
| amount | number | |
| source | string? |
give(currency: string, amount: number, source: string?) → number
Add an amount with no multipliers (rewards, refunds, purchases from a store).
| arg | type | description |
|---|---|---|
| currency | string | |
| amount | number | |
| source | string? |
spend(currency: string, amount: number, reason: string?, cb: ((boolean, any) → void
Spend an amount if the player can afford it. Returns true when spent. A currency kept in an authoritative outside wallet (economyKit) is decided by the wallet later: it returns nil, "pending" and holds the amount until the answer; `cb(ok, info)` runs with it, "spent" fires on success and "spendRefused" { currency, amount, reason, code, text } on a refusal. Never treat "pending" as paid.
| arg | type | description |
|---|---|---|
| currency | string | |
| amount | number | |
| reason | string? | |
| cb | ((boolean, any |
finish(ok: boolean, info: any) → void
| arg | type | description |
|---|---|---|
| ok | boolean | |
| info | any |
available(currency: string) → number
What the player can spend now: the balance less what pending wallet spends hold back.
| arg | type | description |
|---|---|---|
| currency | string |
canAfford(currency: string, amount: number) → boolean
Whether the player can spend at least amount (pending wallet spends left out).
| arg | type | description |
|---|---|---|
| currency | string | |
| amount | number |
upgrade(id: string) → any need
An upgrade's definition.
| arg | type | description |
|---|---|---|
| id | string |
upgrades(filter: any?) → void
Every upgrade definition in order; filter = { shop = "main" | "prestige", category = "..." }.
| arg | type | description |
|---|---|---|
| filter | any? |
categories(shop: string?) → void
Categories of a shop, in first-seen order.
| arg | type | description |
|---|---|---|
| shop | string? |
level(id: string) → number need
An upgrade's level.
| arg | type | description |
|---|---|---|
| id | string |
excludedBy(d: any) → string
Whether an upgrade's requirements are met (it shows in the shop and can be bought).
| arg | type | description |
|---|---|---|
| d | any |
isUnlocked(id: string) → boolean
Whether an upgrade's requirements are met (it shows in the shop and can be bought). An upgrade whose exclusive group already has another upgrade bought is not unlocked.
| arg | type | description |
|---|---|---|
| id | string |
excludedBy(id: string) → string
The other upgrade of this upgrade's exclusive group the player owns (it locks this one), or nil.
| arg | type | description |
|---|---|---|
| id | string |
lockInfo(id: string) → any
Why an upgrade is locked, as the shop shows it: { locked, share (0..1), text, excludedBy }. The text is the first unmet requirement as a sentence, or 'You chose "X" instead' for an exclusive group.
| arg | type | description |
|---|---|---|
| id | string |
bulkCount(d: any, amount: any) → void
| arg | type | description |
|---|---|---|
| d | any | |
| amount | any |
quote(id: string, amount: any?) → any
What buying `amount` (1, 10, 25, ... or "max") of an upgrade would do: { count, cost, affordable, maxed, locked, level, nextLevel, currency }. "max" with nothing affordable prices one level.
| arg | type | description |
|---|---|---|
| id | string | |
| amount | any? |
cost(id: string) → number
Price of the next single level.
| arg | type | description |
|---|---|---|
| id | string |
buy(id: string, amount: any?) → void
Buy `amount` levels (1 by default, a number, or "max"). Returns ok, the quote (or the reason it failed: "locked", "maxed", "poor", "pending"). An upgrade priced in an authoritative outside wallet (economyKit) returns nil, "pending": its levels are granted ("bought") only once the wallet took the money, and a refusal fires "buyRefused" { id, count, cost, currency, code, text } instead.
| arg | type | description |
|---|---|---|
| id | string | |
| amount | any? |
grant( ) → void
setLevel(id: string, level: number) → void
Set an upgrade's level directly (debug, rewards). No cost.
| arg | type | description |
|---|---|---|
| id | string | |
| level | number |
effectText(id: string, levels: number?) → string
What one more level of an upgrade changes, as text: "+1 Push Power", "x2 Coins", "+1.5/s Coins".
| arg | type | description |
|---|---|---|
| id | string | |
| levels | number? |
statName(stat: string) → string
effectChange reads every stat and production rate an upgrade touches now and with `levels` more levels (all multipliers applied, by working the stats out again at the other level), so a shop can say "Shove 3 -> 4 (+12% push)".
| arg | type | description |
|---|---|---|
| stat | string |
atLevel(id: string, lvl: number, fn: () → void
| arg | type | description |
|---|---|---|
| id | string | |
| lvl | number | |
| fn | ( |
multish(stat: string) → boolean
| arg | type | description |
|---|---|---|
| stat | string |
effectChange(id: string, levels: number?) → void
What `levels` more levels of an upgrade (1 by default, capped at its max) change, as real numbers: a list of rows { kind = "stat" | "rate" | "label" | "preview", name, now, next, nowText, nextText, delta, text } where text reads "Shove 3 -> 4 (+12% push)". Stats and generator rates are worked out with every multiplier; an effect `label` becomes the bracket; the upgrade's own `preview(level, Inc)` adds a "preview" row (its text for this level -> the next).
| arg | type | description |
|---|---|---|
| id | string | |
| levels | number? |
read(k: any) → number
| arg | type | description |
|---|---|---|
| k | any |
fmt(v: number) → string
| arg | type | description |
|---|---|---|
| v | number |
effectChangeText(id: string, levels: number?, sep: string?) → string
effectChange as one line ("Shove 3 -> 4 (+12% push), Coins 5/s -> 6/s (+20%)"); `sep` joins the rows (", " by default).
| arg | type | description |
|---|---|---|
| id | string | |
| levels | number? | |
| sep | string? |
groupCfg(group: string) → any
Upgrades sharing `exclusive = "group"` are a choice: once one of them has a level the others lock ("You chose X instead"). setup{ exclusives = { group = { name, respecCost, respecCurrency, refund, respec = false } } } names the choice and prices a respec, which takes the chosen upgrade (and every upgrade built on it) back to level 0 and refunds `refund` (0..1, default 1) of what was paid for those levels.
| arg | type | description |
|---|---|---|
| group | string |
exclusiveGroup(group: string) → any
One exclusive group: { id, name, options = { upgrade ids }, chosen = id | nil, respec = { enabled, cost, currency, refund } }.
| arg | type | description |
|---|---|---|
| group | string |
exclusiveGroups( ) → void
Every exclusive group, in the order its first upgrade was defined.
respecQuote(group: string) → any
What a respec of an exclusive group would do: { can, reason ("none chosen" | "disabled" | "poor" | "pending"), group, chosen, cost, currency, resets = { ids }, refunds = { [currency] = amount } }.
| arg | type | description |
|---|---|---|
| group | string |
respec(group: string) → void
Respec an exclusive group: pay its respec price, take the chosen upgrade and everything built on it back to level 0, refund what the group's `refund` share says. Returns ok, the quote (or false and the reason). Fires "respec". With the price in an outside wallet it returns nil, "pending" and finishes once the wallet took the money.
| arg | type | description |
|---|---|---|
| group | string |
apply( ) → void
shopOptions(shop: string?) → any
A shop's options from setup{ shops = { [shop] = { layout = "list" | "tree", treeStyle = "columns" | "radial", categories } } }.
| arg | type | description |
|---|---|---|
| shop | string? |
idleRate(currency: string?) → number
Per-second production of a currency from every generator (all multipliers applied). With no currency, the first soft currency.
| arg | type | description |
|---|---|---|
| currency | string? |
idleRates( ) → void
Every currency's per-second production: { [id] = rate }.
computeOffline(away: number) → any
| arg | type | description |
|---|---|---|
| away | number |
offlinePending( ) → any
What is waiting from time away, or nil: { away, seconds (counted, after the cap), efficiency, capped, amounts = { [currency] = n } }.
claimOffline(mult: number?) → any
Collect the earnings from time away (times `mult`, e.g. 2 for a "double it" button the game pays for). Returns the amounts credited, or nil.
| arg | type | description |
|---|---|---|
| mult | number? |
simulateAway(seconds: number) → any
Test hook: pretend the player was away for `seconds` (as if they had just come back).
| arg | type | description |
|---|---|---|
| seconds | number |
record(name: string, value: number) → boolean
Keep the best value of a record (bestDistance, biggestCombo ...). Returns true when it is a new best.
| arg | type | description |
|---|---|---|
| name | string | |
| value | number |
best(name: string) → number need
The best value kept for a record (0 when none).
| arg | type | description |
|---|---|---|
| name | string |
count(name: string, delta: number?) → number
Add to a lifetime counter (runs, jumps, clicks ...). Returns the new count.
| arg | type | description |
|---|---|---|
| name | string | |
| delta | number? |
counter(name: string) → number need
A lifetime counter's value.
| arg | type | description |
|---|---|---|
| name | string |
milestones( ) → void
Every milestone with { def, done, at, progress = { share, text } }.
hasMilestone(id: string) → boolean need
Whether a milestone is reached.
| arg | type | description |
|---|---|---|
| id | string |
checkAll( ) → void
_check( ) → void
formulaGain(p: any, x: number) → number
| arg | type | description |
|---|---|---|
| p | any | |
| x | number |
prestigePreview( ) → any
What a prestige would give right now: { gain, basis (this run's earnings it is worked out from), next (earnings needed for one more point), multiplier, newMultiplier, resets = { currencies, upgrades }, can }.
prestige(force: boolean?) → void
Prestige: grant the preview's gain, reset the chosen currencies and upgrades and this run's totals. Returns ok, preview (or the reason).
| arg | type | description |
|---|---|---|
| force | boolean? |
prestiges( ) → number need
How many times the player prestiged.
format(n: number, style: string?) → string return N
Write a number in the current style (or `style`): Inc.format(1.5e9) -> "1.5B".
| arg | type | description |
|---|---|---|
| n | number | |
| style | string? |
setNumberStyle(style: string) → void
Switch how every number the kit shows is written: short, letters, scientific, engineering, words, si, myriad, kanji, grouped.
| arg | type | description |
|---|---|---|
| style | string |
numberStyles( ) → void
Every number style with its name and a sample.
card( ) → any
This player's public card (written beside the save for leaderboards): { name, prestiges, records, lifetime }.
cardOf(userId: string) → any
Another player's public card by user id (nil until they have played).
| arg | type | description |
|---|---|---|
| userId | string |
isMine(player: any) → boolean
Whether a player is the one this machine plays (the only one whose progress this machine may change).
| arg | type | description |
|---|---|---|
| player | any |
hostComponent( ) → string
_ensureHost( ) → void
Make sure the local host (ticking, saving, screens) exists. Play mode only.
_attach(id: string) → void
| arg | type | description |
|---|---|---|
| id | string |
_detach(id: string) → void
| arg | type | description |
|---|---|---|
| id | string |
_host( ) → string
The entity id of the host that ticks the kit (nil until play starts).
tick(dt: number) → void
Advance idle production and autosave by dt seconds (the host calls this every frame; call it yourself only without the host).
| arg | type | description |
|---|---|---|
| dt | number |
_sessionEnd( ) → void
_newSession( ) → void
Start a new play session with the last setup config: reload the profile, reset the screens and respawn the host. The kit calls this itself on entering play; a game never needs to.
__index(_t: ?, k: ?) → void
| arg | type | description |
|---|---|---|
| _t | ? | |
| k | ? |
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.