Jev Civilizations

https://thunder-monocle.env-ca.veilstreamapp.com/

Jev Civilizations is a small strategy game where four tribes run their own lives and you can only change the world around them.

• Pick a tribe to support. Farmers, hunters, mountain fishers, or raiders — each lives off the land differently.
• You never give orders. Instead, every other turn you choose how the environment changes: a wet spring, a harsh winter, a wildlife boom, a crop pest. On the turns in between, Nature picks at random.
• The tribes decide for themselves. Each turn an AI model,Jev , chooses one action for every tribe from the moves that are actually possible for it — farm, hunt, build, research, move, scout for new land, found a new settlement, or raid a neighbour.
• A game engine works out what happens. Harvests, hunger, births, raids, and growing or shrinking borders are all calculated by ordinary game rules, and the map changes to show it.
• See why things happened. A decision inspector shows exactly what Jev was told and how strongly it preferred each option, and an event log explains every result.
• The best civilization wins. After the match (10–200 turns, 50 by default), tribes are ranked by population, resilience, technology, and territory.

No API key? The app also has a clearly labelled mock mode that uses a simple built-in policy instead of Jev, so you can play and develop offline.

• Next.js 16 (App Router) + React 19 + TypeScript (strict), exact versions pinned in package-lock.json

• Pure TypeScript game engine in lib/game/ (no DOM, database, or network)

• Server-only Jev adapter in lib/server/jev/ — the only external call the app makes

• Local SQLite through Node's built-in node:sqlite (no native build step, no hosted database)

• Canvas 2D map, locally drawn SVG art, system fonts; no remote assets, analytics, or telemetry

• Node.js 24 or newer (developed on 26.5;node:sqlite is built in)

• npm 11

• A persistent, writable directory for the SQLite file

• A TypeSafe API key for live play (optional for the clearly labeled mock mode)

The default deployment is a single persistent Node server with a writable volume. Ephemeral serverless filesystems and multi-instance deployments are not supported (SQLite state and turn leases live on one disk).

npm install
cp .env.example .env.local

Environment variables (see .env.example):

Nothing to run by hand. On first use the server creates DATABASE_PATH (and its directory) and applies the schema migrations in lib/server/migrations.ts. Migrations are append-only and versioned in schema_migrations.

npm run dev          # development server on http://localhost:3000
npm run build        # validates the content catalog, then builds
npm start            # production server (PORT/-p to change the port)

Set APP_ORIGIN to the exact origin players use (for example https://civ.example.com), otherwise mutations from the browser are rejected as cross-site.

With ALLOW_MOCK_MODE=true, the start screen offers Mock simulation. Decisions then come from a deterministic local test policy (lib/game/mockPolicy.ts), never from Jev. Mode is chosen when a game is created and persisted; mock games are labeled "MOCK SIMULATION" in the header, inspector, results, replays, and exports. A live game never switches to mock. If live Jev is unavailable, the turn s with Retry and Return to menu.

docker build -t jev-civilizations .
docker run -p 3000:3000 -v jevciv-data:/data \
  -e TYPESAFE_API_KEY=... -e APP_ORIGIN=http://localhost:3000 jev-civilizations

The Dockerfile has not been verified in this environment (Docker was not installed during development).

npm run typecheck
npm run lint
npm test                      # Vitest: engine, content catalog, Jev adapter (local HTTP stub), orchestration, routes
npx playwright install chromium   # once
npm run build && npm run test:e2e # Playwright browser tests against `next start` with an in-process Jev fake
npm run simulate -- --games 100 --turns 50   # balance smoke run with the MOCK policy (not Jev)
npm run validate:catalog
npm run check:secrets             # after a build: scans bundles, committable files, and the DB for the key
npm run probe:jev                 # optional: ONE real Jev request (uses your key; small cost)

No test in npm test or npm run test:e2e contacts the real API. Adapter tests route the fixed endpoint to a local HTTP stub; browser tests preload tests/e2e/stub-fetch.mjs, which answers the fixed endpoint in-process.

• Export : the header'sExport button (orGET /api/games/:id/export ) downloads JSON with every turn's exact Jev request (without the Authorization header), validated output, attempts, usage, outcomes, and state hashes. Exports never include keys, cookies, session IDs, or database paths.
• Replay :Replay match (or/game/:id/replay ) steps through recorded map deltas, events, and decisions. Replays make no model calls and are labeled REPLAY.verifyReplay() inlib/server/replay.ts re-runs the engine from the recorded initial state and recorded choices and checks every post-turn state hash (covered by tests).
• A new match on the same seed reproduces the same initial world but is a new live run, not a replay.

All state is in the SQLite file at DATABASE_PATH (WAL mode, so also -wal/-shm files while running).

node -e "const {DatabaseSync}=require('node:sqlite');new DatabaseSync(process.argv[1]).exec(\"VACUUM INTO '\"+process.argv[2]+\"'\")" data/jevciv.sqlite backup.sqlite

Players keep access through their anonymous session cookie; restoring the database restores their matches. A complete 50-turn game uses about 4 MB of storage (turn records, map changes, and a full snapshot every ten turns).

app/                 pages (/, /game/[id], /game/[id]/replay) and same-origin API route handlers
components/          start screen, Canvas map, event card, scoreboard, inspector, results, replay
content/             authored catalog: tribes, events (32×3), actions, technologies, balance, narration, help
lib/game/            pure engine: world generation, candidates, resolution, effects, economy, scoring, views
lib/server/          config, SQLite, sessions, limits, Jev adapter, turn orchestration, replay/export
lib/client/          browser API client, world decoding, game controller hook
scripts/             catalog validation, balance simulation, live probe, secret scan
tests/               engine, content, server (stub Jev), e2e (Playwright)
public/art/          local SVG emblems and illustrations

Released under the MIT License (see LICENSE), © 2026 Steven Jones. Third-party packages are used under their own licenses (see THIRD_PARTY_NOTICES.md).

This project is not affiliated with or endorsed by TypeSafe. Live play uses your own TypeSafe API key, and you are responsible for its terms and costs. Game content is fiction. See DISCLAIMER.md for details, SECURITY.md to report vulnerabilities and for key handling, and CONTRIBUTING.md to contribute.