IdleKit

Appearance

@idlekitjs/economy ​

Headless economic primitives for IdleKit games: resources, accessors, amounts, requirements, transactions, cost curves and formatting view models.

What it provides ​

  • createEconomy and EconomyError.
  • Resource definitions: ResourceId, ResourceAccessor, ResourceInit and ResourceDef.
  • Accessor helpers: stateKey, arrayIndex, recordField, computed and readonly.
  • Amount helpers: normalizeAmounts, collectAmounts, mergeAmounts and scaleAmounts.
  • Requirement helpers: resourceAtLeast, resourceAtMost, allOf and not.
  • Transaction helpers and types: Transaction, previewTransaction and executeTransaction.
  • Cost curve helpers: costCurve, flat, geometric, geometricSum and geometricAffordable.
  • Formatting helpers and view models: formatAmount, formatCost, formatReward on the economy instance, plus describeFailure.

Public subpaths:

ts
import { createEconomy, stateKey } from "@idlekitjs/economy";
import { arrayIndex } from "@idlekitjs/economy/accessors";
import { costCurve, geometric } from "@idlekitjs/economy/cost-curves";

When to use it ​

Use Economy when a player or system action needs explicit economic settlement: requirements, costs, rewards, a state effect and UI diagnostics.

Typical actions include upgrades, purchases, claims, token activations and pickup collection. Continuous simulation belongs in mechanics or systems.

Basic usage ​

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 result = economy.execute(state, {
  id: "upgrade:stronger-clicks",
  cost: [["currency:coins", 100]],
  apply: (state) => {
    state.upgrades.push("stronger-clicks");
  },
});

Boundaries ​

@idlekitjs/economy does not own game state. Resource balances live in the game state and are read or written through declared accessors.

It does not schedule frames, advance dt, render UI, persist saves or replace gameplay mechanics.

Official mechanic bridges live under mechanic subpaths:

txt
@idlekitjs/mechanics/producers/economy
@idlekitjs/mechanics/collections/economy
@idlekitjs/mechanics/containers/economy
@idlekitjs/mechanics/crafting/economy
@idlekitjs/mechanics/pickups/economy
@idlekitjs/mechanics/projects/economy
@idlekitjs/mechanics/boosts/economy