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,
  construction (with masonry), cooking, leatherworking, herblore, combat,
  prayer and reconnaissance. Smiths also make hardware for builders, one kind
  per metal (copper rivets to rune locks), which fittings and buildings need.
- **Combat:** every fight is played out swing by swing: you and the enemy
  each have HP, a swing timer, accuracy and a max hit, and swings hit, miss
  or crit (power from level and gear aims and hits; armour dodges and soaks).
  Below half health you eat from your bank; out of food you retreat, losing
  nothing but the fight. HP recovers 25% an hour. The Combat page replays
  the fight live. Fights are split into the Frontier (bandits, sabotage,
  drilling, the city's troubles) and expeditions: Greenwood to start, then
  one area per tier (Old Watchtower, Sunken Barrows, Iron Hills, Frostpeak,
  Dragon's Spine), each with a golem, a troll, a spirit and a flyer that drop
  rare trophies (3%, 6% from bosses) for stronger weapons, and a boss (the
  dragons at the top). Each kill is followed by a 2-second pause.
- **Weapons:** four styles, one per trade, and anyone can use any of them.
  Sword and shield (2.4s swings, the shield blocks 15% of hits; swords from
  Smithing, shields from Construction), warhammer (Smithing; slow, heavy,
  twice the crits), staff (Herblore; accurate, ignores armour) and bow
  (Leatherworking; fast, strikes first). The last three take both hands and
  carry a shield's power. Your trade's weapon does 15% more damage. Golems
  break under hammers, trolls fall to swords, spirits only fear staves, and
  flyers fall to bows. Past copper, each weapon needs its tier's trophies.
- **Tiers:** six RuneScape-style tiers (copper, iron, steel, mithril,
  adamant, rune at levels 1–75) of ore, trees (up to enchanted) 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 are trades,** from gathering to finished goods, so each player has
  a quiet gathering side and a busier crafting side: miner (mining, smithing),
  builder (woodcutting, construction), homesteader (farming, cooking,
  herblore) and ranger (hunting, fishing, leatherworking, cooking). A trade's
  skills are 20% faster, 1 in 10 of its crafts make double, and each has one
  bonus of its own. Homesteaders farm differently: two plots, either one crop
  30% faster or two crops at once sharing a 20% faster pace. Every class can train every skill, scout and drill.
  Building costs draw on all four trades: thatch, flax for rope, hide glue,
  leather and provisions as well as wood, stone and metal.
- **Bank:** 12 slots of 1,000 each to start; more than a stack of one item
  spills into another slot. 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, then rises by labour:
  players working the site with Construction (more labour per action every
  20 levels, faster with a hammer), plus a slow trickle from the townsfolk.
  Construction also saws planks, which higher building levels need, and
  builds fittings from them: one-off upgrades a building takes once it's high
  enough (shelving, a well pump, weapon racks, enchanted chests…). Population eats food,
  pays taxes, and fills the houses (empty homes draw settlers, half of
  them a day, so it slows as the houses fill, plus slow family growth); it promotes the settlement
  (hamlet, village at 40, town at 90, city at 150), which raises building
  level caps and gives everyone bank slots.
- **Prayer:** enemies drop bones; burying them gives prayer points and
  Prayer XP. Up to two prayers (eight unlock from level 1 to 60) boost each
  fight while their points last, and praying trains Prayer too. A Temple adds
  points per bone and lets players offer bones as devotion, which wards the
  city in the next raid.
- **Herblore:** farmers grow six herbs (guam to snapdragon), one per tier.
  Every potion is a ladder of up to six tiers (I–VI): the tier's herb plus
  the matching rung of the skill's own resources (copper ore → runite ore,
  logs → enchanted logs, copper bar → rune bar…), at Herblore 1, 15, 30, 45,
  60 and 75. Gathering and Construction potions are 10–35% faster, crafting
  potions a 10–35% chance to keep materials, Prayer more points from bones,
  and combat has Strength and Defence ladders. Potions last 50 uses, one per
  skill at a time; an empty one is replaced from the bank automatically.
- **Events:** raids are announced a day or two ahead. Reconnaissance from
  scouts, informants and the spymaster's guild narrows down when, how strong,
  and finally where their camp is, so fighters can sabotage it. Fighters can
  also drill the militia before any raid: a full drill takes as much work as
  full intel on that threat and adds one defence per townsperson. Favour never buys results directly: master builders,
  informants and drill sergeants double what players put in for a while,
  XP included. Each intel
  level takes more scouting than the last and more for a bigger band, and
  levels 2 and 3 only open about a day and eight hours before the raid
  arrives. 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.
  Every fight uses up arrows and breaks some of the swords and shields
  handed out (worst first), more in a close fight or a defeat.
  Now and then a dragon comes instead of bandits.
- **Happenings:** three more tracks run on their own cooldowns. Minor threats
  (wolves, a mine collapse, goblin thieves…) slow or block a skill until
  players deal with them; hardships (sickness, locusts, rot, storms, fire,
  harsh winters, drought) hit the stores and buildings, softened by a granary,
  lumber shed, well and water barrels; fortunes (visiting masters, harvests,
  festivals, nobles, mercenaries…) give windows of plenty. Weather changes
  every few hours, and a game season lasts a week.

## 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).

## Credits

Icons are from [game-icons.net](https://game-icons.net) by Lorc, Delapouite
and contributors, used under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/).
`tools/build_icons.py` fetches the glyphs the game uses into `static/icons.svg`.