idlegame/docs/architecture.md

Architecture

Idlegame is split into four layers.

Engine

src/engine/ contains deterministic gameplay logic:

• tickLoop.ts: fixed-timestep accumulator. Large elapsed deltas, including offline catch-up, drain through the same tick path as active play.
• game.ts: core game state, action queue, costs/unlocks on start, completion-driven queue advancement (actions do not auto-repeat when the queue is empty).
• save.ts: versioned save schema, serialized export/import strings, and offline elapsed calculation.
• num.ts: branded numeric boundary and human-readable formatting.

The engine must stay pure. It does not import React, Zustand, browser APIs, storage, requestAnimationFrame, or Date scheduling.

Content

src/content/ contains authored definitions validated by Zod. M0 includes one resource and one timed action. M1 expands this into real resources, actions, story nodes, automation unlocks, and prestige definitions.

State

src/state/ owns environment coupling:

• persistence backend selection: IndexedDB via idb-keyval, with localStorage fallback
• load-on-boot and autosave orchestration
• requestAnimationFrame loop and lifecycle hooks
• mapping engine state to view models
• Zustand store updates for React

UI

src/ui/ renders the view model and calls runtime commands. Components should not implement gameplay rules. The M0 shell includes a resource readout, action panel, progress bar, and event log.

Verification

Run the full local gate before pushing:

pnpm typecheck
pnpm lint
pnpm test:coverage
pnpm build

Rendered checks for the walking skeleton:

• app loads without framework overlay or console errors
• starting the timed action increments Gold after completion
• reload preserves saved state
• reopening after time away credits offline progress