From 75c3d49b04686553e5e70bc3f82344fb6936fee9 Mon Sep 17 00:00:00 2001 From: "Fabian @ Blax Software" Date: Tue, 3 Nov 2026 09:42:07 +0100 Subject: [PATCH] docs: population in heads and the food rate at world speed, a level needs idle villagers, the no-locks row and lint, config comments Co-Authored-By: Claude Opus 5.5 --- config/game/buildings.php | 3 ++- config/game/economy.php | 9 ++++++--- config/game/units.php | 4 +++- docs/architecture.md | 18 ++++++++++++++---- 4 files changed, 25 insertions(+), 9 deletions(-) diff --git a/config/game/buildings.php b/config/game/buildings.php index 825dc61..4f909aa 100644 --- a/config/game/buildings.php +++ b/config/game/buildings.php @@ -4,7 +4,8 @@ // `space` is how much of the village's building space an instance takes, at any level. // Level n: cost = cost × factor^(n−1), build time = base × factor^(n−1) seconds at world // speed 1, workers = round(base × factor^(n−1)), and production, capacity, hides, -// detection and beds = base × factor^(n−1). +// detection and beds = base × factor^(n−1). A new instance or level is only queued when +// idle villagers stand ready for the workers it adds; farms are exempt. // One instance of a type is enough; copies are the exception. The instance at rank n // (0-based, by level, highest first) costs instance_cost_factor^n times as much, and // copies work at a falling share (economy.instance_share). diff --git a/config/game/economy.php b/config/game/economy.php index 6aac251..f1962eb 100644 --- a/config/game/economy.php +++ b/config/game/economy.php @@ -4,11 +4,14 @@ return [ // Per hour at world speed 1, regardless of staffing. 'base_production' => ['wood' => 5, 'clay' => 5, 'iron' => 5], - // Food per hour each villager eats. + // Heads each villager takes: the food per hour it eats at world speed 1. Population + // counts in these heads, so a village holds as many on every world speed; farms make + // and people eat world speed times as much food. 'upkeep' => ['villager' => 1], - // Villagers and soldiers fill this share of the farms' nominal output; the rest is - // surplus that goes into storage. Expensive units eat into it, down to starvation. + // Villagers and soldiers fill this share of the farms' nominal output at world speed 1; + // the rest is surplus that goes into storage. Expensive units eat into it, down to + // starvation. 'villager_share' => 0.8, // Output at staffing ratio r is e^(k·(r−1)): 100% full, about 10% empty. diff --git a/config/game/units.php b/config/game/units.php index 809f25f..37f425e 100644 --- a/config/game/units.php +++ b/config/game/units.php @@ -1,7 +1,9 @@ level). - Barracks (spear, sword, archer), stable (light and heavy cavalry), workshop (ram, catapult) and academy (nobleman) are ordinary building instances. Each instance runs its own recruiting queue, so two barracks train side by side, the second at half speed (see "Copies"). Requirements: stable needs barracks 3, workshop barracks 5, academy headquarters 5 and barracks 1; the barracks itself needs nothing. -- Recruiting pays the full cost up front and takes the villagers at once: units in training count against the food budget like trained ones, so villagers shrink immediately and food income doesn't change while they train. A village can't queue more units than it has villagers for (`count × upkeep ≤ villagers`). +- Recruiting pays the full cost up front and takes the villagers at once: units in training count against the food budget like trained ones, so villagers shrink immediately and food income doesn't change while they train. A village can't queue more units than it has villagers for (`count × upkeep ≤ villagers`, in heads, so the same on every world speed). - An order's times are fixed when it is queued: it starts when the previous order at that building ends (or now), and one unit takes `build_time / speed / (1 + recruit_speed_per_level × level) / staffing / share`, with the building's instance share. Units arrive lazily, `done = floor(elapsed / seconds_per_unit)`, and every read or action moves them into `unit_stacks`; a `recruit.finished` event settles the rest. - Cancelling refunds the untrained units in full and moves later orders at that building forward. Tearing a military building down refunds what it was still training. @@ -136,7 +145,8 @@ A village may fail through war or bad play, but it must never get stuck. Every l | Lock | Rule that prevents it | |---|---| | No villagers, no food | Farm 0 (gatherers) has nominal output > 0, so capacity is never 0. Villagers fill instantly. Wood, clay, and iron trickle regardless of staffing. | -| Farm, workers, and capacity feeding each other | Capacity uses nominal farm output, not actual output. Farms are staffed before every other building. Lint: each farm level's worker upkeep < its output. | +| Farm, workers, and capacity feeding each other | Capacity uses nominal farm output, not actual output. Farms are staffed before every other building. Lint: each farm level's worker upkeep < the heads it feeds. | +| Not enough villagers for a level | Farms need no idle villagers, so a village can always grow its farms, and a bigger farm brings more villagers. Demolishing frees a building's workers, cancelling frees what an order reserved, and support sent elsewhere or soldiers lost free heads. Drafted militia don't count as idle, but every levy ends on its timer. Lint: one of every building at max level, with its workers, fits the villagers one farm at max level feeds (at the villager share, without soldiers). | | Copies that give nothing | A copy works at `instance_share`^n of a full building; one that eats more than it gives can always be demolished. Lint: `economy.instance_share` above 0 and at most 1, every `instance_cost_factor` at least 1. | | Next upgrade costs more than storage holds | Lint: for every building and level, the cost fits the storage cap reachable without that building, and storage's own next level fits its current cap. | | Building space full | Demolishing is always allowed, costs nothing, and refunds. Core buildings (HQ, one storage, one farm) cannot go below level 1. Lint: the start buildings fit the space, and every type fits next to them. |