feat: add bookmark scenario, province history, and design docs

Add "The End of an Empire" bookmark with event planning, bookmark game data, province history, and localization. Include project masterplan and design ideas documents. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-07 15:00:31 +01:00
parent 04a788aca6
commit 96215ef3fc
6 changed files with 1670 additions and 0 deletions
@@ -0,0 +1,503 @@
+# MASTERPLAN — Lords of Ash
+
+## Vision
+
+A Crusader Kings III total conversion set in Brandon Sanderson's Mistborn: The
+Final Empire. The player experiences the world of Scadrial through the "End of
+an Empire" bookmark — playing as Kelsier leading his unlanded crew, or as Vin
+navigating a world of noble intrigue and Allomantic power. A game rule toggle
+lets players choose between Narrative Mode (curated story arcs following the
+book's plot) and Sandbox Mode (play any character, acquire metallic arts via
+decision). The mod is rich with Sanderson lore, features a custom Scadrial map,
+full graphics, and deep event content.
+
+**Done** means: Steam Workshop release quality. A player installs the mod, picks
+the "End of an Empire" bookmark, chooses Kelsier or Vin, and plays through a
+complete Mistborn: The Final Empire experience — from crew assembly through the
+Fall of Kredik Shaw — on a custom Scadrial map with custom art, polished
+balance, and clean error logs. Alternatively, they can flip to Sandbox Mode and
+play any house lord with full metallic arts mechanics.
+
+**DLC dependency:** Roads to Power (unlanded adventurer band system).
+
+---
+
+## Current State
+
+Strong foundation, not yet playable.
+
+**What exists:**
+- 12 Misting traits + Mistborn + strength tiers + potentials
+- Feruchemy (full Feruchemist + potential)
+- Hemalurgy (5 spike types + Inquisitor creation)
+- Compounding detection on yearly pulse
+- Lord Ruler Attention system (0-100, 3-tier escalation events)
+- 4 religions (Steel Ministry, Terris, Survivorism, Cult of Ruin), 5 holy sites
+- 3 cultures (noble_scadrian, skaa, terris) with pillars and traditions
+- 10 dynasties (Great Houses), 20+ placeholder characters
+- 5 kingdoms, duchies, counties, baronies mapped to vanilla Swiss provinces
+- 4 decisions (balls, snapping, kandra, hemalurgy)
+- 8 event files (~2,700 lines, several are stubs)
+- 4 men-at-arms types
+- Full localization coverage (874 lines across 9 files)
+- Bookmark definition (bm_end_of_an_empire) with 4 placeholder characters
+
+**What's missing or broken:**
+- Province history files are empty (mod may crash on load)
+- `@#` comment syntax in several files (CK3 uses `#`)
+- Characters are placeholders, not canonical Mistborn figures
+- No custom map (using vanilla provinces)
+- No graphics (trait icons, portraits, loading screens)
+- No unlanded band system
+- No custom name lists
+- No vanilla content suppression (vanilla decisions bleed through)
+- No game rule definitions
+- No custom buildings, schemes, or casus belli
+- Several event files are stubs (~20% content)
+- Lord Ruler not implemented as a character
+- `e_final_empire` has no holder
+
+---
+
+## Milestones
+
+Each milestone is a **playtesting anchor** — the mod loads, the new features are
+functional enough to test, and friends can give feedback. Rough edges and
+placeholder content are acceptable. Steam-release polish happens in M8.
+
+---
+
+### M1: Foundation
+
+*The mod loads and plays cleanly on the vanilla map.*
+
+**Scope:**
+- Fix province history — create `history/provinces/` files assigning culture,
+  religion, and holdings for all mapped provinces
+- Fix `@#` comment syntax to `#` in all affected files
+- Verify all modifier definitions exist and match their localization keys
+- Fix scripted trigger issues:
+  - `is_feruchemist_trigger` should not match dormant potential
+  - `has_allomantic_potential_trigger` should distinguish active vs dormant
+- Unify the dual Lord Ruler attention system (variable-based + modifier-based)
+- Add `trait_knows_hemalurgy` (referenced by decision but undefined)
+- Suppress vanilla decisions that break immersion — create empty replacement
+  files in `common/decisions/` for vanilla decision files
+- Define game rule infrastructure in `common/game_rules/` (Narrative vs Sandbox
+  toggle, even if not yet meaningful)
+- Boot test — load mod, verify error.log is clean, play 5 years
+
+**Key files:**
+- `history/provinces/` — new files (one per province or grouped by dominance)
+- `common/scripted_triggers/mistborn_triggers.txt`
+- `common/scripted_effects/mistborn_effects.txt`
+- `common/modifiers/00_mistborn_modifiers.txt`
+- `common/game_rules/` — new directory and file
+- `common/decisions/` — vanilla suppression files
+
+**Exit criteria:** Mod loads with no errors. No vanilla decisions visible. Game
+rule appears in setup screen. Play a landed noble for 5 years without crashes.
+
+---
+
+### M2: The Metallic Arts
+
+*All metallic arts systems are complete and tested.*
+
+**Scope:**
+- Validate and polish all Allomancy traits — inheritance chances, trait
+  interactions, icon references
+- Complete the snapping event chain — all outcomes, edge cases, forced snapping
+- Add Allomantic Training event chain (education-style, mentor teaches pupil,
+  choices influence specialization, grants `allomantic_strong` on completion)
+- Validate Feruchemy system — ensure Terris-only inheritance, Keeper mechanics
+- Validate Hemalurgy — spike application events, Inquisitor creation, Ruin
+  influence consequences
+- Validate Compounding — yearly pulse detection, correct trait pair matching,
+  compounder modifier balanced
+- Add savant consequences (negative effects for `trait_allomantic_savant`)
+- Balance men-at-arms types (Hazekillers, Koloss, Mistborn Agents) — damage,
+  toughness, cost, terrain modifiers
+- Polish existing event files — complete stub events in `hemalurgy_events.txt`,
+  `atium_events.txt`, `skaa_events.txt`, `skaa_allomancer_events.txt`
+- Add Sandbox Mode decision: "Discover Your Metallic Arts" — lets any character
+  test for Allomantic/Feruchemical potential (only in Sandbox game rule)
+- Localization for all new content
+
+**Key files:**
+- `common/traits/` — all 6 trait files
+- `events/snapping_events.txt`
+- `events/hemalurgy_events.txt`, `atium_events.txt`, `skaa_events.txt`,
+  `skaa_allomancer_events.txt`
+- `common/on_action/mistborn_on_actions.txt`
+- `common/decisions/00_mistborn_decisions.txt`
+- `localization/english/mistborn_traits_l_english.yml`
+- `localization/english/mistborn_events_l_english.yml`
+
+**Exit criteria:** Snap a character into a Misting or Mistborn. Train an
+Allomancer pupil. Create a Steel Inquisitor via Hemalurgy. Trigger Compounding.
+Use Sandbox decision to gain powers. All metallic arts events fire correctly.
+
+---
+
+### M3: The Final Empire
+
+*Canonical characters populate the world. The Lord Ruler looms over everything.*
+
+**Scope:**
+- Design and implement the Lord Ruler as off-map religious head:
+  - Change Steel Ministry doctrine from `doctrine_no_head` to spiritual head
+  - Create Lord Ruler as immortal character (Compounder: Allomancy + Feruchemy +
+    atium bracers)
+  - Assign as `e_final_empire` holder and Steel Ministry religious head
+  - Make non-playable via scripted trigger or game rule
+  - Lord Ruler attention events now reference him directly
+- Create canonical characters with appropriate traits:
+  - **Kelsier** — Mistborn, ambitious, brave, scarred (Pits survivor)
+  - **Vin** — Mistborn potential (pre-snap), paranoid, young
+  - **Sazed** — Feruchemist, Terris Keeper, scholarly
+  - **Breeze** — Soother, noble-born skaa
+  - **Ham** — Thug, philosophical
+  - **Clubs** — Smoker, gruff veteran
+  - **Dockson** — no Allomancy, organizer
+  - **Marsh** — Seeker, later Inquisitor
+  - **Yeden** — skaa rebel leader
+  - **OreSeur** — kandra (needs kandra trait)
+  - **Elend Venture** — heir to House Venture, bookish
+  - **Straff Venture** — head of House Venture, Tineye
+  - **Shan Elariel** — Mistborn, noble rival
+  - **Steel Inquisitors** — Hemalurgic super-soldiers
+  - Other Great House heads matching existing dynasties
+- Keep or rework existing placeholder characters as minor nobles where they fit
+- Create custom name lists for all 3 cultures in
+  `common/culture/name_lists/` — male, female, dynasty names drawn from
+  Mistborn lore
+- Create special buildings in `common/buildings/`:
+  - **Kredik Shaw** (Luthadel) — unique palace, prestige and control bonuses,
+    holy site building
+  - **Pits of Hathsin** — atium generation, tyranny cost, built by Lord Ruler
+  - **Conventical of Seran** — Inquisitor base, dread and martial bonuses
+- Polish religions:
+  - Steel Ministry: Lord Ruler as head, obligator hierarchy
+  - Terris Keepers: secret faith, forbidden knowledge mechanics
+  - Survivorism: hidden faith, rebellion bonuses
+  - Cult of Ruin: human sacrifice, Hemalurgy bonuses
+- Add kandra trait and kandra Contract mechanics (kandra characters are
+  shapeshifters bound by Contracts)
+
+**Key files:**
+- `history/characters/00_mistborn_characters.txt` — major rewrite
+- `history/titles/00_mistborn_titles.txt` — reassign to canonical characters
+- `common/religion/religions/00_scadrial_religions.txt`
+- `common/culture/name_lists/` — new directory
+- `common/buildings/` — new directory
+- `common/landed_titles/00_landed_titles.txt` — add special building slots
+- `localization/english/` — significant new localization
+
+**Exit criteria:** Start the game. Kelsier, Vin, Elend, and the Lord Ruler
+exist in the world. Lord Ruler is religious head of Steel Ministry. Kredik Shaw
+and Pits of Hathsin have special buildings. Names are Scadrial-appropriate.
+
+---
+
+### M4: Scadrial on the Map
+
+*The vanilla map feels like Scadrial. The mod is shareable.*
+
+**Scope:**
+- Relabel all vanilla provinces with Scadrial names in localization (players see
+  "Luthadel" not "Bern")
+- Set terrain types that evoke Scadrial:
+  - Mountains → Ashmounts
+  - Wasteland/desert → Ash plains
+  - Urban → Luthadel, major cities
+  - Hills → mining regions
+- Add province modifiers:
+  - `ash_blight` on ashmount-adjacent provinces
+  - `mist_heavy` on certain provinces (Allomancer snapping bonus)
+  - `fertile_ashland` on the few productive regions
+- Suppress remaining vanilla bleed-through:
+  - Empty replacement files for vanilla events that break immersion
+  - Suppress vanilla GUI text where possible via localization overrides
+- Create custom casus belli in `common/casus_belli_types/`:
+  - House War (noble house vs noble house)
+  - Rebellion (skaa vs noble/Lord Ruler)
+  - Inquisition Purge (Steel Ministry vs heretics)
+  - Dominance Claim (claim a Dominance title)
+- Create custom schemes in `common/schemes/`:
+  - Noble Infiltration (spy on a house via balls and agents)
+  - Raid House Vault (steal gold, reduce control)
+  - False Flag (hostile action that frames a third party)
+- Full testing pass — error.log review, 20-year playthrough, verify no vanilla
+  anachronisms visible
+
+**Key files:**
+- `localization/english/mistborn_titles_l_english.yml` — province renames
+- `common/casus_belli_types/` — new directory
+- `common/schemes/` — new directory
+- Province modifier definitions in `common/modifiers/`
+- `localization/english/` — new localization for CB, schemes, provinces
+
+**Exit criteria:** A friend can install the mod and play. The world feels like
+Scadrial — Scadrial names, ash terrain, Mistborn mechanics, no vanilla
+anachronisms. Custom wars and schemes work.
+
+---
+
+### M5: The Crew
+
+*Play as Kelsier's unlanded band. The bookmark works.*
+
+**Scope:**
+- Research Roads to Power adventurer band mechanics — understand band creation,
+  member management, decisions, event scoping, interaction with landed system
+- Implement Kelsier's crew as adventurer band:
+  - Kelsier as band leader
+  - Vin, Breeze, Ham, Clubs, Dockson, Marsh, Yeden, OreSeur as band members
+  - Vin playable as non-leader (investigate if CK3 supports this natively or if
+    events/decisions must simulate it)
+  - On Kelsier's death: Vin becomes band leader via event (martyrdom mechanic)
+- Create/update the "End of an Empire" bookmark:
+  - Kelsier (unlanded crew, difficulty: medium)
+  - Vin (crew member, difficulty: hard) — if non-leader play is feasible;
+    otherwise Vin is Kelsier's heir and unlocks on death
+  - Optional: keep 1-2 landed starts for house play (Elend Venture, etc.)
+- Activate game rule toggle:
+  - Narrative Mode: Kelsier/Vin bookmark, curated events fire
+  - Sandbox Mode: any character, "Discover Your Metallic Arts" decision
+    available, narrative events suppressed
+- Crew-specific decisions:
+  - Recruit a crew member (if starting with partial crew)
+  - Plan the next operation (menu decision branching to arcs)
+  - Lay low (reduce Lord Ruler attention at cost of momentum)
+- Non-DLC fallback: if Roads to Power not detected, Kelsier starts as landed
+  minor lord of a Luthadel slum barony
+
+**Key files:**
+- `common/bookmarks/00_mistborn_bookmarks.txt` — major rewrite
+- `common/decisions/` — crew decisions
+- `common/game_rules/` — activate toggle
+- `events/` — crew-specific events
+- `localization/english/` — bookmark text, crew decisions
+
+**Exit criteria:** Select "End of an Empire" bookmark. Play as Kelsier with
+crew. Recruit members. Game rule toggle works. If Kelsier dies, Vin takes over.
+
+---
+
+### M6: The Plan
+
+*The core story of Mistborn: The Final Empire is playable.*
+
+**Scope:**
+- **Crew Assembly arc** — recruit named crew members through skill checks and
+  events. Each recruitment has a cost (gold/prestige) and a narrative moment.
+  Completing the full crew grants a modifier and unlocks rebellion decisions.
+- **Skaa Army arc** — decision to raise hidden levy in caves. Multi-year
+  building via events. Lord Ruler attention checks at each stage. Discovery =
+  army destroyed + attention spike. Success = war option unlocked.
+- **Noble House Infiltration arc** — spy scheme targeting noble courts. Ball
+  events where player chooses which house to approach. Rumor-spreading. Failure
+  risks cover being blown. Success undermines house alliances.
+- **Rebellion arc** — faction-style mechanic for skaa uprising. Builds over
+  time based on tyranny/crackdowns. Civil war trigger when conditions met.
+  Military confrontation with the Final Empire's forces.
+- **Kelsier's Martyrdom** — if Kelsier dies during the rebellion, his death
+  creates a Survivorism religious event. The rebellion strengthens (not ends).
+  Vin inherits leadership. A new religious icon appears in the faith.
+- All events gated by game rule (Narrative Mode only; Sandbox players get the
+  mechanical systems but not the scripted story beats)
+- Each arc needs: events, decisions, scripted triggers, scripted effects,
+  localization, on_action hooks
+
+**Key files:**
+- `events/` — new event files per arc (or expand existing ones)
+- `common/decisions/` — arc-triggering decisions
+- `common/scripted_effects/mistborn_effects.txt`
+- `common/scripted_triggers/mistborn_triggers.txt`
+- `common/on_action/mistborn_on_actions.txt`
+- `localization/english/mistborn_events_l_english.yml` — major expansion
+
+**Exit criteria:** Play as Kelsier from bookmark. Assemble the crew. Train the
+skaa army. Infiltrate noble society. Trigger the rebellion. Experience Kelsier's
+martyrdom. Vin takes over as leader. The core plot of Book 1 plays out.
+
+---
+
+### M7: The Deepness
+
+*All event arcs implemented. Deep Sanderson lore throughout.*
+
+**Scope:**
+- **Raids on Noble Houses** — hostile scheme/decision chain. Steal gold, reduce
+  county control, lower prestige. Escalating consequences if caught.
+- **The Eleventh Metal** — rare event chain for Mistborn/Augur characters.
+  Discover malatium. Reveals hidden information about powerful characters.
+  Grants intrigue advantage.
+- **Mistborn Duels in the Mists** — personal combat events. Metal-type specific
+  options (Coinshots get ranged, Thugs get endurance, Tineyes detect ambushes).
+- **Ball Assassination** — variant ball event with assassination attempt. Vin vs
+  Shan Elariel fight. Reveals hidden Mistborn status. Major political fallout.
+- **Political Intrigue** — false flag scheme (frame a third house). Atium
+  contract auction (houses bid prestige/gold). Obligator oversight events
+  (bribe/intimidate/accept). Skaa mistress scandal chain.
+- **Atium Economy** — atium supply modifier. Pits of Hathsin generation. Atium
+  contract as decision. Atium trading events. Atium as strategic resource.
+- **Fall of Kredik Shaw** — endgame event chain. Requires understanding of
+  Compounding. Must identify and remove Lord Ruler's atium bracers. Triggers
+  unique war where Lord Ruler becomes mortal. Victory collapses `e_final_empire`.
+  New era begins.
+- **Atmosphere & Flavor:**
+  - Ash falls — province events, ash blight modifier, clearing decisions
+  - The Mists — yearly encounters, Allomancer empowerment, skaa fear, rare
+    snapping triggers
+  - The Flower — rare positive morale event (hope in the ash)
+  - Sazed's Knowledge — Feruchemist learning events about lost religions and
+    history, coppermind mechanics
+  - Kandra Contracts — deepen kandra mechanics, impersonation events, Contract
+    obligations
+- Additional Sanderson lore events:
+  - Terris breeding program (Lord Ruler's suppression of Feruchemy)
+  - Obligator spy network flavor
+  - Skaa plantation life events
+  - Noble ball politics and gossip
+  - Koloss army events (uncontrollable berserkers)
+  - Steel Inquisitor encounters (terror events)
+  - Ashfall seasons affecting agriculture
+  - Deepness myths and Alendi's journal fragments
+
+**Key files:**
+- `events/` — many new event files
+- `common/schemes/` — expand with new scheme types
+- `common/decisions/` — atium decisions, endgame decisions
+- `common/modifiers/` — atium supply, ash blight, mist modifiers
+- `localization/english/` — massive expansion (hundreds of new keys)
+
+**Exit criteria:** All 13+ event arcs from `events.md` are implemented plus
+additional lore events. Play through the complete story including the Fall of
+Kredik Shaw. Atmosphere events fire regularly. The world feels deeply Mistborn.
+
+---
+
+### M8: The Art of Metals
+
+*Custom Scadrial map. Full graphics. Publication quality.*
+
+**Scope:**
+- **Custom Map:**
+  - Create `provinces.png` — Scadrial landmass with province borders matching
+    the Dominance structure. Central Dominance around Luthadel, Northern
+    (Urteau), Western (Fadrex), Eastern, Southern Dominances, Terris in the
+    north, Pits of Hathsin location.
+  - Create `definitions.csv` — province ID to RGB mapping
+  - Create `heightmap.bmp` — terrain elevation (Ashmounts as peaks, Central
+    Dominance as plains, Terris mountains in the north)
+  - Create `rivers.png` — River Channerel and tributaries
+  - Define terrain types, geographic regions, climate zones
+  - Remap all `province = XXXX` references in `00_landed_titles.txt`
+  - Rewrite province history files for new province IDs
+  - Extensive map testing (broken rivers and province borders crash CK3)
+- **Graphics:**
+  - Custom trait icons (`.dds` files) for all metallic arts traits — 12 Misting
+    types, Mistborn, Feruchemist, Hemalurgist, spike types, strength tiers,
+    potentials (~25-30 icons)
+  - Custom modifier icons for lord_ruler_attention, ruin_influence, ash_blight,
+    atium_supply, etc.
+  - Loading screen art (Luthadel skyline, mists, ashmounts)
+  - Bookmark art (Kelsier and Vin character portraits, the Final Empire backdrop)
+  - Decision icons for major decisions
+- **Portraits:**
+  - Custom ethnicity definitions for Scadrial cultures (noble_scadrian pale
+    skin, skaa darker features, terris dark skin per lore)
+  - Portrait modifiers for Hemalurgic spikes (eye spikes for Inquisitors)
+  - Ash-stained clothing/accessories
+- **Polish:**
+  - Balance pass on all mechanics — play multiple full campaigns
+  - Localization review — consistent tone, no typos, all keys present
+  - Error.log must be completely clean
+  - Performance check — no excessive event firing or script loops
+  - Community feedback integration (share with testers)
+
+**Key files:**
+- `map_data/` — new directory (provinces.png, heightmap.bmp, rivers.png,
+  definitions.csv, default.map, geographical_regions/)
+- `gfx/` — new directory (interface/icons/traits/, interface/icons/modifiers/,
+  loadingscreens/, portraits/)
+- `common/landed_titles/00_landed_titles.txt` — province remapping
+- `history/provinces/` — rewrite for new province IDs
+- All localization files — final review pass
+
+**Exit criteria:** The mod is publication quality. Custom Scadrial map looks
+good. All traits have custom icons. Loading screens show Mistborn art.
+Characters look like Scadrians. No errors. Ready for Steam Workshop.
+
+---
+
+## Dependency Map
+
+```
+M1 Foundation
+ └─► M2 Metallic Arts
+      └─► M3 The Final Empire
+           ├─► M4 Scadrial on the Map ──► (shareable v1)
+           └─► M5 The Crew
+                └─► M6 The Plan
+                     └─► M7 The Deepness
+                          └─► M8 The Art of Metals ──► (done)
+```
+
+M4 and M5 can run in parallel after M3. M6 depends on M5 (band system required
+for narrative arcs). M7 depends on M6 (extended arcs build on core narrative).
+M8 depends on M7 (all content must exist before final polish and map swap).
+
+---
+
+## Risks & Open Questions
+
+### Technical Risks
+
+1. **Lord Ruler as off-map entity.** CK3 does not have a clean off-map power
+   mechanic like EU4. Options: (a) immortal emperor holding `e_final_empire`,
+   made non-playable; (b) religious head via spiritual doctrine; (c) hidden
+   title + event-only interactions. The right approach affects the attention
+   system, rebellion arc, and endgame. Must be resolved in M3.
+
+2. **Vin as non-leader band member.** Roads to Power may not support playing as
+   a non-leader in an adventurer band. If not natively supported, Vin's gameplay
+   must be simulated via events and decisions (Kelsier as event-driven NPC when
+   playing Vin). Must be researched in M5.
+
+3. **Custom map stability.** Broken province borders or rivers crash CK3 hard.
+   Map work requires pixel-level accuracy and extensive testing. This is the
+   highest-risk single task in the project.
+
+4. **Vanilla content bleed-through.** Every vanilla decision, event, and name
+   that isn't suppressed breaks immersion. Total conversion requires systematic
+   suppression via empty replacement files. This is tedious but critical.
+
+5. **Roads to Power DLC dependency.** Friends without the DLC cannot play
+   Kelsier's crew. A non-DLC fallback (landed minor barony) must exist in M5.
+
+### Design Questions
+
+6. **Government type.** The Final Empire is not feudal — the Lord Ruler appoints
+   governors, Great Houses hold land by his grace. A custom government type in
+   `common/governments/` may be needed to restrict war declaration and modify
+   succession. Scope TBD in M3.
+
+7. **Succession laws.** Titles should not freely inherit by partition. The Lord
+   Ruler controls title distribution. Custom succession laws or realm laws may
+   be needed.
+
+8. **Era 2 metals.** The REVIEW_NOTES mention missing chromium, aluminum,
+   cadmium, and bendalloy traits. These are not known in the Final Empire era
+   per lore. Decision: omit them (lore-accurate) or include as ultra-rare
+   hidden knowledge.
+
+9. **Kandra depth.** Kandra are shapeshifters bound by Contracts. How deep
+   should this system go? A full kandra trait with impersonation mechanics, or
+   flavor events only?
+
+10. **Mod size and performance.** 13+ event arcs with hundreds of events, plus
+    atmosphere events on yearly pulses, could cause performance issues on slower
+    machines. Events should be gated efficiently.