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 <noreply@anthropic.com>
This commit is contained in:
Fabian @ Blax Software 2026-11-03 09:42:07 +01:00
parent c272ecb5f2
commit 75c3d49b04
4 changed files with 25 additions and 9 deletions

View File

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

View File

@ -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.

View File

@ -1,7 +1,9 @@
<?php
// Units, with Die Stämme-like stats. A unit is trained from one villager at its building
// type; while queued and after, it eats `upkeep` food per hour instead of that villager.
// type; while queued and after, it takes `upkeep` heads of the food budget instead of that
// villager: it eats `upkeep` food per hour at world speed 1, world speed times that on a
// faster world.
// build_time is seconds per unit at world speed 1, building level 1 and full staffing.
// speed is minutes per field (M4), carry is loot per unit (M4). volley is what one unit
// shoots before the melee, in food upkeep of the enemy it kills (0 when missing; see combat.php).

View File

@ -54,8 +54,13 @@ Rates are constant between events. Any change to a rate settles the village firs
### Population
- **Capacity** is a food budget in food/h: `nominal farm output + 24h average of food delivered to this village`, a copy farm at its share (see "Copies"). Nominal means the output at full staffing, which avoids a loop between farms, workers, and capacity (see "No locks"). Capacity is TW-like and instant: no growth timer.
- **Upkeep**: every villager eats `upkeep.villager` (for example 1 food/h), and soldiers eat per unit type (for example spear 1, heavy cav 4, noble 10). Foreign support stationed in the village counts against the host's budget.
Population counts in heads. A head is one food per hour at world speed 1. Farms make world speed times their output and every head eats world speed times its upkeep, so a village holds the same heads on every world speed and only the food rate scales.
- **Capacity** is a food budget in heads: `nominal farm output at world speed 1 + 24h average of food delivered to this village ÷ world speed`, a copy farm at its share (see "Copies"). Nominal means the output at full staffing, which avoids a loop between farms, workers, and capacity (see "No locks"). Capacity is TW-like and instant: no growth timer.
- **Upkeep**: every villager takes `upkeep.villager` heads (1), and soldiers take their unit's `upkeep` (for example spear 1, heavy cav 4, noble 10). Foreign support stationed in the village counts against the host's budget.
- **Food rate**: `rates.food` is the farms' output at world speed and staffing, minus upkeep × world speed. The food stock, starvation and its desertion waves run at world speed like every other resource; the heads stay the same.
- The village payload's `population` is in heads: `food_budget`, `upkeep`, `villagers`, `workers`, `idle` and `reserved` (see "Workers and staffing"); `soldiers` and `training` count units. `rates.food` is food per hour at world speed.
- Villages from before heads had their highest farm raised on deploy to the lowest level that feeds their soldiers and workers (migration `farms_feed_their_heads`); only the speed 100 dev world had such villages.
- **Villagers** fill instantly up to `economy.villager_share` (default 80%) of the budget, minus what soldiers and stationed support eat. Villagers are the workforce. The other 20% of the farms' output is surplus that goes into storage, so food builds up; expensive units eat into it, and a big enough army pushes the village into starvation.
- **Training a soldier** turns one villager into that unit and costs resources. The soldier's upkeep takes from the budget, so villagers shrink to match, the same as TW farm space.
- **Levy**: the player can draft villagers as militia for a fixed time (`economy.levy.duration`, divided by world speed), one levy at a time. The militia still eat but don't work, so their buildings run understaffed; recruiting can only train villagers who are not drafted. A `levy.ends` event at `levy_until` settles the village and sends them back to work; the player can also end the levy early. If villagers drop below the militia count (a farm torn down, soldiers trained), the militia shrink with them.
@ -65,6 +70,10 @@ Rates are constant between events. Any change to a rate settles the village firs
- Each building level needs `workers` (config). Villagers are assigned to buildings automatically, highest `priority` first, then evenly. The player sets the priority per building instance.
- Output at staffing ratio `r = staffed / required` is `e^(k·(r−1))`, with `k` from world config (`staffing.k`, default 2.3). Full staffing gives 100% and an empty building gives about 10%, so output never reaches zero.
- Staffing scales resource production, and the HQ's staffing scales build speed.
- **A level needs villagers.** Queuing a new instance or an upgrade is refused (`villagers`) unless enough idle villagers stand ready for the workers it adds: workers(target) − workers(target − 1), all of level 1's for a new instance (`BuildingRules::extraWorkers`). Idle villagers are the villagers not drafted by a levy, minus the workers every standing building needs, minus what queued orders reserved, never below 0 (`Workforce::idle`).
- A queued new instance or upgrade reserves its extra workers until it finishes or is cancelled, the way a new instance reserves its space. A demolition frees its workers when it finishes.
- Farms are exempt: they need no idle villagers and reserve none. A farm brings more heads than it employs (lint), and without the exemption a full village could never grow.
- Build options and upgrade offers carry `villagers` (the idle villagers they need, 0 for farms) and `blocked: 'villagers'` when there aren't enough. `population.idle` and `population.reserved` give the numbers.
### Copies
@ -106,7 +115,7 @@ A new village starts with HQ 0, storage 0, and farm 0, plus starting resources f
Units live in `config/game/units.php` (Die Stämme-like stats): the building type that trains them, cost, food `upkeep` per hour, `build_time` per unit, attack, defence per class, speed and carry (both used from M4), and `requires` (building type => 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. |