Lineage — Endgame Expansion Design

Status: APPROVED 2026-05-16 — Phase 1 in progress this session

Lineage's mid-game is well-tuned: claim territories, build economy, train armies, research toward victory. Its endgame is hollow: once a player has filled their building slots and accumulated 5+ territories, the game offers no new construction, no new units, and no new threats — only a long grind toward a victory threshold (50% territory, 100k gold, all 5 legendary techs, etc.) with the same toolkit they had at turn 10.

This expansion adds three pillars of late-game content that compose with the existing systems rather than bolting on a parallel game.

Customer Feedback Origin (2026-05-13/14)

Player AMAUJLNE... wrote three feedback rows in 24 hours:

ID	Feedback	Identifies
5609	"when are you gonna give us new commands to extend our kingdom with buildings"	Building slot cap — no late-game building
5610	"how do you build buildings in new territories"	Discoverability — per-territory build UX
6086	"thank you for fixing the territory situation but how do we attack and progress now that our territories are full"	Post-territory progression gap

Notification message sent to AMAUJLNE 2026-05-15 acknowledging the work.

The literal asks are answered by three native, composable additions: building upgrades (deepens construction inside existing slots), legendary units (deepens warfare past ELITE), and endgame threat events (gives "what now" content after territory saturation).

Design Pillars

1. Native, not bolted-on — every new feature reuses existing infrastructure: TerritoryBuilding.level, , event pool, map.
2. Gated by existing progression — legendary units gated by LEGENDARY_WARFARE tech (20-turn research), endgame events gated by ≥5 territories or turn ≥30. No new gating systems.
3. Spending sinks before victory — give players reasons to keep accumulating gold/resources after their territory and base economy are saturated.
4. Phase 1 ships the highest-impact subset — building upgrades, legendary units, and one threat event ship together. Phase 2 deepens the threat pool and adds post-victory Empire tier.

---

Pillar A — Building Upgrades (Phase 1)

Problem (feedback 5609)

After ~10 turns of construction in a single territory and 1-2 expansion territories, the player has filled every building slot. The build menu still works but every action returns "you already have a X here." There is no further investment path inside an existing territory.

Solution

Buildings already have a level field (1-5 typical) on TerritoryBuilding and .getProduction(buildingType, level) already scales production linearly by level. The handler currently always sets level=1 and never increments. Wire a new upgrade [building] command that increments a building's level (cap at 5) for an escalating gold cost.

NLU

New Tier 4 pattern in :

^(?:upgrade|improve|level\s*up)\s+(?:\b(?:a|an|the)\b\s+)?
  ([a-z_\s]+?)
  (?:\s+(?:in|at|on)\s+(?:territory\s+)?(\d+))?\s*$

The building name is normalized via LineageSynonymResolver.normalizeBuilding. If the name is not a known building, the pattern returns null so it falls back to other parsers / FALLBACK (does not eat unrelated free-text).

Runs AFTER kingdom-rename, recruit, build, assign-workers, and BEFORE enhance-territory (whose pattern matches bare "upgrade" / "upgrade territory N"). The enhance pattern does not match "upgrade farm" because its inner group is (?:territory|capital|land)? followed by optional digit only — the new upgrade-building pattern requires a building-name token after the verb. Ordering keeps the existing enhance behavior intact.

Routes to a new FreeTextDeclarationAction.LINEAGE_UPGRADE_BUILDING with matchedKey = BUILDING_TYPE [IN TERRITORY N].

Regression fix (fb 7088/7131/7144): a stale process_one_shot_values row 7760 (LINEAGE_BUILD | KEY | "upgrade " | BLOOD_LINEAGE) was intercepting upgrade <building> at the one-shot tier (Tier 4) BEFORE (Tier 5). The result: handleBuild replied "you already have a X" and never leveled the building. Only upgrade farm appeared to work, because the build menu's upgrade-farm option matches at the OPTIONS tier (Tier 3) first; every other upgrade <building> was lost. (improve/level up had no such one-shot and always routed correctly.) Fixed in code so the fix is version-controlled and deploy-safe: detects an upgrade verb on the original utterance and delegates to handleUpgradeBuilding, and handleUpgradeBuilding strips a leading upgrade verb from matchedKey so the building name resolves from every routing path. One-shot 7760 is now harmless but semantically stale; removing it is optional follow-up cleanup. Locked by scenario_test 1501 (build mine; upgrade mine).

Cost Formula

upgradeCost(buildingType, currentLevel) = BUILDING_COSTS[buildingType] * currentLevel

So a 100g FARM goes:

• Level 1 → 2: 100 gold
• Level 2 → 3: 200 gold
• Level 3 → 4: 300 gold
• Level 4 → 5: 400 gold

Total to max-level a FARM: 1000 gold (10x base build cost over 4 upgrades).

A 500g MAGE_TOWER:

• Level 1 → 2: 500 gold
• Level 2 → 3: 1000 gold
• Level 3 → 4: 1500 gold
• Level 4 → 5: 2000 gold

Total to max: 5000 gold. Mage Tower / Mana Well max-level provides a serious mana economy late game.

Cap

Level 5 max. Pattern returns Building is already at maximum level. on attempted overflow.

Production Effect

Already wired via .getProduction(buildingType, level) which multiplies base rates by level. So a level-5 FARM produces 125 food/turn (5 × 25), level-5 MARKET produces 100 gold/turn, level-5 MANA_WELL produces 50 mana/turn (versus 10 base).

Status Display

already iterates buildings and would benefit from showing the level — Phase 2 polish, not in scope here.

Edge cases

• Buildings without production (BARRACKS, ARMORY, CITY_WALLS, etc.) can still be upgraded — higher levels reserved for future per-building tier effects (e.g., ARMORY level 2 unlocks better unit upkeep). Phase 2 attaches mechanical effects beyond raw production.
• Territory targeting reuses the same extractedTerritoryIndex / possibleNumbers mechanism as handleBuild.
• Territory picker (fb 9071): a bare upgrade <building> used to always resolve to the capital, so the same building in a second territory was unreachable without saying in territory N. When the building stands in 2+ owned territories and the player named none, handleUpgradeBuilding now shows a territory picker (mirroring the recruit army picker) whose options carry UPGRADE_PICK_TERRITORY_<idx>_<BUILDING>; selecting one upgrades that copy. also surfaces a tappable upgrade <building> in territory N option per owned-territory building. scenario_test 2202.

---

Pillar B — Legendary Unit Tier (Phase 1)

Problem

ELITE units (strength 40) cap the recruitment tree. Players who research LEGENDARY_WARFARE (a 20-turn endgame tech) get no recruitment payoff. Battles at endgame become "stack more ELITE."

Solution

Three new units gated behind LEGENDARY_WARFARE technology:

Unit	Strength	Cost (gold)	Upkeep	Gate
DRAGON_KNIGHT	60	1200	24	requires LEGENDARY_WARFARE
ARCHMAGE	70	1500	30	requires LEGENDARY_WARFARE
WAR_TITAN	100	3000	60	requires LEGENDARY_WARFARE

Numbers chosen so:

• DRAGON_KNIGHT (60) ≈ 1.5× ELITE (40) — first legendary tier, only modestly stronger
• ARCHMAGE (70) ≈ 2.3× BATTLE_MAGE (30) — magical analog
• WAR_TITAN (100) = 2.5× ELITE — apex unit, prohibitively expensive to mass

Upkeep at 2% of cost matches the existing comment ("Approximately 2% of recruitment cost — military must be viable as a parallel strategy to economic play").

Wiring

• Add to , UNIT_COST, UNIT_UPKEEP (centralized, no duplicate map override needed in handler).
• Add unit synonyms to LineageSynonymResolver and normalizeUnitPluralForm (DRAGON_KNIGHTS → DRAGON_KNIGHT, ARCHMAGES → ARCHMAGE, WAR_TITANS / TITAN / TITANS → WAR_TITAN).
• Gate enforcement in : before deducting cost for a unit in LEGENDARY_UNITS set, check kingdom.getDiscoveredTechnologies().contains("LEGENDARY_WARFARE") and reject with a clear message if not.

Voice copy on rejection: "You need to research Legendary Warfare before you can recruit Dragon Knights. Researching Legendary Warfare unlocks the most powerful unit tier in the realm."

Voice Compatibility

Voice readouts use natural-language pluralization. The existing pluralize helper handles WAR_TITAN → "War Titans" (suffix +s rule); DRAGON_KNIGHT → "Dragon Knights" (suffix +s rule); ARCHMAGE → "Archmages" (suffix +s rule). No new voice-rule edge cases.

---

Pillar C — Endgame Threat Events (Phase 1)

Problem (feedback 6086)

Once a player has 5+ territories, the existing event pool (BOUNTIFUL_HARVEST, PLAGUE, TRADE_CARAVAN, etc.) feels small-scale. There is no "what now, this is escalating" content. The map fills, the kingdom plateaus, and the game stops feeling alive.

Solution

Add a new event type, BARBARIAN_HORDE, that ONLY fires when the kingdom holds ≥5 territories OR turn ≥30. Fires through the same 10% per-turn event roll but is selected from the endgame pool instead of the generic pool when the kingdom qualifies.

BARBARIAN_HORDE

"Scouts return at dawn with grim news. A barbarian horde, ten thousand strong, has crossed the eastern frontier. Their warlord is said to wear the skull of a giant on his belt. Your weakest territory lies directly in their path."

Three choices:

#	Choice	Effect
1	"Meet them in battle"	Lose 25% of strongest army. If army survived: +800 gold spoils, +10 morale (your veterans return triumphant).
2	"Pay tribute"	-1500 gold. Horde departs. -5 morale (your people whisper about cowardice).
3	"Fortify and wait them out"	-200 stone. All territories gain +30 effective defense for 5 turns (KingdomBonus). Horde harasses but does not seize.

Expiration penalty (3 turns no response): horde overruns the weakest territory — territory loses 30% population, all buildings deactivated for 3 turns.

Phase 2 Threat Pool (NOT IMPLEMENTED THIS SESSION)

Documented for the future expansion of the endgame event pool:

Event	Trigger	Resolution Theme
DRAGON_AWAKENS	turn ≥40 + has BASIC_MAGIC	Tribute, battle, or magical pact
RIVAL_DYNASTY	turn ≥50 + ≥10 territories	New aggressive AI kingdom spawns at map edge
ANCIENT_CURSE	turn ≥35 + has TEMPLE	Random territory loses production unless mana paid
CROWN_OF_REALM	50% territories held for 10 consecutive turns	+5000 prestige, DRAGONBLOOD auto-grant, milestone

---

Pillar D — Empire Tier (SHIPPED — see empire-4x-layer.md, not built here)

Status update: the design sketched below (Empire tier, Empire Edicts) shipped as SE-1 of empire-4x-layer.md — "Empire Tier core + Empire Screen + Edicts", 2026-06-19. The live implementation is + (voice command: LINEAGE_VIEW matched key EMPIRE), reached via

• LineageViewType.EMPIRE. The four edicts below (Peace/Conquest/Prosperity/Legacy) shipped with the same costs and effects sketched here — this section is now the ORIGIN DESIGN, not the current spec. Read empire-4x-layer.md for the live system (Empire Screen voice-memory rules, edict menu behavior, code locations); do not treat this section as unbuilt.

Concept (as originally sketched — now built)

After a victory of any type, instead of ending the game, the dynasty enters EMPIRE tier:

• Game continues. World reseeds with rebellious vassal AI kingdoms (former AI kingdoms claim independence, starting hostile).
• Player gains +10 prestige points per turn passively.
• New action class: Empire Edicts — one-shot powerful kingdom-wide buffs costing prestige:
  • Edict of Peace (500 prestige): -20 unrest in every owned territory.
  • Edict of Conquest (750 prestige): +30% army strength for 3 turns.
  • Edict of Prosperity (500 prestige): +50% gold production for 3 turns.
  • Edict of Legacy (1000 prestige): +1 carried trait slot for next dynasty (composes with Track B from prestige.md).

Why it took a second wave

Empire tier required significant refactoring of (the pre-SE-1 path set world.isCompleted = true and stopped processing). That refactor plus the Empire Screen and Edicts landed together in SE-1 as part of the broader 4X depth build-out (gd-04, decision 285) — not in the Phase 1 session that shipped Pillars A-C.

---

Rollout Phases

Phase 1 — Land This Session

• Design doc (this file) — captures direction with rationale, links to feedback 5609/5610/6086.
• Pillar A — Building upgrades with NLU + handler + cost formula.
• Pillar B — Three legendary units in + tech gate in handler.
• Pillar C — BARBARIAN_HORDE event in event generator + endgame-pool selection in random event service.
• Scenario tests covering each new feature.
• Java build green.
• Feedback 5609 / 5610 / 6086 in-game answer paths documented (upgrade verb, build-in-territory verb, BARBARIAN_HORDE).

Phase 2 — Future (separate epic)

• Dragon Awakens, Rival Dynasty, Ancient Curse, Crown of the Realm events.
• Building upgrade level shown in output.
• Per-building level effects beyond pure production (e.g., ARMORY-2 unlocks higher armor tier, ACADEMY-5 unlocks 2 buildings per turn).
• Empire tier (Pillar D) — SHIPPED as empire-4x-layer.md SE-1 (2026-06-19), not in this Phase-2 batch. Post-victory progression, Empire Edicts, and vassal rebellion are live via .
• Frontend BuildingLevelPanel showing each building level and upgrade cost preview.

---

Acceptance Criteria (Phase 1)

• A new Blood Lineage kingdom can say "upgrade farm" and see their farm level rise from 1 to 2, paying 100 gold.
• Attempting to upgrade a max-level building emits "already at maximum level" instead of charging.
• Attempting to recruit DRAGON_KNIGHT without LEGENDARY_WARFARE researched returns the gated message naming the tech.
• After researching LEGENDARY_WARFARE, "recruit 5 dragon knights" succeeds at 6000 gold cost (1200 × 5).
• A kingdom on turn 30 with 5 territories has a chance to receive a BARBARIAN_HORDE event each turn from the endgame pool.
• Each new feature has a passing scenario_tests row.
• Java build green via build({ action: "build", targets: ["java"] }).
• The three feedback rows (5609, 5610, 6086) have in-game answer paths discoverable from the build menu, recruit menu, or event flow.

---