IdleKit

Headless engine

A deterministic fixed-step loop, reactive state and typed events with zero browser dependency. Run it in a game, a test, or a server — the DOM is an optional add-on.

Gameplay mechanics

Producers, modifiers, collections, projects, crafting, boosts, containers, timers and pickups. Generic, serializable primitives — your game supplies the data, names and balancing.

Economy vocabulary

Explicit resources, costs, rewards, requirements, cost curves and atomic transactions. It reads your state through accessors and never owns it.

Engine policies

Autosave and offline progress compose with browser lifecycle bridges as opt-in extensions. One line each, no wiring ceremony.

Pluggable persistence

A tiny SaveAdapter contract with versioned saves and migrations. Memory and localStorage backends ship in the storage package.

Surgical DOM rendering

Declarative bindings that re-run only when the state keys they actually read have changed. No virtual DOM, no framework, no wasted writes.

TypeScript-first

Your state type flows through everything — systems, extensions, mechanics, saves. If it compiles, the wiring is right.

Ten lines to a running game

import { createEngine } from "@idlekitjs/core";
import { Renderer, bindText } from "@idlekitjs/dom";
import { createRafScheduler } from "@idlekitjs/browser/raf-scheduler";

interface State {
  coins: number;
}

const renderer = new Renderer();
const engine = createEngine<State>({
  initialState: { coins: 0 },
  renderer,
  scheduler: createRafScheduler(),
});

engine.addSystem((state, dt) => {
  state.coins += dt; // 1 coin per second
});

const coins = document.querySelector<HTMLElement>("#coins")!;
renderer.add(bindText(coins, () => Math.floor(engine.state.coins).toString()));

engine.start();

That is a complete game: a typed state, a deterministic simulation, and a DOM binding that only touches the page when the displayed value changes. IdleKit provides the engine — your game is what you build on top of it. Follow the quickstart to build it step by step.

The toolkit

Package	What it gives you
`@idlekitjs/core`	Headless engine: simulation loop, reactive state, events, saves, numbers, RNG
`@idlekitjs/dom`	DOM renderer and declarative bindings
`@idlekitjs/browser`	Browser bridges: page lifecycle, rAF scheduler, screen helpers
`@idlekitjs/economy`	Explicit resources, requirements, transactions, costs and rewards
`@idlekitjs/mechanics`	Producers, modifiers, collections, projects, crafting, boosts, containers, timers, pickups
`@idlekitjs/plugins`	Engine policies: autosave and offline progress
`@idlekitjs/storage`	Persistence backends: memory, localStorage
`@idlekitjs/types`	Shared contracts (`Extension`, `SaveAdapter`, `Binding`, ...)
`@idlekitjs/utils`	Pure helpers, platform-agnostic

Package

What it gives you

@idlekitjs/core

Headless engine: simulation loop, reactive state, events, saves, numbers, RNG

@idlekitjs/dom

DOM renderer and declarative bindings

@idlekitjs/browser

Browser bridges: page lifecycle, rAF scheduler, screen helpers

@idlekitjs/economy

Explicit resources, requirements, transactions, costs and rewards

@idlekitjs/mechanics

Producers, modifiers, collections, projects, crafting, boosts, containers, timers, pickups