guildhall/README.md

# Guildhall

A co-op idle game for a handful of friends. Everyone is an adventurer in the
same young frontier city: train skills Melvor-style (your character keeps
working for up to a day while you're away), supply the city council, and get
the city ready for bandit raids that arrive at times the game picks.

Alpha. One season, bandit raids plus two friendly events, six buildings.

## What's in it

- **Skills:** mining, woodcutting, farming, hunting, fishing, smithing,
  masonry, cooking, leatherworking, combat, plus the scout's reconnaissance.
- **Combat:** fights cost HP (less when out-levelled or armoured); below half
  health you eat food from your bank, and out of food you retreat, losing
  nothing but the fight. HP recovers 25% an hour.
- **Tiers:** six RuneScape-style tiers (copper, iron, steel, mithril,
  adamant, rune at levels 1–75) of ore, trees (up to magic) and hides (deer,
  boar and bear from hunting; green, blue and red dragonhide from fighting
  dragons). Every metal tier has a sword, shield, helmet, greaves, cuirass and
  five tools; every leather tier a cap, trousers and jerkin. Higher bars need
  coal; each metal past copper needs a Smithy level (rune needs level 5, so a
  city). Gear needs a combat level to wear, tools a skill level to use.
- **Classes:** warrior, scout, artisan, pioneer. Every class can train every
  skill; a class makes some skills 20% faster and has one signature ability.
- **Bank:** 12 slots of up to 1,000 each to start. When something doesn't
  fit it goes to the city stockpile (or the action stops, if you prefer).
  Raids never touch your bank. Players can give items to each other.
- **City:** each building collects its own fund, from players' banks or the
  city's stockpile and treasury. Funds are safe from raiders, and a funded
  building joins the construction queue by itself. Population eats food,
  pays taxes, and grows up to the housing cap; it promotes the settlement
  (hamlet, village at 40, town at 90, city at 150), which raises building
  level caps and gives everyone bank slots.
- **Events:** raids are announced a day or two ahead. Intel (spymaster's
  guild + scout reconnaissance) narrows down when, how strong, and finally
  where their camp is, so fighters can sabotage it. Defeat kills or drives
  off people, loots the stockpile and treasury, and may damage a building.
  Damaged buildings stop working until repaired but keep their level.

## Running

```sh
nix run . -- --dev --speed 60     # http://127.0.0.1:8098, time runs 60x
python3 -m unittest discover -s tests
```

Without `--dev` the server trusts the `Remote-User` header from the
authenticating proxy (Authelia). With `--dev` it reads a `gh_user` cookie
instead, so the dev bar can switch between players and fast-forward time.

The world is one JSON document in SQLite. `--backup-to DIR` writes a dated
snapshot and exits; the NixOS module runs it nightly when
`services.guildhall.backup.directory` is set.

## Layout

- `game.py`: content tables and the rules. Pure functions of `(world, now)`.
- `app.py`: stdlib HTTP server, persistence and the background ticker.
- `static/`: the client (vanilla JS, no build step).