IdleKit

Appearance

Economy overview ​

@idlekitjs/economy is the headless vocabulary for economic actions in an IdleKit game: resources, accessors, amounts, requirements, transactions, cost curves and formatting view models.

ts
import { createEconomy, stateKey } from "@idlekitjs/economy";

What it is ​

Economy declares named scalar resources and moves amounts through explicit operations. It reads and writes the game state through accessors supplied by the game.

Use it when an action should be evaluated as one economic unit:

  • an upgrade with gates and costs;
  • a purchase with a scaling price;
  • a claim action with a reward;
  • a token activation;
  • a collect action that should fail cleanly when requirements are not met.

What it is not ​

Economy does not own game state. Resources read and write through accessors.

Economy is not the simulation loop, a scheduler, a renderer, a save backend or a gameplay mechanic. Continuous dt behavior stays in mechanics and game systems. Economy transactions are for explicit actions.

txt
Continuous production, timers, jobs and expiry -> mechanics or systems.
Atomic requirements + cost + reward + effect -> economy transactions.

How it composes with mechanics ​

Mechanics remain usable without Economy. Official bridges live beside the mechanic whose state shape they adapt:

txt
@idlekitjs/mechanics/producers/economy
@idlekitjs/mechanics/collections/economy
@idlekitjs/mechanics/containers/economy
@idlekitjs/mechanics/pickups/economy

Those adapters declare resources, requirements or transactions around an existing mechanic. The mechanic remains the source of truth for its own state.

Examples:

  • producers own production math; Economy can settle a multi-resource producer purchase;
  • containers own capacity math; Economy can gate a deposit with containerHasSpace;
  • pickups spawn temporary items; Economy can settle collection through collectPickup.

Spawning a pickup is not the same as granting a reward. A pickup can spawn without changing resources. The reward exists only when a collect transaction succeeds.

Basic flow ​

ts
import { createEconomy, stateKey } from "@idlekitjs/economy";

interface State {
  coins: number;
  upgrades: string[];
}

const economy = createEconomy<State>()
  .resource({ id: "currency:coins", label: "Coins", accessor: stateKey("coins") });

const upgrade = {
  id: "upgrade:stronger-clicks",
  cost: [["currency:coins", 100]],
  apply: (state: State) => {
    state.upgrades.push("stronger-clicks");
  },
};

const preview = economy.preview(state, upgrade);
if (preview.ok) {
  economy.execute(state, upgrade);
}

preview is pure. execute runs the same checks, then mutates only when the preview succeeds.