docs: building space, diorama and map in architecture and roadmap
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
e8c4382d78
commit
111ce3d608
|
|
@ -8,7 +8,7 @@ Read [docs/architecture.md](docs/architecture.md) before you change game logic,
|
||||||
|
|
||||||
## Game rules for the code
|
## 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.
|
- **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.
|
- **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`.
|
- **Config, not literals.** Game values live in `config/game/*.php` plus per-world overrides in `worlds.config`. Game code reads them through `WorldConfig`.
|
||||||
|
|
|
||||||
|
|
@ -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/Production.php rates per resource from buildings, staffing, base trickle
|
||||||
Economy/Population.php food budget, capacity, villagers, worker assignment
|
Economy/Population.php food budget, capacity, villagers, worker assignment
|
||||||
Economy/Settle.php stored + rate × elapsed, storage caps, food zero-crossing
|
Economy/Settle.php stored + rate × elapsed, storage caps, food zero-crossing
|
||||||
Buildings/BuildingRules.php cost, time, workers, output per level
|
Buildings/BuildingRules.php cost, time, workers, output, space, points per level
|
||||||
Buildings/VillageGrid.php footprint placement and overlap checks
|
|
||||||
Buildings/BuildQueue.php builders, next unblocked order
|
Buildings/BuildQueue.php builders, next unblocked order
|
||||||
|
Map/Continent.php K-names of the 100 × 100 continents
|
||||||
Travel/TravelTime.php
|
Travel/TravelTime.php
|
||||||
Combat/CombatResolver.php
|
Combat/CombatResolver.php
|
||||||
Combat/LootCalculator.php
|
Combat/LootCalculator.php
|
||||||
|
|
@ -71,15 +71,16 @@ When upkeep exceeds income, food stock drains. The engine computes the exact mom
|
||||||
|
|
||||||
## Village space
|
## 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 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 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 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.
|
||||||
- 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.
|
- 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.
|
- 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.
|
- 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.
|
- 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 has footprint `[0, 0]`: it surrounds the village and takes no space.
|
- 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
|
## 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. |
|
| 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 < 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. |
|
| 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. |
|
| 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. |
|
| 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. |
|
| 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
|
||||||
|
|
||||||
`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):
|
A building entry looks like this (numbers start TW-like):
|
||||||
|
|
||||||
```php
|
```php
|
||||||
'timber_camp' => [
|
'timber_camp' => [
|
||||||
'footprint' => [2, 2],
|
'space' => 4,
|
||||||
'max_per_village' => null,
|
'max_per_village' => null,
|
||||||
'max_level' => 30,
|
'max_level' => 30,
|
||||||
'cost' => ['wood' => 50, 'clay' => 60, 'iron' => 40, 'factor' => 1.25],
|
'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 |
|
| `worlds` | name, slug, config json, started_at, ends_at null |
|
||||||
| `players` | user_id, world_id, name, points. unique(user_id, world_id) |
|
| `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) |
|
| `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, x, y, priority, workers (assigned, derived on settle) |
|
| `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, x, y, cost json, position, builder null, starts_at null, finishes_at null, game_event_id null |
|
| `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) |
|
| `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 |
|
| `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 |
|
| `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.
|
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
|
## 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.
|
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.
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
# Roadmap
|
# 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
|
## 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] `Production` + `Settle` (base trickle, staffing curve, storage caps) with unit tests
|
||||||
- [x] `Population` (food budget, villagers, worker assignment by priority) 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] `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] `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] 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] 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] 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
|
## M2: Map and barbarian villages
|
||||||
|
|
||||||
- [ ] Map generation and spawn placement
|
- [ ] Map generation and spawn placement (for now: rings of every second field around the centre)
|
||||||
- [ ] Barbarian villages: seeding, optional growth over time (world config)
|
- [x] Barbarian villages: seeding around the centre with random levels, once per world
|
||||||
- [ ] `map.view {x, y, w, h}` with village owner and points
|
- [ ] Barbarian growth over time (world config)
|
||||||
- [ ] UI: coordinate table map with jump-to and village info
|
- [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
|
## 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
|
- [ ] Village switcher and overviews across villages
|
||||||
- [ ] Inactive villages turn barbarian; restart on the same world after losing every village
|
- [ ] 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)
|
- [ ] Richer diorama: more detail per building type and level tier, animations (the basic diorama shipped with M1)
|
||||||
- [ ] Drag to place new buildings and move existing ones (server validates)
|
|
||||||
- [ ] Steam build check: static output wrapped in Electron or Tauri
|
- [ ] Steam build check: static output wrapped in Electron or Tauri
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue