Blood Lineage — Spoken State-of-the-Realm Return Briefing

Status: IMPLEMENTED 2026-06-17 — E1 snapshot, E2 delta, E3 adaptive length + drill-down + NLU all shipped. Code: (briefing + delta), LineageBriefingSnapshot (delta store on ), (hook point), LineageViewType.BRIEFING + (the 'tell me more' route). Regression: JUnit (delta + succession-while-away), scenario_tests 2144 (launch structure) + 2145 (tell-me-more drill-down). Snapshot reconciled with this doc 2026-06-21: the realm line now names the lowest critically-low material, and the threats line surfaces a running food deficit projected to starve the realm within ten turns. Added regression: (lowestCriticalResource / realmLine / foodThreatFragment / netFoodPerTurn) + scenario_test 2321 (deficit threat at a comfortable stockpile).

Parent: index.md. Siblings: progression.md, kingdom.md, military.md, diplomacy.md, four-x-systems.md. Voice standard: ../../philosophy/player-experience.md. Source: game-design-audit gd-04 (process-reports report 3, finding 13) — the audit's flagged best easy win for the voice-memory-load problem.

The problem (gd-04)

Blood Lineage is a turn-based 4X with no screen. The state a player must hold in their head is large: seven resources, population, morale, stability, a map of owned territories with buildings and fortifications, multiple armies with stances and positions, a ruler who ages and can die, an heir line, a web of treaties and AI relations, research in progress, pending random events, and progress toward five victory conditions. On a screen that lives in panels the player can glance at. In voice, it lives only in the player's memory — and between sessions (often days; in Global mode turns process weekly) that memory is gone. A returning player relaunches and has no idea where their realm stands, what threatened it, or what happened while they were away. That cognitive cliff is a primary reason a voice 4X loses returning players.

Thesis — turn the memory-load into charm

A 4X UI would solve this with a dashboard. Voice can do something a dashboard cannot: brief the player like a steward addressing their returning liege. Instead of asking the player to remember their realm, the game tells them — concisely, in-character, leading with what is urgent — the moment they return. The memory burden becomes a moment of immersion: "Welcome back, my liege. Here is where your realm stands." This is the cheapest high-leverage fix in the game because every piece of state it narrates already exists and is already loaded at session entry; the briefing only has to read and speak it.

What it is

A spoken state-of-the-realm briefing delivered automatically on session entry, in two parts: a snapshot of where the realm stands now, and a delta of what changed since the player was last here. It ends by handing the player a clear next action and a "tell me more" drill-down. It is a readout, not a new mechanic — it never changes state, costs nothing, and reads only what is already persisted.

When it fires

• On session entry / launch, AFTER the existing forced-interaction gates resolve (a brand-new player still names their kingdom first via ; the briefing is for a returning player with an established realm, so it fires once the kingdom is loaded and named).
• Once per session. It does not repeat on every turn. A returning player hears it on the launch that resumes their game; mid-session they use the on-demand resource screen (four-x-systems.md) and status instead.
• It respects the meta-bypass allowlist (): a player who launches and immediately says "help"/"exit" is not trapped behind the briefing.
• It is skippable — "skip"/"continue"/"my realm" / any concrete game action cuts the briefing short and proceeds, exactly like an intro narrative. Never a dead-end.

Part 1 — the snapshot (where the realm stands)

Lead with the most urgent, then the durable. Speak only what matters; suppress empty sections (a realm at peace does not get a "no wars" sentence). Sourced entirely from the already-loaded LineageKingdom / world / armies / treaties / events / dynasty:

Briefing element	Source field(s)
Threats first — wars, an enemy army massed on a border, high unrest (85+ = rebellion risk), a pending event about to expire, famine/deficit	treaties at war, contested territories, territory.unrestLevel, pending LineageEvent expiry, resource deficits
Realm size + treasury — territories held, gold, and any resource that is critically low	territory count, resources (gold + the lowest critical resource)
Military — total army strength and where the main force sits, its stance	kingdom.armies (units → strength, location, stance)
Ruler + dynasty — ruler name, age, health if not HEALTHY, generation; an heir warning if the ruler is DYING with a weak or absent heir line, OR if there is no heir and no fertile path to one at all (unmarried, or the consort is past childbearing age) so a player who never married is told their line will end while there is still time to act (finding 900)	ruler (name/age/health), dynasty.generationNumber, heirs, ruler.spouse.canHaveChildren
Pursuits — research in progress and its ETA; the closest victory path	currentResearchId + progress, (the nearest condition)

Snapshot thresholds (implemented). The snapshot's two quantitative judgments are defined precisely so code and this doc cannot drift:

• Lowest critical resource (the realm line): the single lowest non-gold material — wood, stone, iron, or mana — whose stockpile sits below 50 is named ("though your iron stores run critically low"). Gold is always spoken, food is owned by the threats line, and gems are not a production constraint, so none of those are scanned here. A well-supplied or freshly-founded realm names nothing (starting mana is 75, already above the line). Selection is the lowest amount among the materials below the threshold.
• Food deficit (the threats line): beyond famine (consecutive zero-food turns) and a low stockpile (below 100), a running food deficit is surfaced when the net per-turn food flow is negative AND the current stockpile would empty within ten turns ("your granaries are emptying, with about N turns of food remaining"). This is what catches a deep realm bleeding food fast — a high stockpile losing a hundred a turn is days from starvation yet invisible to a stockpile-only check. A gentle deficit with more than ten turns of reserves is deliberately left unalarmed, since ample reserves are not urgent. Net flow mirrors the resource-screen formula (territory base yield + farms + food workers, minus population upkeep + army rations), so the briefing never contradicts what end turn actually does.

Part 2 — the delta (what changed while you were away)

The part that makes it a briefing and not just a status dump. Compute the change since the player's last session and narrate the events that matter:

• Turns elapsed since last seen (in Global mode this can be several weekly turns; in SP/MP it is the turns the player ended last session that resolved).
• What happened: random events that fired or expired (and any auto-penalty taken on an ignored event), combat results, diplomacy changes (a new war declared on you, a treaty broken or expired, an alliance formed), succession (the ruler died and an heir/regent took the throne — the single most important "you missed this" event), research completed, victory milestones awarded, a rebellion that fired from unattended unrest.
• Net economy since last session at a glance ("your treasury grew by N gold" / "you are now running a food deficit").

To compute the delta the game persists a lightweight last-briefing snapshot at session exit (or on each briefing): the last-seen turn number + a small set of key metrics (territory count, gold, ruler id/generation, army strength, active-war count, research id) on the account/profile. On the next entry the briefing diffs current-vs-snapshot and narrates only the meaningful changes. The snapshot is small and write-through; it never becomes a second source of truth for game state (the kingdom row remains authoritative).

Voice-first shape (mandatory)

Per ../../philosophy/player-experience.md: no parens, brackets, slashes, or abbreviations (Alexa reads it aloud); numbers spoken naturally; commas not bullet points. Concise — the snapshot is a few sentences, not an inventory. Lead with the one urgent thing. End with a concrete next action and the drill-down offer. Illustrative (not locked copy):

"Welcome back, my liege. While you were away, three turns passed and the Iron Compact declared war on your eastern border, where two hundred of your warriors hold the line. Your realm holds four provinces and six hundred gold, and your steel research finishes in two turns. Your ruler, Aldric the Second, is sixty eight and ailing, with one heir of age. Shall I tell you more, or say continue to keep playing?"

A realm at peace, mid-game, gets a calmer, shorter briefing. The briefing always ends on an actionable handoff, never a dead-end.

Handoff verb (finding 905). The resume prompt says "say continue to keep playing" and the resume option is labelled continue — NOT "take command". "Take command" read as a new action ("why take command when I already control the ruler?"); "continue" is the globally-recognized resume verb, so it resolves from any context, not only while the briefing options are shown. "take command" is retained only as a hidden synonym for players who learned it. Code:

• the two handoff addText lines. Guard: .

Adaptive length

Scale verbosity by how recently the player last played (mirrors Mystery's adaptive onboarding):

Time since last session	Briefing
Same day / very recent	One-line resume ("Welcome back. Nothing has changed since you left. Take command.") — the delta is empty, so skip Part 2 entirely.
A few days / 1-2 turns	Full snapshot + a tight delta.
Long absence / many turns (Global)	Full snapshot + a prioritized delta of the most important changes (cap the event list; log what was summarized rather than reading every one).

Drill-down

The briefing ends offering "tell me more." A "tell me more" / "what about my army" / "how is the war" / "tell me about my dynasty" routes to the matching existing detail surface (military / diplomacy / dynasty / the resource screen), so the briefing is the index and the existing commands are the chapters — no new detail handlers required.

Relationship to existing systems (do not duplicate)

• The on-demand resource screen (four-x-systems.md) is a pull surface the player asks for any time ("my resources", "state of the realm"). The return briefing is the push surface delivered once on entry. They share the same underlying reads; the briefing leads with threats + delta, the resource screen is the full standing ledger. The briefing's drill-down routes INTO the resource screen and status.
• status already gives context-aware next steps mid-session; the briefing is the richer, in-character, entry-only, delta-bearing cousin. The briefing does not replace status.

Out of scope (deferred per owner, 2026-06-16)

Meaningful New Game Plus depth and emergent-story hooks are explicitly deferred (human_idea 22102 decision: "Design return-briefing now, defer NG+"). They are already sketched in four-x-systems.md (Legacy screen + scaling founding headstart; Dynasty Chronicle) as future work — do NOT design or build them in this pass. This doc is the return-briefing only.

Where it hooks + data sources

• Hook point: the session-entry / relaunch path that loads the player's game (LineageGameLoader.loadSinglePlayerGame and the launch handler that renders the resume), after the forced-interaction gate, before handing the player the normal play surface.
• Data: all already loaded at entry — LineageKingdom (resources, population, morale, stability, armies, ruler, dynasty, heirs, currentResearch), the world/territories (count, unrest, contested), treaties + AI relations, pending/expired LineageEvents, .
• Delta store: the lightweight last-briefing snapshot on the account/profile (last-seen turn + key metrics). PROD is the source of truth; never read local.

Regression shape (hermetic)

Per .claude/rules/hermetic-scenario-tests.md:

• Hermetic game_test.scenario_tests (via add_scenario_test): seed a known kingdom state, launch, and assert the stable structure — the briefing opens with the in-character greeting, names the realm's territory count and treasury, and ends with an actionable next-action option. Assert the date/RNG-INDEPENDENT surface only; NEVER assert a specific random-event line or a turn-count that depends on the clock.
• Delta logic → JUnit: seed a before-snapshot + an after-state and assert the diff narrates the right changes (war declared, ruler succeeded, research completed) and suppresses unchanged sections. The succession-while-away case is the highest-value unit test.
• Snapshot judgments → JUnit: lowestCriticalResource, realmLine, foodThreatFragment, and netFoodPerTurn are pure over their inputs and unit-tested directly — the lowest-critical-material selection cannot be seeded through the scenario-launch setup (there is no per-material setter), so JUnit is its hermetic home. The running-deficit threat IS seedable (a large setPopulation forces a negative net flow), so scenario_test 2321 guards it end to end at a comfortable stockpile.
• Skip / meta-bypass → process_tests + scenario_test: "skip" and a meta-command on the briefing turn both escape cleanly (no dead-end).

Build epics (flagged — the queued chain implements these)

#	Epic	Scope
E1	Snapshot briefing	Read the loaded realm state and speak the threats-first snapshot on session entry (once per session, skippable, meta-bypass-respecting). Voice-first. Hermetic scenario_test on the stable structure.
E2	Delta / what-changed-since-last-session	The last-briefing snapshot store + the diff narration (turns elapsed, events, combat, diplomacy, succession, research, net economy). Succession-while-away JUnit.
E3	Adaptive length + drill-down + NLU	Verbosity scaling by absence length; "tell me more" + per-topic drill-down routing into existing detail surfaces; process_tests for the briefing/skip/drill-down phrases.

Each epic is game-engine code and carries the per-commit game_test.scenario_tests obligation (.claude/rules/deploy-gating.md) and updates this doc + index.md (repository root) in the same change. NG+ / emergent-story remain OUT of scope.

Related docs

• four-x-systems.md — the on-demand resource screen (complement) + the deferred NG+ / Dynasty Chronicle.
• progression.md — turn pipeline, succession, events, victory (what the delta narrates).
• index.md — realm state model + the forced-interaction / meta-bypass entry gates the briefing sits behind.
• ../../philosophy/player-experience.md — voice-first, never-dead-end.
• .claude/rules/hermetic-scenario-tests.md — the regression discipline for the entry-time, delta-bearing surface.