diff --git a/docs/architecture.md b/docs/architecture.md index 593ebae..58f8c44 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -27,7 +27,7 @@ app/Game/ pure rules: no Eloquent, no now(), fully unit tested Economy/Production.php rates per resource from buildings, staffing, base trickle Economy/Population.php food budget, capacity, villagers, worker assignment Economy/Settle.php stored + rate × elapsed, storage caps, food zero-crossing - Buildings/BuildingRules.php cost, time, workers, output, space, points per level + Buildings/BuildingRules.php cost, time, workers, output, space, points per level, instance shares Buildings/BuildQueue.php builders, next unblocked order Map/Continent.php K-names of the 100 × 100 continents Map/MapBounds.php coordinates from −size/2 to size/2 − 1 around 0|0 @@ -46,13 +46,13 @@ app/Models/ Eloquent ### Resources -There are four resources: wood, clay, iron, and food. Every village gets a base trickle of wood, clay, and iron (`economy.base_production`, for example 5/h each). That trickle ignores staffing. Buildings add to it. Food comes from farms only. Storage caps all four resources. +There are four resources: wood, clay, iron, and food. Every village gets a base trickle of wood, clay, and iron (`economy.base_production`, for example 5/h each). That trickle ignores staffing. Buildings add to it. Food comes from farms only, and one farm feeds a full army: level 30 makes about 19,400 food/h at world speed 1. Storage caps all four resources. Rates are constant between events. Any change to a rate settles the village first: it writes the current amounts and `resources_at = now`, then applies the change. Changes to rates include a build finishing, a worker change, levy, troops arriving or leaving, and a food delivery expiring. ### Population -- **Capacity** is a food budget in food/h: `nominal farm output + 24h average of food delivered to this village`. 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. +- **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. - **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. @@ -64,6 +64,15 @@ Rates are constant between events. Any change to a rate settles the village firs - 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. +### Copies + +One instance of each type is enough, as in Die Stämme. A copy works at a falling share (`economy.instance_share`, 0.5). The instances of one type rank by level, highest first, then lowest id, and the one at rank n works at `instance_share`^n: the first or only one in full, a second at half, a third at a quarter. + +- The share scales production, a farm's nominal output in the food budget, storage capacity, hides, hospital beds and training speed (seconds per unit divide by it). +- Workers needed stay full, so a copy eats like a full building and gives half. +- The rank follows the standing buildings on every read (`BuildingRules::instanceShares`). Upgrading a copy past the first swaps their shares. +- The village payload carries `instance_share` on every building, and on every build option the share a new instance would work at: `instance_share`^(standing + queued instances of that type). + ### Builders Each village has `builders` (default 2, +1 at the HQ levels listed in world config, for example 10 and 20). All orders share one queue. A free builder takes the first order that is not blocked by an order still running, for example a second upgrade of the same building instance. Build time is scaled by the HQ's level and staffing. @@ -80,13 +89,13 @@ A wave takes the fewest units that make income cover upkeep again: support stati - Each building type takes a fixed `space` from config, for example HQ 9, barracks 6, resource buildings 4, and hiding place 1. The level changes only the look, never the space. A building fits when the space of all buildings plus new buildings still in the queue, plus its own, stays within the budget. The space is reserved when the order is queued. - There are no tiles and no stored positions. The client draws the village as a low-poly isometric diorama and lays the buildings out itself (HQ in the centre, the rest around it), so where a building stands is presentation, not game state. - Levels start at 1, as in Die Stämme, and a new instance is built at level 1. Every per-level formula uses `level − 1` as the exponent of its factor, so level 1 has the base values. -- Multiple instances per type are allowed. `max_per_village` limits types that must stay unique (HQ, rally point, wall). `instance_cost_factor` makes the n-th instance of a type more expensive, so many cheap copies don't beat upgrading. +- One of each type is enough: one storage, one farm, one barracks. Copies are the exception and pay twice. `max_per_village` keeps some types unique (HQ, rally point, wall, watchtower, academy). The n-th instance of a type (0-based, in build order) costs `instance_cost_factor`^n as much at every level (2: a second camp costs double, a third four times), and it works at a falling share (see "Copies"). Upgrading beats copying. - Basic buildings have no requirements: everything in the core set, the wall included, can be built from the start. Only advanced buildings get `requires` (type => minimum level of any instance), for example the academy (Adelshof) needs the headquarters and a barracks (Kaserne). A build option lists what is still missing. - Demolishing goes through the build queue. It lowers an instance by one level and refunds `demolish_refund` × that level's cost (default 0.5). Taking level 1 down removes the instance (an order with target level 0) and frees its space. - The wall takes 0 space: it surrounds the village. -- **Roles** (`Specialisation`, `world.village.specialisation`): what fills the space gives a village a role. Resource buildings (timber camp, clay pit, iron mine) and military buildings (barracks, stable, workshop, academy) count; when one kind takes at least `share` (70%) of the space both kinds take together, and at least `min_space` (16), the village has that role. A resource village's camps produce `production` (+20%) more; a military village trains `recruit_speed` (+20%) faster and everyone defending it, support included, fights with `defense` (+10%) more. Farms, storage and the rest count for neither, since both kinds of village need them. Only standing buildings count, so a role starts and ends when an order finishes. The payload's `specialisation` carries the role, the space per role and the rules. +- **Roles** (`Specialisation`, `world.village.specialisation`): what fills the space gives a village a role. Resource buildings (timber camp, clay pit, iron mine) and military buildings (barracks, stable, workshop, academy) count; when one kind takes at least `share` (70%) of the space both kinds take together, and at least `min_space` (16), the village has that role. A resource village's camps produce `production` (+20%) more; a military village trains `recruit_speed` (+20%) faster and everyone defending it, support included, fights with `defense` (+10%) more. Farms, storage and the rest count for neither, since both kinds of village need them. Only standing buildings count, so a role starts and ends when an order finishes. The payload's `specialisation` carries the role, the space per role and the rules. A role now needs paid-for copies: one of each camp takes 12 space, short of `min_space`, and next to one of each camp the military buildings fall short of `share`. - Each building level is worth `points` (config); a village's points are their sum, kept on the row when an order finishes and shown on the map. -- Every building in the village payload carries `effects` and `next_effects` (`BuildingRules::effects`): what one instance does at its level and one level up, as `{key, value, resource?}`: production at full staffing, capacity, hides, detection, the wall's flat defence and bonus %, the headquarters' build speed %, builders and village space, a military building's training speed %. The client shows them on the building's own screen. +- Every building in the village payload carries `effects` and `next_effects` (`BuildingRules::effects`): what one instance does at its level and one level up, at its instance share, as `{key, value, resource?}`: production at full staffing, capacity, hides, detection, the wall's flat defence and bonus %, the headquarters' build speed %, builders and village space, a military building's training speed %. The client shows them on the building's own screen. A new village starts with HQ 0, storage 0, and farm 0, plus starting resources from world config. @@ -94,14 +103,14 @@ 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. Requirements: stable needs barracks 3, workshop barracks 5, academy headquarters 5 and barracks 1; the barracks itself needs nothing. +- 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`). -- 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`. 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. +- 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. ### Hospital -The Lazarett (`hospital`, needs barracks 1) brings part of the fallen back. Its instances add up their `beds`, each scaled by its staffing like production, and a bed holds one wounded of any unit. +The Lazarett (`hospital`, needs barracks 1) brings part of the fallen back. Its instances add up their `beds`, each scaled by its staffing and instance share like production, and a bed holds one wounded of any unit. - After a battle in the village, `combat.hospital.share` (50%) of each own unit that fell, rounded down, comes in as wounded (`Wounds::admit`). Support fell for another village and gets nothing. When they need more beds than are free, the beds are shared out evenly, the rest by largest remainder. A conquered village takes nobody in, and barbarian villages keep no hospital. - One battle's wounded are one `wounded` row with `heals_at = battle + heal_time / speed` (4 hours). A `wounded.healed` event puts them back into the village's own stacks. @@ -126,6 +135,7 @@ A village may fail through war or bad play, but it must never get stuck. Every l |---|---| | 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. | +| 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. | | Queue blocked | A free builder skips blocked orders. Every order can be cancelled with a refund. |