From 111ce3d6084e6e9d7165e03fae549b58fcb00358 Mon Sep 17 00:00:00 2001 From: "Fabian @ Blax Software" Date: Wed, 28 Oct 2026 19:45:03 +0100 Subject: [PATCH] docs: building space, diorama and map in architecture and roadmap Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 2 +- docs/architecture.md | 33 +++++++++++++++++++-------------- docs/roadmap.md | 20 ++++++++++---------- 3 files changed, 30 insertions(+), 25 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2039f07..52e6201 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,7 +8,7 @@ Read [docs/architecture.md](docs/architecture.md) before you change game logic, ## Game rules for the code -- **Server-authoritative.** The client sends only intents, such as `village.build {village_id, type, x, y}`. The server checks ownership, cost, space, queue, and requirements, and computes every cost, duration, and timestamp itself. +- **Server-authoritative.** The client sends only intents, such as `village.build {village_id, type}`. The server checks ownership, cost, building space, queue, and requirements, and computes every cost, duration, and timestamp itself. - **Lazy state.** Resources, loyalty, and recruit progress are `stored + rate × elapsed`. Before any change, settle the current value into the row, then apply the change. - **Timed effects** are rows in `game_events`. The `game:events` worker processes them in `(fire_at, id)` order. Game logic is never a delayed queue job, because those don't keep order. - **Config, not literals.** Game values live in `config/game/*.php` plus per-world overrides in `worlds.config`. Game code reads them through `WorldConfig`. diff --git a/docs/architecture.md b/docs/architecture.md index 90026fd..db669a9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -26,9 +26,9 @@ 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 per level - Buildings/VillageGrid.php footprint placement and overlap checks + Buildings/BuildingRules.php cost, time, workers, output, space, points per level Buildings/BuildQueue.php builders, next unblocked order + Map/Continent.php K-names of the 100 × 100 continents Travel/TravelTime.php Combat/CombatResolver.php Combat/LootCalculator.php @@ -71,15 +71,16 @@ When upkeep exceeds income, food stock drains. The engine computes the exact mom ## Village space -- Each village has a grid of `grid_w × grid_h` cells. The world config sets the default (`village.grid`, 10 × 5 = 50 cells). The village row stores its own size, so terrain or specials can change it per village later. -- Each building type has a fixed `footprint` `[w, h]` in config, for example HQ `[3, 3]`, barracks `[3, 2]`, resource buildings `[2, 2]`, and hiding place `[1, 1]`. The level changes only the sprite, never the size. -- Each building instance has its own position `(x, y)` from M1 on. The client may send a position; otherwise the server picks the first free slot. The server validates bounds and overlap either way. Positions are stored from the start because an area budget alone can "fit" a set of buildings that cannot actually be packed onto the grid, and the M6 city view could not draw such a village. +- Each village has a building space budget. The world config sets the default (`village.space`, 50). The village row stores its own `space`, so terrain or specials can change it per village later. +- 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 0. Level 0 is a real, primitive state: the HQ is a tent, storage is open ground, and the farm is gatherers. A new instance is built at level 0. - 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. -- Demolishing goes through the build queue. It lowers an instance by one level and refunds `demolish_refund` × that level's cost (default 0.5). Below level 0 the instance is removed and its cells are freed. -- The wall has footprint `[0, 0]`: it surrounds the village and takes no space. +- Demolishing goes through the build queue. It lowers an instance by one level and refunds `demolish_refund` × that level's cost (default 0.5). Below level 0 the instance is removed and its space is freed. +- The wall takes 0 space: it surrounds the village. +- 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. -A new village starts with HQ 0, storage 0, and farm 0, auto-placed, plus starting resources from world config. +A new village starts with HQ 0, storage 0, and farm 0, plus starting resources from world config. ## No locks @@ -90,7 +91,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. | | 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. | -| Grid full | Demolishing is always allowed, costs nothing, and refunds. Core buildings (HQ, one storage, one farm) cannot go below level 0. | +| Building space full | Demolishing is always allowed, costs nothing, and refunds. Core buildings (HQ, one storage, one farm) cannot go below level 0. 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. | | Building requirements | Lint: the requirement graph has no cycles, and every building and level is reachable from the start village. | | Starvation spiral | Deserters leave in the order foreign support, soldiers, non-farm villagers. Farm workers stay, so food income can't collapse. | @@ -101,13 +102,13 @@ A village may fail through war or bad play, but it must never get stuck. Every l ## Config -`config/game/world.php`, `economy.php`, `buildings.php`, `units.php`, and `combat.php` hold the defaults. `worlds.config` (JSON) overrides any key, the way Die Stämme world settings do: speed, unit speed, morale, night bonus, beginner protection, map size, builders, refund rate, grid size, staffing k, starvation grace, noble rules, and so on. `WorldConfig` merges the two and is the only reader. +`config/game/world.php`, `economy.php`, `buildings.php`, `units.php`, and `combat.php` hold the defaults. `worlds.config` (JSON) overrides any key, the way Die Stämme world settings do: speed, unit speed, morale, night bonus, beginner protection, map size, builders, refund rate, building space, staffing k, starvation grace, noble rules, and so on. `WorldConfig` merges the two and is the only reader. A building entry looks like this (numbers start TW-like): ```php 'timber_camp' => [ - 'footprint' => [2, 2], + 'space' => 4, 'max_per_village' => null, 'max_level' => 30, 'cost' => ['wood' => 50, 'clay' => 60, 'iron' => 40, 'factor' => 1.25], @@ -124,9 +125,9 @@ A building entry looks like this (numbers start TW-like): |---|---| | `worlds` | name, slug, config json, started_at, ends_at null | | `players` | user_id, world_id, name, points. unique(user_id, world_id) | -| `villages` | world_id, player_id null (null = barbarian), name, x, y, grid_w, grid_h, wood/clay/iron/food decimal(14,4), resources_at datetime(3), villagers, levy_until null, starving_since null, loyalty, loyalty_at, points. unique(world_id, x, y) | -| `buildings` | village_id, type, level, x, y, priority, workers (assigned, derived on settle) | -| `build_orders` | village_id, building_id null (null = new instance), type, action (build/upgrade/demolish), target_level, x, y, cost json, position, builder null, starts_at null, finishes_at null, game_event_id null | +| `villages` | world_id, player_id null (null = barbarian), name, x, y, space, wood/clay/iron/food decimal(14,4), resources_at datetime(3), villagers, levy_until null, starving_since null, loyalty, loyalty_at, points. unique(world_id, x, y) | +| `buildings` | village_id, type, level, priority (workers are derived on every read) | +| `build_orders` | village_id, building_id null (null = new instance), type, action (build/upgrade/demolish), target_level, cost json, builder null, starts_at null, finishes_at null. Queue order is id order | | `unit_stacks` | village_id (where they stand), home_village_id (owner), unit, count. unique(village_id, home_village_id, unit) | | `recruit_orders` | village_id, building_id, unit, count, done, seconds_per_unit, starts_at, finishes_at, game_event_id | | `food_deliveries` | village_id, amount, delivered_at. Feeds the 24h import average; each row's expiry is an event | @@ -149,6 +150,10 @@ Handlers are idempotent per event row: the transaction plus `processed_at` guard The map is square (`map.size`, default 1000 × 1000) and split into TW-style continents of 100 × 100 for orientation (K55). New players spawn on a ring that moves outward from the center as the world fills. Barbarian villages fill the gaps, grow slowly (world config), and a village whose player has been inactive for too long turns barbarian. +`map.view {world_id, x, y, w, h}` returns the villages in a `w × h` window (at most `map.max_view` per side) centred on `x|y`, kept inside the map; without a centre it opens on the player's first village. Each village comes with its coordinates, continent, name, points, owner (null for barbarians) and whether it is the player's own. The client draws it like the Die Stämme map: a top-down field grid with coordinate rulers and continent lines. + +So far (M2 in progress) players spawn on rings of every second field around the centre, and `SeedBarbarians` scatters `map.barbarians.count` barbarian villages with random low building levels within `radius` of the centre, once per world, keeping the inner spawn area free. + ## Movements and encounters Every group on the map is a `movement`: an attack, support, return, or trade caravan (merchants, optionally with an escort). It moves in a straight line at constant speed, so its position at time t is a linear interpolation between origin and target. diff --git a/docs/roadmap.md b/docs/roadmap.md index bee911b..8d9afb2 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,6 +1,6 @@ # Roadmap -Each milestone ends with tests green, `ConfigLint` green, and something playable in the plain UI. +Each milestone ends with tests green, `ConfigLint` green, and something playable in the UI. ## M1: Village, economy, buildings @@ -13,19 +13,20 @@ Each milestone ends with tests green, `ConfigLint` green, and something playable - [x] `Production` + `Settle` (base trickle, staffing curve, storage caps) with unit tests - [x] `Population` (food budget, villagers, worker assignment by priority) with unit tests - [x] `BuildingRules` (cost, time, workers, output, instance_cost_factor, levels from 0) with unit tests -- [x] `VillageGrid` (per-type footprints, bounds, overlap, auto-place, unique types) with unit tests +- [x] Building space (per-type space, village budget, reserved for queued builds, unique types) with unit tests (replaced the first tile grid) - [x] `BuildQueue` (builders by HQ level, next unblocked order) with unit tests - [x] Event engine: `game_events`, `game:events` worker, per-village catch-up, idempotent handlers - [x] Actions: join world (HQ 0, storage 0, farm 0), build, upgrade, demolish with refund, cancel with refund, set priority. Feature tests with time travel - [x] WS controllers `village.show|build|upgrade|demolish|cancel|staff` and a `village:updated` push -- [x] UI: resource bar with projected values, population and food budget, building table with staffing, grid as a plain table of cells, build queue with builders and countdowns +- [x] UI: resource bar with projected values, population and food budget, building table with staffing, village as a low-poly isometric diorama (full width), build queue with builders and countdowns ## M2: Map and barbarian villages -- [ ] Map generation and spawn placement -- [ ] Barbarian villages: seeding, optional growth over time (world config) -- [ ] `map.view {x, y, w, h}` with village owner and points -- [ ] UI: coordinate table map with jump-to and village info +- [ ] Map generation and spawn placement (for now: rings of every second field around the centre) +- [x] Barbarian villages: seeding around the centre with random levels, once per world +- [ ] Barbarian growth over time (world config) +- [x] `map.view {world_id, x, y, w, h}` with village owner, points and continent; village points from building levels +- [ ] UI: Die Stämme-style coordinate map with rulers, continent lines, jump-to and village info ## M3: Units, upkeep, starvation @@ -61,8 +62,7 @@ Each milestone ends with tests green, `ConfigLint` green, and something playable - [ ] Village switcher and overviews across villages - [ ] Inactive villages turn barbarian; restart on the same world after losing every village -## M7: City view +## M7: City view and Steam -- [ ] Rendered village grid with sprites per building type and level (level 0 = tent, open storage, gatherers) -- [ ] Drag to place new buildings and move existing ones (server validates) +- [ ] Richer diorama: more detail per building type and level tier, animations (the basic diorama shipped with M1) - [ ] Steam build check: static output wrapped in Electron or Tauri