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.

Beta. The core game is in place; changes from here are mostly balance and tuning.

## What's in it

- **Skills:** mining, woodcutting, farming, hunting, fishing, smithing,
  jewelcrafting, construction (with masonry), cooking, leatherworking, tailoring, herblore,
  firekeeping, 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:** a fight is a party against a pack, played out in quarter-second
  slices (`combat.py`). Everyone swings on their weapon's timer, and swings hit,
  miss or crit. Every blow has a damage type (slashing, blunt, piercing, magic);
  each enemy is vulnerable to some (+25%) and resists others (-25%), shown as
  tinted icons. Armour stops physical blows, ward stops magic. On top of the
  swings, your weapon gives four abilities (learned at combat 1, 15, 30 and 45)
  and your trade one more; for now they're all on auto. Enemies use their own:
  brutes wind up a Heavy Slam, skirmishers lunge at whoever isn't tanking,
  casters cast a Hex Bolt you can interrupt, elites and bosses enrage, dragons
  breathe fire. Enemies pick targets by threat. A pack is as many enemies as
  there are of you, often one more (each weaker); a rare elite comes alone.
  Between fights you rest back to full: food is only eaten then, and better food
  rests you faster. In a fight the only heal you carry is a health potion
  (Herblore), drunk once a fight under 35% HP. At 0 HP you're knocked out: you
  lose that fight and come round at 30%; three knockouts in a row and you stop.
  HP recovers 25% an hour away from fights. 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 four races and a boss (the dragons at the top). Races drop trophies
  (10%, 20% from bosses) for stronger weapons and the area's armour reagents
  (10%, far more from dragons).
- **Bosses and dragons** are group fights: two or more. Alone you wait at it
  for someone to tag in. They grow with the group, and everyone who brings one
  down gets their own loot.
- **Multiplayer Combat:** tag into anyone's fight from the encounter card or the guild roster.
- **Weapons:** four styles, one per trade, and anyone can use any of them; the
  weapon decides your abilities and your role.
  Sword and shield (slashing, 2.4s swings, the shield blocks 15% of hits;
  swords from Smithing, shields from Construction), warhammer (blunt,
  Smithing; slow, heavy, twice the crits), staff (magic, Herblore;
  accurate) and bow (piercing, Leatherworking; fast, strikes first). The
  last three take both hands and carry a shield's power. Your trade's weapon
  does 15% more damage. Past copper, each weapon needs its tier's trophies.
- **Abilities:** sword and shield tanks (Shield Bash, Challenge, Sweeping Cut,
  Shield Wall; the shield ones need a shield), warhammer hits hard and stuns
  (Crushing Blow, Concuss, Earthshaker, Unstoppable), staff heals and holds
  (Bolt, Mend, Ward, Thornbind), bow shoots from afar (Aimed Shot, Pinning
  Shot, Barbed Arrow, Volley, which takes 5 arrows). Trades: Find the Seam
  (miner: a target's resistance stops counting), Barricade (builder: the group
  takes less), Hearty Meal (homesteader: the group heals over time), Mark Prey
  (ranger: a target takes more from everyone).
- **Active play:** any ability can be switched from AUTO (a rule uses it, on a
  1.5× cooldown) to YOU: you press it (tap, or keys 1–9) on its real cooldown,
  and tap frames to pick your target or aim your heals. Your hands only count
  while you watch: look away for 12 seconds and it's all auto again. Presses are
  kept with the fight, which is played again from its seed with them, so
  nothing that already happened changes.
- **Dungeons:** one per area for 2 to 4, pulls in order, sized for the group:
  Goblin Warren (Greenwood, combat 8), Watchtower Depths (20), Barrow Crypts
  (35), Bandit Stronghold (Frontier, 40), The Deep Forge (50), Frozen Hold (65)
  and Dragon's Lair (80). Each has two mini-bosses and a final boss with its own
  abilities. Trash falls on auto; the bosses don't: interruptible curses and
  shrieks, slams to brace for, adds at half health and an enrage timer. Join
  before the first pull. A wipe repeats the pull, three on one pull end the
  run, and the run waits while anyone looks away. Bosses give everyone
  their own loot; clearing pays gold, a trophy and reagents.
- **Armour:** three weights. Heavy plate (Smithing) is strong against blows
  and weak to magic, light cloth (Tailoring) the other way round, medium
  leather (Leatherworking) a bit of both. Every trade gathers its own base
  material at every tier (ore, hunted hides, farmed fibres), and past copper
  each piece also needs reagents from that tier's area: plating, lacing or
  thread.
- **Jewellery:** Jewelcrafting sets a gem in a band. Each tier's rock turns
  up its gem 2% of the time (quartz, garnet, amethyst, sapphire, emerald,
  diamond), and jewellers prospect spare ore for more (5 ore, 15%). Bands
  are copper, then silver and gold, which the jeweller mines and smelts
  without a smithy. Past quartz each piece needs a shard from that tier's
  area. Rings for offence (swing speed, crit, power), amulets for defence (max
  HP, ward, regen), trinkets for the rest (XP, double gathering,
  double crafting), each in its own tab.
- **Tools and stations:** smiths make every tool: one per gathering skill and
  one per crafting skill (chisel, gem drill, hammer, cleaver, mortar and
  pestle, awl, shears). Builders make every station, a second slot for each
  crafting skill (anvil stand, jeweller's bench, workbench, hearth, alembic,
  tanning rack, loom), from the tier's planks and hardware and another
  trade's bars, leather or cloth. Both run 15–60% faster by tier, and a
  station speeds what's made at it (a workbench the building site too).
- **Storage:** builders make
  strongboxes (+2 to +14 bank slots) and homesteaders sew bags (+250 to
  +2,000 per stack); each has one slot on the Bank page, and a smaller one
  can't go on while the bank holds more than it would.
- **Tiers:** six RuneScape-style tiers (copper, iron, steel, mithril,
  adamant, rune at levels 1–75) of ore, trees (up to enchanted), hides (deer,
  boar, bear, elk, sabrecat, mammoth) and fibres (flax, cotton, silk,
  moonpetal, starbloom, spiritvine). Every metal tier has a sword, shield,
  helmet, greaves, cuirass and five tools; every leather tier a cap,
  trousers and jerkin; every cloth tier a hood, leggings and robe. Higher
  bars need coal; each metal past copper needs a Smithy level (rune needs
  level 5, so a city). Gear needs the combat level of its tier (15, 30, 45,
  60, 75) to wear, and the areas open at the same levels; tools need the
  same level in their skill.
- **Classes are trades,** from gathering to finished goods, so each player has
  a quiet gathering side and a busier crafting side: miner (mining, smithing,
  jewelcrafting),
  builder (woodcutting, construction, firekeeping), homesteader (farming, cooking,
  herblore, tailoring) 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.
- **Work orders:** players post requests on a board. A crafting order names
  the item and lets the requester put in any of its reagents; one crafter
  claims it and makes it with their own materials for the rest, and each piece
  goes straight to the requester. A materials request is open to anyone with
  the items. Reagents and the reward are held by the order, paid out as it's
  filled and refunded if it's cancelled or expires (3 days, 5 open each).
  Players who can take an order see a badge, a toast and a banner on the skill.
- **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. Health potions (I–VI, the tier's
  herb and cooked fish) are the one heal you take into a fight. Potions last 50 uses, one per
  skill at a time; an empty one is replaced from the bank automatically.
- **Firekeeping:** the guild shares four fires: the forge (bars), the kitchen
  fire (cooking), the kiln (bricks) and the still (potions). Every craft at a
  fire takes one log of its tier as fuel; a fire burning that tier's flame or
  hotter pays it, and a hot forge takes a coal off every bar (never the last).
  Anyone can tend any fire: each go feeds one log onto your own pile in it, for
  minutes of fire and XP that grow with level, until your pile reaches your
  bank. The fire burns everyone's piles at once, sharing one minute a minute,
  so every log adds to how long it lasts and a full fire never shuts a
  beginner out. Better logs burn hotter colours (red, gold, white, blue,
  green, violet), burn first in their pile, and push your own cheaper fuel out
  when your pile is full; the fire is as hot as its hottest pile. Warmth: 10%
  of the XP of every craft the fire pays for, shared evenly by everyone whose
  pile is hot enough for that craft on its own. Because the fires are shared, the server runs
  everyone's actions as time passes, not only when they next look.
- **Events:** a threat lands every two days, give or take two hours, and the
  next is rumoured as soon as the last one lands. 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 a half and exactly a day before
  the raid arrives, so the second day is for fighting at the camp. 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. Sentries raise the alarm
  five minutes out, and everyone watches the battle play out once, live or
  on their next visit, before the report.
- **Happenings:** three more tracks run on their own cooldowns. Minor threats
  (wolves, a mine collapse, goblin thieves, smugglers…) slow or block a skill until
  players deal with them; hardships (sickness, locusts, rot, storms, fire,
  harsh winters, drought, blight, the tax collector…) hit the stores and buildings, softened by a granary,
  lumber shed, well and water barrels; fortunes (visiting masters, harvests,
  festivals, nobles, mercenaries…) give short windows of plenty, several a day. 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)`.
- `combat.py`: the fight engine and the abilities.
- `tools/balance.py`: an hour of fighting per trade and tier (`solo`, `party`, `bosses`), and
  each dungeon pull on auto or with `perfect` hands (`dungeon`).
- `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`.