Economy adapters

Economy adapters are official bridges between @idlekitjs/economy and implemented mechanics.

They are optional and subpath-only:

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

They are not exported by the @idlekitjs/mechanics barrel and they do not live under @idlekitjs/economy/adapters.

Boundary

Economy is domain-free: it knows resources, amounts, requirements, transactions, formatting and cost curves. It does not know producer columns, card entries, container contents, pickup items, recipe bags, projects or boost timers.

Each adapter lives beside the mechanic whose state shape it adapts. Core mechanic modules remain usable without Economy.

Producers

import {
  economyPurchase,
  producerOutput,
  producerPurchase,
  producerResourceId,
  producerResources,
} from "@idlekitjs/mechanics/producers/economy";

Export	Role
`producerResourceId`	`producer:<id>` id convention.
`producerResources`	Declare one resource per producer tier, backed by `total[index]`.
`producerOutput`	Bridge an Economy resource into the producers `resource` seam.
`economyPurchase`	Implement the scalar producers purchase seam through Economy.
`producerPurchase`	Build a composite producer purchase transaction from a `CostCurve`.

Use economyPurchase for single-scalar tier purchases. Use producerPurchase when a producer purchase has multi-resource costs or extra requirements.

const purchase = economyPurchase(economy, (index) =>
  index === 0 ? "currency:coins" : producerResourceId(PRODUCERS[index - 1].id),
);

producerPurchase grants through producers.grant(index, state, quantity, { owned: true }), so the producer purchase count advances after the transaction has paid.

Collections

import {
  cardLevelAtLeast,
  cardLevelBelow,
  cardLevelResourceId,
  cardResources,
  cardShardResourceId,
  hasCardShards,
} from "@idlekitjs/mechanics/collections/economy";

Export	Role
`cardShardResourceId`	`card:<id>:shards`.
`cardLevelResourceId`	`card:<id>:level`.
`cardResources`	Declare writable shard and read-only level resources.
`cardLevelAtLeast`	Requirement over the read-only level.
`cardLevelBelow`	Requirement for "not maxed" gates.
`hasCardShards`	Non-consuming shard requirement.

cardResources declares two resources per card. Shards are writable integer resources. Levels are read-only integer resources. Collection upgrades remain owned by the collections mechanic or by explicit game code in a transaction apply.

Containers

import {
  containerContentResources,
  containerFreeSpaceResource,
  containerHasSpace,
} from "@idlekitjs/mechanics/containers/economy";

Export	Role
`containerHasSpace`	Requirement that an amount of content fits now.
`containerContentResources`	Expose container content amounts as writable resources.
`containerFreeSpaceResource`	Expose free capacity as a read-only resource.

Containers stay the source of truth for capacity and contents. Economy can observe and trade the same numbers.

Gate deposits with containerHasSpace before crediting a content resource. containerContentResources credits go through the all-or-nothing fill operation.

import { collectPickup } from "@idlekitjs/mechanics/pickups/economy";

const collectScrap = collectPickup(pickupsExt, {
  itemId: "scrap#1",
  requirements: [containerHasSpace(bin, "scrap-bin", "scrap", 1)],
  apply: (state) => {
    bin.fill(state, "scrap-bin", "scrap", 1);
  },
});

Crafting

import {
  amountsToBag,
  bagToAmounts,
  craftingResources,
  recipeCost,
  recipeReward,
} from "@idlekitjs/mechanics/crafting/economy";

Export	Role
`craftingResources`	Declare `ResourceBag` entries as Economy resources.
`bagToAmounts`	Convert a `ResourceBag` to amount lines.
`amountsToBag`	Convert amount lines back to a `ResourceBag`.
`recipeCost`	Recipe inputs as `Cost`.
`recipeReward`	Recipe outputs as `Reward`.

Crafting keeps the job lifecycle: start consumes inputs, cancel refunds or discards inputs, and update credits completed outputs. The adapter exposes the same stock for Economy formatting and transactions.

const economy = createEconomy<State>().resources(
  craftingResources(["ore", "coal", "iron"], {
    getResources: (state) => state.resources,
    setResources: (state, resources) => {
      state.resources = resources;
    },
  }),
);

Pickups

import { collectPickup, pickupAvailable } from "@idlekitjs/mechanics/pickups/economy";

Export	Role
`pickupAvailable`	Requirement that the item exists and is ready.
`collectPickup`	Transaction for a pickup collect action.

Pickups spawn temporary items. Rewards are credited only when a collect transaction succeeds.

const result = economy.execute(
  state,
  collectPickup(pickupsExt, {
    itemId: "coin#4",
    reward: [["currency:coins", 25]],
  }),
);

Extra requirements can gate collection, for example requiring container space before taking the pickup.

Projects

import { projectFromTransaction } from "@idlekitjs/mechanics/projects/economy";

projectFromTransaction(economy, transaction, options) wraps an Economy transaction as a Project<T>.

Project field	Mapping
`id`	`transaction.id`
`affordable`	`economy.canExecute(state, transaction)`
`effect`	`economy.execute(state, transaction)`
`cost`	Formatted transaction cost unless overridden
`trigger`	`options.trigger` or always visible
`repeatable`	`options.repeatable`

Projects keep completed, repeatable and trigger behavior. Economy supplies the action's affordability, execution and cost formatting.

Boosts

import { activateBoost, boostTokenResourceId } from "@idlekitjs/mechanics/boosts/economy";

Export	Role
`boostTokenResourceId`	`boost-token:<id>` token convention.
`activateBoost`	Transaction that spends a token and calls `boosts.grant`.

The usual pattern is:

Declare a token resource in your game state.
Credit the token as a reward.
Execute activateBoost to spend the token.
Let boosts own timer expiry, stacking and modifier publication.

const result = economy.execute(
  state,
  activateBoost(boostsExt, { boostId: "double-production" }),
);

Economy adapters ​

Boundary ​

Producers ​

Collections ​

Containers ​

Crafting ​

Pickups ​

Projects ​

Boosts ​

Related ​