From 7303817911846693b6c4e96b6ffb5891b0041a29 Mon Sep 17 00:00:00 2001 From: "Fabian @ Blax Software" Date: Sat, 31 Oct 2026 11:04:45 +0100 Subject: [PATCH] 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) --- docs/architecture.md | 28 ++++++++++++++++++++++++---- docs/roadmap.md | 2 +- 2 files changed, 25 insertions(+), 5 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 5b7e176..02de396 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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/Frontier.php where new villages settle as the world grows Travel/TravelTime.php + Trade/TradeRules.php merchants, their pace, fair offers, route shipments Combat/CombatResolver.php Combat/LootCalculator.php 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. | | 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. | -| 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. | | 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/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): @@ -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 | | `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 | -| `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 | | `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) | -| `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) | ## 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. +## 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 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. diff --git a/docs/roadmap.md b/docs/roadmap.md index 3cecc58..44d06c9 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -75,7 +75,7 @@ The world pushes back, so a world with few players is a game too: something thre ## 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 - [ ] Encounter events: field battles, caravan looting, skipping destroyed groups - [ ] Barbarian ambushes with seeded RNG