Lithos

Lithos is a mobile-first roguelike civilization game. Lead one people from a fragile Stone Age hearth through the city-states of the Bronze Age and into a Classical civilization whose final ideals become its ending.

This repository contains a playable three-age prototype focused on consequential narrative choices, compact strategy, and progression between runs.

The run

Each turn follows a deliberate rhythm:

1. Collect resources, feed the population, grow, and advance active research.
2. Spend action points exploring, building institutions, or approaching rival civilizations.
3. Face a state-aware narrative event with visible locked alternatives.
4. Watch rival factions expand, trade, or test the frontier.

Research culminates in an age-defining discovery. Every project takes at least two collections; unused knowledge is banked in a bounded reserve, and switching projects retains progress. Between ages the frontier grows around the existing geography. Settled districts and their buildings endure, the capital changes, and cultural identity, tags, leaders, discoveries, construction methods, feats, and the civilization chronicle carry forward.

New players can follow a skippable Stone Age opening: inspect the food ledger, survey and claim a fertile district, research Survival, build a Gathering Site, and decide how to use the first harvest. The guided start provides a dependable nearby food district and a small food cushion; unguided starts keep the procedural opening.

Review the last turn's resource changes and frontier news from the map recap. Use the map's Key for discovered symbols and visible border risks, or Plan a discovery in Research to inspect a destination's prerequisites and alternative branches.

Roguelike legacy

Choices can accomplish feats. A feat provides an immediate reward to the current civilization and permanently unlocks an ancestral perk for later runs. Before starting another lineage, the player may equip up to two unlocked perks.

Examples include preserving the first flame, welcoming displaced people into a Bronze Age city, founding a citizen assembly, or carrying one civilization through all three ages. Perks alter starting resources, army capabilities, action points, or per-turn production, so later runs enable materially different strategies and event paths.

Current prototype content includes:

• Stone, Bronze, and Classical ages with distinct maps, buildings, research trees, factions, and narrative themes
• 41 state-aware story events, including cross-age consequences and a guided First Harvest
• 54 technologies across three branching trees (14 Stone, 18 Bronze, 22 Classical)
• Seven persistent feats and seven selectable ancestral perks
• Cultural identity, leader traits, civilization tags, and a readable run chronicle
• Resource economy, population growth/starvation, effective army stats, event combat, rival pressure, and diplomacy
• Versioned run saves plus separately persisted legacy progression

Architecture

• Content registry — age packages expose definitions, technologies, events, and starting settlements through src/data/content.ts.
• Pure domain engines — turn, resource, event-choice, combat, rival, age, and run generation logic live under src/logic.
• Commands — dispatchCommand validates actions atomically, resolves automatic phases, enforces defeat, and queues persistent outcomes. React only requests actions and acknowledges messages.
• Run state — Zustand stores one saveable run; Zod and semantic checks validate versioned saves, with retained backups and visible storage failures.
• Legacy state — a separate Zustand store persists feats, perks, run history, victories, and the furthest age across run resets.
• Presentation — React renders narrative/UI overlays while Phaser renders and handles the hex map. Zustand is their shared boundary.
• Determinism — the run persists its random cursor and pending results, so reloading does not reroll outcomes or repeat their rewards.

Development

Requires Node.js 20 or newer.

npm install
npm run dev
npm test
npm run build

The test suite covers hex math, resources, turns, research, events, choice resolution, combat, rivals, age transitions, the three-age content registry, and roguelike perk/feat behavior.

See Milestone 1 implementation notes for command rules, save migration/recovery, and verification coverage.

See Milestone 2 for research, economy and age inheritance, and the Stone Age vertical slice / Milestone 3 for onboarding, UI changes, playthrough findings and remaining acceptance checks.

Prototype scope

The three-age arc is complete and winnable. The broader design still leaves room for later historical ages, more event chains and endings, deeper rival diplomacy, audio/animation, accessibility passes, and mobile-store packaging.