docs: market rules, trade tables, no-locks rows for merchants and routes; market partly done on the roadmap

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Fabian @ Blax Software 2026-10-31 11:04:45 +01:00
parent 924f2d1d8a
commit 7303817911
2 changed files with 25 additions and 5 deletions

View File

@ -33,6 +33,7 @@ app/Game/ pure rules: no Eloquent, no now(), fully unit tested
Map/MapBounds.php coordinates from −size/2 to size/2 − 1 around 0|0 Map/MapBounds.php coordinates from −size/2 to size/2 − 1 around 0|0
Map/Frontier.php where new villages settle as the world grows Map/Frontier.php where new villages settle as the world grows
Travel/TravelTime.php Travel/TravelTime.php
Trade/TradeRules.php merchants, their pace, fair offers, route shipments
Combat/CombatResolver.php Combat/CombatResolver.php
Combat/LootCalculator.php Combat/LootCalculator.php
ConfigLint.php proves the config has no locks (see "No locks") ConfigLint.php proves the config has no locks (see "No locks")
@ -144,13 +145,14 @@ A village may fail through war or bad play, but it must never get stuck. Every l
| Foreign support eats the host | The host can send any support home at any time. Foreign support deserts first. | | Foreign support eats the host | The host can send any support home at any time. Foreign support deserts first. |
| Levy never returns | Militia return automatically on a timer. | | Levy never returns | Militia return automatically on a timer. |
| Wounded never return | Each battle's wounded stand again at a fixed `heals_at`. Lint: `combat.hospital.heal_time` above 0 and `share` between 0 and 1. | | Wounded never return | Each battle's wounded stand again at a fixed `heals_at`. Lint: `combat.hospital.heal_time` above 0 and `share` between 0 and 1. |
| All merchants killed | Merchants are trained at the market like units, so dead merchants can always be replaced. | | Merchants never free again | Merchants come from the market's level, not from training. Every trip ends on a timer, cancelling an offer frees its merchants, and merchants a lost village had under way stop counting. Lint: every market level has at least 1 merchant, `market.carry` and `minutes_per_field` above 0, `max_ratio` at least 1. |
| Trade route stuck | A run sends what the stock and the free merchants allow, or nothing, and plans the next run either way. A route whose target changed hands pauses; the player can resume, change or delete it at any time. Lint: 0 < `route.min_every` ≤ `route.max_every`. |
| Player loses every village | The player can restart on the same world with a fresh village. | | Player loses every village | The player can restart on the same world with a fresh village. |
| Raids bleed a village dry | Raids come `every_hours` apart in real hours on every world, after beginner protection, and loot only what the hiding places don't cover. Rams never take a wall below 1, a beaten band's rams fire only their first half, and no band takes a village. Beating the camp down scatters its next band, and a band facing a defence far too strong stays home. Lint: intervals above 0, `scatter_below` above 0, `dare` at least 0. | | Raids bleed a village dry | Raids come `every_hours` apart in real hours on every world, after beginner protection, and loot only what the hiding places don't cover. Rams never take a wall below 1, a beaten band's rams fire only their first half, and no band takes a village. Beating the camp down scatters its next band, and a band facing a defence far too strong stays home. Lint: intervals above 0, `scatter_below` above 0, `dare` at least 0. |
## 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, building space, 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`, `combat.php`, `market.php` and the rest of `config/game/` 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):
@ -180,11 +182,13 @@ A building entry looks like this (numbers start TW-like):
| `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 |
| `wounded` | village_id, units (json unit => count), heals_at datetime(3): one battle's wounded in the hospital | | `wounded` | village_id, units (json unit => count), heals_at datetime(3): one battle's wounded in the hospital |
| `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 |
| `movements` | world_id, player_id (whose troops), type (attack/support/return), mode, origin_id, target_id, units json, cargo json null, catapult_target null, rng_seed, sent_at, arrives_at, visible_at. Trade, merchants and destroyed_at come with M5 | | `movements` | world_id, player_id (whose troops or merchants), type (attack/support/return/trade/trade_return), mode, origin_id, target_id, units json, cargo json null, catapult_target null, rng_seed, sent_at, arrives_at, visible_at, merchants (0 for troops), route_id null (the trade route that sent it), offer (sent for an accepted offer). destroyed_at comes with encounters |
| `trade_offers` | world_id, village_id, give_resource, give_amount, want_resource, want_amount, count (still open), merchants (reserved per unit of count) |
| `trade_routes` | village_id, target_id, target_player_id (the target's owner when made), wood, clay, iron, every (real seconds), next_at datetime(3), paused, paused_reason null, last_sent_at null, last_cargo json null |
| `tribes`, `tribe_members`, `tribe_invites`, `tribe_relations`, `tribe_events` | world_id, name, tag, description; tribe_id, player_id (unique), role; tribe_id, player_id, invited_by; tribe_id, other_tribe_id, state (ally/nap/enemy), confirmed_at, ends_at; tribe_id, type, payload, happened_at | | `tribes`, `tribe_members`, `tribe_invites`, `tribe_relations`, `tribe_events` | world_id, name, tag, description; tribe_id, player_id (unique), role; tribe_id, player_id, invited_by; tribe_id, other_tribe_id, state (ally/nap/enemy), confirmed_at, ends_at; tribe_id, type, payload, happened_at |
| `player_quests`, `player_counters` | player_id, quest, claimed_at; player_id, key, value. Progress is derived, not stored | | `player_quests`, `player_counters` | player_id, quest, claimed_at; player_id, key, value. Progress is derived, not stored |
| `level_rewards` | player_id, village_id (where reached), type, level, reward json, reached_at, claimed_at null. unique(player_id, type, level) | | `level_rewards` | player_id, village_id (where reached), type, level, reward json, reached_at, claimed_at null. unique(player_id, type, level) |
| `reports` | player_id, type (attack/defense/support), payload json (a snapshot with village names, units, losses, loot), happened_at, read_at | | `reports` | player_id, type (attack/defense/support/trade), payload json (a snapshot with village names, units, losses, loot), happened_at, read_at |
| `game_events` | world_id, type, subject_type, subject_id, fire_at datetime(3), processed_at null, attempts. index(processed_at, fire_at) | | `game_events` | world_id, type, subject_type, subject_id, fire_at datetime(3), processed_at null, attempts. index(processed_at, fire_at) |
## Event engine ## Event engine
@ -256,6 +260,22 @@ The visibility radius decides two things:
See "Tribes". Encounters (M5) will check hostility at encounter time, not at send time. See "Tribes". Encounters (M5) will check hostility at encounter time, not at send time.
## Market
Merchants carry wood, clay and iron between player villages (`config/game/market.php`, rules in `TradeRules`, rows in `Market`). Food is not traded yet.
- The market (`market`, one per village, needs headquarters 3 and storage 2) has merchants by its level, from Die Stämme's table (`buildings.market.merchants`: 1 at level 1, 11 at 11, 235 at 25). Staffing doesn't change them. A merchant carries `carry` (1000), so n resources need ceil(n / 1000) merchants.
- Busy merchants are the ones on the village's trades, out and back, plus the ones its open offers reserve. The rest are free, never fewer than 0.
- Merchants take `minutes_per_field` (6) per field, divided by the world speed and `movement.unit_speed` like troops. Travel modes don't apply.
- `market.send` takes the resources from the stock and the merchants leave at once, as a `trade` movement with `merchants` and `cargo`. It arrives by the target's `movement.arrives` event like troops (`Rally::arrive` hands it to `Market`), and reading the sender catches up the target first. The cargo goes into the target's storage, settled first; what doesn't fit is lost. The merchants turn round as a `trade_return` that takes as long as the way there, and are free again when it arrives.
- Trades are not troops. They never fight, are never attacked and can't be called back. They stay out of the rally lists, the incoming count, `map.view` and the noble slots. `market.show` lists them: `out` and `back` for the village's own merchants, `in` for anyone's merchants coming with cargo.
- **Offers** (`trade_offers`): a village offers `count` times an amount of one resource for an amount of another. Neither amount may be more than `max_ratio` (3) times the other. The goods for the whole count and ceil(amount / carry) merchants per unit are reserved at once. Cancelling gives back the goods of the open count, up to the storage, and frees the merchants. Another player takes part or all of the count: their merchants carry what the offer asks, the offer's reserved merchants carry what it gives, and both leave at once. The offer row stays locked meanwhile, so two buyers can't take the same count. `market.offers` lists the world's open offers, nearest first, at most 100.
- **Trade routes** (`trade_routes`): a shipment to another player village, repeated every `every` seconds, from `route.min_every` (10 minutes) to `route.max_every` (a week), at most `route.max_routes` (10) per village. These are real seconds: a route runs on the player's clock, not on world time. Each run is a `trade.route` event on the origin at `next_at`, the first one `every` after the route is made. A run sends of each resource what the route asks for as far as the stock has it, scaled down evenly to what the free merchants carry. With nothing in stock or no free merchant, nothing goes this time. Either way the next run comes `every` after this one, and `last_sent_at` and `last_cargo` record the run (all 0 when nothing went).
- A route remembers the target's owner. If the target has another owner when a run comes, the route pauses itself (`paused_reason: owner_changed`) instead of sending. Resuming plans the next run `every` from now and accepts the new owner. A new interval also counts from now.
- A `trade` report (`{from, to, cargo, offer}`) goes to the receiving player when the cargo arrives, and to the sender too. Deliveries between one player's own villages write none.
- A village that changes hands or turns barbarian (`Nobility::release`) loses its trades under way, out and back, its open offers with the goods they reserved, and its routes. Trades coming to it from others still arrive. On an ended world every market change is refused (`world_ended`) and routes stop sending; looking stays allowed.
- The village payload carries `market: {building_id, level, merchants, free, carry}`, or null without a market. The engine pushes `village:updated` to the target when a trade arrives, to the home village when the merchants are back, and to both villages when an offer is accepted.
## Raids ## Raids
Barbarian camps raid the player villages around them (`config/game/raids.php`, rules in `Raids`, rows in `Raiders`), so a village has something to defend against even on a quiet world. Barbarian camps raid the player villages around them (`config/game/raids.php`, rules in `Raids`, rows in `Raiders`), so a village has something to defend against even on a quiet world.

View File

@ -75,7 +75,7 @@ The world pushes back, so a world with few players is a game too: something thre
## M5: Trade and encounters ## M5: Trade and encounters
- [ ] Market and merchants: caravans with optional escort and travel mode, `food_deliveries` and the 24h import average - [x] Market and merchants, partly: the market with merchants per level, sending resources, offers between players and repeating trade routes. Still open: escorts and travel modes for caravans, encounters, food deliveries (`food_deliveries`) and the 24h import average
- [ ] `EncounterFinder` (closest approach of two linear paths) with unit tests - [ ] `EncounterFinder` (closest approach of two linear paths) with unit tests
- [ ] Encounter events: field battles, caravan looting, skipping destroyed groups - [ ] Encounter events: field battles, caravan looting, skipping destroyed groups
- [ ] Barbarian ambushes with seeded RNG - [ ] Barbarian ambushes with seeded RNG