From b7b209692d157cb03ac858b18d1df2bd818d9f32 Mon Sep 17 00:00:00 2001 From: "Fabian @ Blax Software" Date: Thu, 29 Oct 2026 10:05:55 +0100 Subject: [PATCH] docs: quest book and level rewards Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/architecture.md | 11 +++++++++++ docs/roadmap.md | 1 + 2 files changed, 12 insertions(+) diff --git a/docs/architecture.md b/docs/architecture.md index 83e9f9e..cef5020 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -97,6 +97,15 @@ Units live in `config/game/units.php` (Die Stämme-like stats): the building typ - 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. - 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. +## Quest book + +The quest book guides new players through the game in parallel lines (`config/game/quests.php`): construction, army, and village, which covers what Die Stämme doesn't have (staffing priorities, a second instance, the levy). A line shows its first unclaimed quest; claiming it (`quest.claim {village_id, quest}`) pays its resources into that village, up to what the storage holds, and opens the next one. Titles and texts are client i18n. + +- Goals are `building` (a type at a level in any of the player's villages), `instances` (that many of a type in one village) or `counter` (an action done that often). `QuestBook` (pure) measures them against `Facts` gathered per read; only claimed quests are stored (`player_quests`), so progress never drifts from the village. +- Counters live in `player_counters`, bumped by the actions (`Quests::bump`): `recruited.`, `attacks.sent`, `attacks.barbarian`, `scouts.sent`, `support.sent`, `village.renamed`, `priority.set`, `levy.called`, `reports.read`, and `map.viewed` (set once, not counted). `ConfigLint` proves every goal can be met. +- **Level rewards**: the first time a player reaches a level of a building type (any village, any instance), `quests.level_reward_share` (20%) of what that order cost waits in `level_rewards`. `quest.collect {village_id, ids?}` pays them into the current village. Demolishing pays nothing, and a second instance at the same level pays nothing again. +- `quest.index {village_id}` returns the lines, the rewards waiting, and what the next level of each building in the village would pay back. The village payload carries `quests: {claimable, rewards}` for the badge; the client opens the book by itself when `claimable` goes up. + ## No locks A village may fail through war or bad play, but it must never get stuck. Every lock below has a way out in the rules, and each one marked "lint" is proven by `ConfigLint`, which runs as a Pest test against the default config and every world's overrides. @@ -148,6 +157,8 @@ A building entry looks like this (numbers start TW-like): | `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 | | `tribes`, `tribe_members`, `tribe_relations` | name, tag; player_id, role; tribe_id, other_tribe_id, state (ally/nap/enemy). Arrives in M6 | +| `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 | | `game_events` | world_id, type, subject_type, subject_id, fire_at datetime(3), processed_at null, attempts. index(processed_at, fire_at) | diff --git a/docs/roadmap.md b/docs/roadmap.md index 33f3428..08e5e8d 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -51,6 +51,7 @@ Each milestone ends with tests green, `ConfigLint` green, and something playable What Die Stämme has at this stage that the game still lacks. +- [x] Quest book: construction, army and village lines with goals and rewards; a reward for every building level reached the first time - [x] Scouts: a scout unit, scouts meet scouts first, scouting reports (troops, resources, buildings) - [x] Battle simulator at the rally point (`CombatResolver` over WS, nothing changes) - [ ] Troop templates at the rally point, "repeat attack" from a report