Break the MASTERPLAN into 8 milestone documents (M1-M8) with a standard template. Each milestone includes prerequisites, current state assessment, numbered implementation tasks with file references, testing checkpoints, acceptance criteria, and risk analysis. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
27 KiB
M5: The Crew
Play as Kelsier's unlanded adventurer band. The "End of an Empire" bookmark works.
Prerequisites
- M3 (The Final Empire) must be complete:
- Canonical characters exist (Kelsier, Vin, Breeze, Ham, Clubs, Dockson, Marsh, Yeden, OreSeur, Elend, Straff Venture, Shan Elariel)
- Lord Ruler implemented as immortal emperor / religious head
- Custom name lists for all 3 cultures
- Special buildings (Kredik Shaw, Pits of Hathsin) in place
- Religions polished (Survivorism available as hidden faith)
- M1 (Foundation) game rule infrastructure exists in
common/game_rules/ - CK3 version 1.18.* with Roads to Power DLC mechanics understood
Current State
Bookmark (common/bookmarks/00_mistborn_bookmarks.txt): Defines
bm_end_of_an_empire with start date 1020.1.1. Currently lists 4 placeholder
landed noble characters (Devinshae Venture, Jordren Hasting, Trentohn Elariel,
Brodren Lekal). All use government = feudal_government. No unlanded/adventurer
characters exist.
Characters (history/characters/00_mistborn_characters.txt): Contains 30+
placeholder characters across Great Houses, Terris stewards, and skaa. None are
canonical Mistborn book characters (Kelsier, Vin, etc.). These were designated
for replacement in M3.
Decisions (common/decisions/00_mistborn_decisions.txt): 8 existing
decisions, all gated behind is_ruler = yes and landed requirements. No
crew-specific or adventurer-compatible decisions exist.
Game rules: No common/game_rules/ directory or files exist yet. The
Narrative/Sandbox toggle was scoped for M1 but the infrastructure is needed here.
On-actions (common/on_action/mistborn_on_actions.txt): Hooks for
on_birthday, on_yearly_pulse, on_game_start, on_birth. No hooks for
adventurer-specific events or death succession handling.
Implementation Tasks
5.1 -- Research and Document Adventurer Band Mechanics
Context: CK3's Roads to Power DLC (patch 1.13+) introduced the landless adventurer system. Before implementing Kelsier's crew, we must understand how the engine handles adventurer characters in history files, bookmarks, camp mechanics, and succession. This task produces a reference that subsequent tasks depend on.
Steps:
- Examine vanilla CK3 game files for adventurer bookmark definitions. Look at
how
government = adventurer_governmentis set in bookmarkcharacter {}blocks and in history files. Check the vanillagame/history/characters/andgame/common/bookmarks/directories for examples of landless adventurer starts (e.g., the vanilla 1178 bookmark has adventurer characters). - Document how camp followers / band members are defined. Determine whether
band members are specified in history files (e.g., via
employer = <id>or similar), or created viaon_game_startscripted effects. - Determine how adventurer succession works when the band leader dies. Check
if there is a vanilla
on_actionhook (such ason_deathoron_title_lost) that handles adventurer leadership transfer, or if a custom event is needed. - Test whether a non-leader band member can be a playable bookmark character. If not, document the limitation and note that Vin's playability requires either (a) Vin as a separate bookmark start who becomes leader immediately via event, or (b) Vin only becomes playable after Kelsier's death.
- Document how decisions scope to adventurer characters (i.e., what replaces
is_ruler = yes/any_held_titlechecks for unlanded characters). Adventurers may useis_landless_adventurer = yesor similar trigger. - Write findings to
docs/ck3-modding/adventurer-bands.mdas a reference doc for the team.
Files:
docs/ck3-modding/adventurer-bands.md-- create
References:
- Vanilla CK3
game/common/bookmarks/-- adventurer bookmark examples - Vanilla CK3
game/common/governments/--adventurer_governmentdefinition - Vanilla CK3
game/history/characters/-- adventurer character history syntax - CK3 Wiki: Adventurer page, Bookmarks modding page
- CK3 AGOT mod (uses adventurer bands extensively) for patterns
5.2 -- Implement Game Rule Toggle (Narrative vs Sandbox)
Context: The game rule toggle controls whether curated story events fire (Narrative Mode) or the player gets a freeform experience (Sandbox Mode). This must exist before M6 events can be gated. The game rule also determines which bookmark characters are recommended.
Steps:
- Create
common/game_rules/00_mistborn_game_rules.txtwith amistborn_game_moderule:mistborn_game_mode = { default = mistborn_narrative_mode mistborn_narrative_mode = { # Curated events fire, Kelsier/Vin recommended } mistborn_sandbox_mode = { # Narrative events suppressed, any character playable # "Discover Your Metallic Arts" decision available } } - Create the scripted trigger
is_narrative_mode_triggerincommon/scripted_triggers/mistborn_triggers.txt:is_narrative_mode_trigger = { has_game_rule = mistborn_narrative_mode } - Create the inverse trigger
is_sandbox_mode_triggerin the same file. - Add localization keys to a new file
localization/english/mistborn_game_rules_l_english.yml:mistborn_game_mode:0 "Game Mode"mistborn_game_mode_desc:0 "Choose between Narrative Mode..."mistborn_narrative_mode:0 "Narrative Mode"mistborn_narrative_mode_desc:0 "Play through the story of..."mistborn_sandbox_mode:0 "Sandbox Mode"mistborn_sandbox_mode_desc:0 "Play any character freely..."
- Verify the game rule appears on the game setup screen during boot test.
Files:
common/game_rules/00_mistborn_game_rules.txt-- createcommon/scripted_triggers/mistborn_triggers.txt-- modify (add 2 triggers)localization/english/mistborn_game_rules_l_english.yml-- create
References:
- Vanilla CK3
game/common/game_rules/for syntax patterns - Existing triggers in
common/scripted_triggers/mistborn_triggers.txt:1-134
5.3 -- Define Kelsier's Crew as Adventurer Band
Context: Kelsier's thieving crew is the core playable unit. In Roads to Power, an adventurer band is a group led by a landless character with camp followers. This task creates the crew in the history files with appropriate traits, relationships, and government type.
Steps:
-
In
history/characters/00_mistborn_characters.txt, add crew member character definitions. Reserve character IDs 900100-900119 for the crew. All crew members useculture = "skaa"(except Sazed who is"terris"and Breeze who is"noble_scadrian"per lore -- half-noble). All usereligion = "steel_ministry"as the default public religion (Sazed uses"terris_worldbringers"secretly). Characters to define:ID Name Key Traits Notes 900100 Kelsier trait_mistborn,brave,ambitious,scarred(usewounded_1or custom),education_intrigue_4Band leader. Born ~985, survived Pits of Hathsin. Scarred arms (Pits brands). Wife Mare is dead. 900101 Vin trait_allomantic_potential(pre-snap) ORtrait_mistborn(post-snap),paranoid,shy,education_intrigue_2Age ~16 at start (born ~1004). No dynasty initially. Should snap early via event. 900102 Breeze trait_misting_soother,gregarious,deceitful,education_diplomacy_3Noble-born (half-noble). Real name Ladrian. Sophisticated. 900103 Ham trait_misting_thug,brave,honest,education_martial_3Philosophical soldier. Strong. 900104 Clubs trait_misting_smoker,cynical,content,education_intrigue_3Gruff veteran. Older (~60). Provides Allomantic cover. 900105 Dockson No Allomancy, diligent,patient,education_stewardship_3Organizer and planner. Kelsier's oldest friend. 900106 Marsh trait_misting_seeker,zealous,just,education_learning_3Kelsier's brother. Later becomes Inquisitor (M6/M7). 900107 Yeden No Allomancy, brave,zealous,craven,education_martial_1Skaa rebel leader. Provides army connection. Dies in the book. 900108 OreSeur trait_kandra(from M3),patient,contentKandra spy. Bound by Contract to Kelsier. -
Set Kelsier's government to
adventurer_governmentin the history file date block (syntax TBD from 5.1 research -- may requiregovernment = "adventurer_government"at the 1020.1.1 date entry, or set via effect). -
Link crew members to Kelsier's band. Based on 5.1 research, this may use
employer = 900100in each member's history, or require anon_game_starteffect to add them to Kelsier's court/camp. -
Create an
on_game_starteffect block incommon/on_action/mistborn_on_actions.txtthat:- Verifies Kelsier exists and is adventurer
- Adds all crew members to his band/court if not already there
- Sets Vin as Kelsier's player_heir (for succession)
- Initializes crew-tracking variables on Kelsier:
set_variable = { name = crew_assembled value = 0 } - If Narrative Mode: triggers the opening crew assembly event chain
-
Ensure Kelsier has appropriate starting resources: gold (~200), prestige (~100), and reasonable stats (diplomacy ~8, martial ~10, stewardship ~6, intrigue ~14, learning ~8, prowess ~18).
Files:
history/characters/00_mistborn_characters.txt-- modify (add crew block)common/on_action/mistborn_on_actions.txt-- modify (expandon_game_start)history/titles/00_mistborn_titles.txt-- possibly modify (if adventurer needs a camp title assignment)
References:
- Existing character definitions:
history/characters/00_mistborn_characters.txt:1-744 - Lore reference:
docs/lore/mistborn-universe.md(crew member details) docs/ck3-modding/adventurer-bands.md(from task 5.1)
5.4 -- Update the Bookmark Definition
Context: The "End of an Empire" bookmark must be rewritten to feature Kelsier and Vin as primary recommended characters, with 1-2 landed noble starts as alternatives. The bookmark must correctly reference adventurer characters.
Steps:
-
Rewrite
common/bookmarks/00_mistborn_bookmarks.txt. The new bookmark should have 4 characters:bm_end_of_an_empire = { start_date = "1020.1.1" is_playable = yes recommended = yes weight = { value = 100 } # Kelsier - Crew Leader (Adventurer) character = { name = bm_kelsier history_id = 900100 dynasty = 0 # or a custom dynasty type = male birth = "985.1.1" government = adventurer_government culture = skaa religion = steel_ministry difficulty = "medium" position = { 500 350 } # Near Luthadel animation = personality_bold } # Vin - Crew Member (if non-leader play supported) # OR marked as "heir" in Kelsier's description character = { name = bm_vin history_id = 900101 type = female birth = "1004.6.1" government = adventurer_government culture = skaa religion = steel_ministry difficulty = "hard" position = { 500 360 } animation = personality_cynical } # Elend Venture - Landed Noble Start character = { name = bm_elend_venture history_id = <elend_id> # from M3 characters dynasty = dynasty_venture dynasty_splendor_level = 4 type = male birth = "1000.1.1" title = <appropriate_title> government = feudal_government culture = noble_scadrian religion = steel_ministry difficulty = "easy" position = { 500 350 } animation = personality_rational } # Straff Venture - Great House Lord character = { name = bm_straff_venture history_id = <straff_id> # from M3 characters dynasty = dynasty_venture dynasty_splendor_level = 4 type = male birth = "965.1.1" title = k_central government = feudal_government culture = noble_scadrian religion = steel_ministry difficulty = "easy" position = { 520 340 } animation = personality_bold } } -
If 5.1 research shows that non-leader band members cannot be bookmark characters, remove Vin from the bookmark character list and instead:
- Add a note in Kelsier's description: "Vin becomes playable upon Kelsier's death"
- OR create Vin as a separate single-character adventurer who joins Kelsier's crew via the opening event
-
Add bookmark localization to
localization/english/mistborn_bookmarks_l_english.yml:bm_kelsier:0 "Kelsier"(and_desc)bm_vin:0 "Vin"(and_desc)bm_elend_venture:0 "Elend Venture"(and_desc)bm_straff_venture:0 "Straff Venture"(and_desc)- Update
bm_end_of_an_empire_descto reference the rebellion plot
-
Write evocative character descriptions for the bookmark screen. Kelsier's should reference the Pits, the crew, and the plan to overthrow the Lord Ruler. Vin's should reference her street upbringing, hidden power, and paranoia. Elend's should reference his bookish nature and reformist ideals.
Files:
common/bookmarks/00_mistborn_bookmarks.txt-- rewritelocalization/english/mistborn_bookmarks_l_english.yml-- rewrite
References:
- Current bookmark:
common/bookmarks/00_mistborn_bookmarks.txt:1-90 - Current bookmark localization:
localization/english/mistborn_bookmarks_l_english.yml:1-24 - Vanilla CK3 bookmark files for adventurer character syntax
5.5 -- Implement Kelsier Death / Vin Succession Mechanic
Context: A core mechanic: when Kelsier dies (especially during the rebellion in M6), leadership passes to Vin. This is both a game mechanic (player_heir / succession) and a narrative moment (martyrdom). This task sets up the mechanical framework; M6 adds the narrative events.
Steps:
- Create a new event file
events/crew_events.txtwith namespacemistborn_crew. - Add an
on_deathhook incommon/on_action/mistborn_on_actions.txt:on_death = { events = { mistborn_crew.1000 # Kelsier death succession check } } - Implement
mistborn_crew.1000-- a hidden event that fires on any character's death. Trigger condition: the dying character is Kelsier (character ID 900100) OR has the flagis_crew_leader. The event:- Finds Vin (900101) or the designated heir
- If Vin exists and is alive:
- Transfers band leadership to Vin (via
make_adventurer_band_leaderor equivalent effect -- syntax TBD from 5.1) - Sets
has_character_flag = kelsier_martyredon Vin - Triggers
mistborn_crew.1001on Vin (the player-facing succession notification event)
- Transfers band leadership to Vin (via
- If Vin is dead, fall through to next eligible crew member
- Implement
mistborn_crew.1001-- player-facing event for Vin:- Title: "The Survivor Falls"
- Description: Kelsier is dead. The crew looks to Vin for leadership.
- Option A: "I will carry on his work." (gain prestige, lose stress,
set
has_character_flag = accepted_leadership) - Option B: "I'm not ready for this." (gain stress, still becomes leader,
but with a temporary negative modifier
reluctant_leader)
- Add localization for
mistborn_crew.1000andmistborn_crew.1001tolocalization/english/mistborn_events_l_english.yml.
Files:
events/crew_events.txt-- createcommon/on_action/mistborn_on_actions.txt-- modify (addon_deathblock)localization/english/mistborn_events_l_english.yml-- modify
References:
- Death event patterns:
events/lord_ruler_events.txt(death handling) - On-action hooks:
common/on_action/mistborn_on_actions.txt:1-119 docs/ck3-modding/adventurer-bands.md(from task 5.1 -- succession mechanics)
5.6 -- Create Crew-Specific Decisions
Context: The crew needs unique decisions that work for unlanded adventurer
characters. These decisions drive the gameplay loop before M6's narrative arcs
take over. They must not require is_ruler = yes with landed title checks.
Steps:
-
Create
common/decisions/01_crew_decisions.txtwith the following decisions:Recruit a Crew Member (
recruit_crew_member_decision):is_shown: characterhas_character_flag = is_crew_leaderANDis_narrative_mode_trigger = yesAND crew is incomplete (var:crew_assembled < 8)is_valid: gold >= 25, appropriate skill check based on which member is nextcost: gold = 25, prestige = 10cooldown: 60 dayseffect: triggersmistborn_crew.0001(recruitment event chain -- see M6 for full implementation; this task creates a placeholder that incrementscrew_assembled)
Plan the Next Operation (
plan_operation_decision):is_shown:has_character_flag = is_crew_leaderANDvar:crew_assembled >= 4(minimum crew size)is_valid: NOThas_character_flag = operation_in_progresscost: prestige = 25cooldown: 90 dayseffect: presents a menu event (mistborn_crew.0010) with branching options:- "Train the Skaa Army" -> sets flag, triggers skaa army arc (M6)
- "Infiltrate the Noble Houses" -> sets flag, triggers infiltration arc (M6)
- "Raid a Noble House" -> sets flag, triggers raid arc (M7)
- "Lay Low" -> reduces Lord Ruler attention by 10, adds 180-day cooldown
Lay Low (
lay_low_decision):is_shown:has_character_flag = is_crew_leaderis_valid: NOThas_character_flag = recently_laid_lowcost: gold = 50cooldown: 1 yeareffect:- Decrease
lord_ruler_attentionby 10 (using existingdecrease_lord_ruler_attention_effect) - Add temporary modifier
laying_low(reduces prestige gain, increases stewardship for crew management) - Set flag
recently_laid_lowfor 1 year
- Decrease
-
Create a scripted trigger
is_crew_leader_triggerincommon/scripted_triggers/mistborn_triggers.txt:is_crew_leader_trigger = { has_character_flag = is_crew_leader } -
Create a scripted trigger
is_crew_member_trigger:is_crew_member_trigger = { has_character_flag = is_crew_member } -
Add the
laying_lowmodifier tocommon/modifiers/00_mistborn_modifiers.txt:laying_low = { monthly_prestige = -0.5 stewardship = 2 hostile_scheme_resistance_mult = 0.2 } -
Add localization for all 3 decisions plus the modifier to
localization/english/mistborn_decisions_l_english.yml:- Decision names, descriptions, tooltips, confirm text (4 keys each x 3)
laying_low:0 "Laying Low"
Files:
common/decisions/01_crew_decisions.txt-- createcommon/scripted_triggers/mistborn_triggers.txt-- modifycommon/modifiers/00_mistborn_modifiers.txt-- modifylocalization/english/mistborn_decisions_l_english.yml-- modify
References:
- Existing decision patterns:
common/decisions/00_mistborn_decisions.txt:1-627 - Existing attention effects:
common/scripted_effects/mistborn_effects.txt:44-99 - Existing modifiers:
common/modifiers/00_mistborn_modifiers.txt:1-154
5.7 -- Implement Non-DLC Fallback
Context: Players without the Roads to Power DLC cannot use the adventurer
government. A fallback must exist where Kelsier starts as a landed minor lord
of a Luthadel slum barony (b_luthadel_slums, province 2048).
Steps:
- Add a DLC detection trigger to
common/scripted_triggers/mistborn_triggers.txt:Note: verify the exact DLC string by checking vanilla game files. It may behas_roads_to_power_trigger = { has_dlc = "Roads to Power" }"Roads to Power"or a different identifier. - In the
on_game_starteffect block (from 5.3), add a conditional branch:- If Roads to Power is NOT active AND the player is Kelsier:
- Grant
b_luthadel_slumstitle to Kelsier - Set
government = feudal_government(ortribal_governmentfor a more thematic "slum lord" feel) - Add crew members as courtiers to Kelsier's court
- Grant
- If Roads to Power IS active:
- Proceed with adventurer band setup as normal
- If Roads to Power is NOT active AND the player is Kelsier:
- In the bookmark definition, add a
dlc_requirementblock if the engine supports it, or add a tooltip note in the character description warning that the full experience requires Roads to Power. - Ensure crew decisions from 5.6 work for both landed and unlanded Kelsier.
Update
is_shownblocks to use OR conditions:is_shown = { OR = { is_landless_adventurer = yes AND = { is_ruler = yes has_character_flag = is_crew_leader } } }
Files:
common/scripted_triggers/mistborn_triggers.txt-- modifycommon/on_action/mistborn_on_actions.txt-- modifycommon/decisions/01_crew_decisions.txt-- modify (adjustis_shownblocks)
References:
- Landed titles:
common/landed_titles/00_landed_titles.txt:38-42--b_luthadel_slumsat province 2048 - DLC detection patterns in vanilla CK3 game files
Testing Checkpoints
-
After 5.1: Research document exists. Team has clear understanding of adventurer band syntax. Key questions (non-leader play, band member linkage, succession) are answered.
-
After 5.2: Boot the mod. The game rule "Game Mode" appears on the setup screen with Narrative Mode and Sandbox Mode options. Selecting either does not cause errors. The
is_narrative_mode_triggerreturns true when Narrative Mode is selected (verify via console:event mistborn_crew.debug_mode_checkor similar debug event). -
After 5.3 + 5.4: Start a new game using the "End of an Empire" bookmark. Kelsier appears as a selectable character. Select Kelsier and begin the game. Verify:
- Kelsier has
trait_mistborn, correct personality traits, reasonable stats - All 8 crew members exist in his band/court
- Vin has
trait_allomantic_potential(pre-snap) ortrait_mistborn - Kelsier's government is
adventurer_government - No error.log entries related to missing characters or bad scopes
- Kelsier has
-
After 5.5: Use the console to kill Kelsier (
kill 900100). Verify:- The succession event fires for Vin
- Vin becomes the new band leader / playable character
- The player can continue playing as Vin
- The
kelsier_martyredflag is set on Vin
-
After 5.6: As Kelsier, verify:
- "Recruit a Crew Member" decision appears and functions
- "Plan the Next Operation" decision appears (once crew >= 4)
- "Lay Low" decision reduces lord_ruler_attention
- All decisions have correct localization (no raw keys visible)
-
After 5.7: Disable the Roads to Power DLC (or simulate DLC absence). Start the game as Kelsier. Verify:
- Kelsier holds
b_luthadel_slums - Crew members are courtiers
- Crew decisions still function
- Game is playable without crashes
- Kelsier holds
Acceptance Criteria
- The "End of an Empire" bookmark shows Kelsier and Vin as recommended characters, plus at least one landed noble alternative (Elend or Straff Venture).
- Selecting Kelsier starts the game with him as an unlanded adventurer band leader (Roads to Power) or as a landed slum lord (non-DLC fallback).
- All 8 named crew members (Vin, Breeze, Ham, Clubs, Dockson, Marsh, Yeden, OreSeur) exist in Kelsier's band/court at game start.
- The game rule toggle (Narrative Mode / Sandbox Mode) appears on the setup screen and can be selected without errors.
- When Kelsier dies, Vin inherits band leadership and becomes the playable character via a succession event.
- Three crew-specific decisions are available: Recruit a Crew Member, Plan the Next Operation, and Lay Low. Each has correct localization.
- The Lay Low decision reduces Lord Ruler attention using the existing variable-based system.
- The mod boots cleanly with no errors in error.log related to M5 content.
- Playing as Kelsier for 5 years without triggering M6 narrative content does not produce errors or broken states.
Risks & Mitigations
-
Adventurer band member linkage is unclear. The exact syntax for assigning band members in history files may differ from courtier assignment. Mitigation: Task 5.1 is dedicated research. If history-file linkage is not possible, use
on_game_starteffects to recruit members dynamically. -
Non-leader band member is not playable. CK3 may not support selecting a non-leader band member as a bookmark character. Mitigation: If confirmed, Vin's bookmark entry is removed and she becomes playable only after Kelsier's death (which is thematically appropriate -- the book's perspective shift). Alternatively, create Vin as an independent adventurer who joins Kelsier's crew on day 1 via event.
-
Adventurer government breaks existing triggers. Many existing triggers and decisions use
is_ruler = yeswhich may or may not apply to adventurer band leaders. Mitigation: Audit all existing triggers in 5.7 and addis_landless_adventureralternatives where needed. -
DLC detection string is wrong. The exact DLC name string may differ from
"Roads to Power". Mitigation: Check vanilla game files for the correct string during 5.1 research. Test with and without the DLC. -
Crew characters conflict with M3 canonical characters. M3 creates canonical characters (Kelsier, Vin, etc.) in the same file. ID ranges must not overlap. Mitigation: Use the reserved 900100-900119 range, which is well above the existing 900001-900091 range.
Open Questions
-
Can a non-leader band member be a bookmark character? This determines whether Vin is directly selectable at the bookmark screen or only playable after Kelsier's death. Research in 5.1 should resolve this.
-
What is the exact DLC detection string for Roads to Power? Need to verify from vanilla game files. Might be
"Roads to Power","ep3", or similar. -
How does adventurer band succession work mechanically? Is there a built-in mechanic for designating an heir within a band, or must we script it entirely via on_death events?
-
Should Kelsier have a custom dynasty? In the books, "Kelsier" is his surname. He could have dynasty
dynasty_kelsieror be dynastyless (usingdynasty = 0). The crew could share a synthetic dynasty "Kelsier's Crew" for mechanical purposes. -
Camp buildings for the crew. If adventurer camps support custom buildings, should we create thematic ones (Smoker's Den for Clubs, Training Ground for Ham, etc.)? This could be deferred to M7 polish.
-
Vin's starting state. Should Vin start with
trait_allomantic_potential(pre-snap, allowing the player to experience her snapping) ortrait_mistborn(post-snap, gameplay-ready from day 1)? The book has her snap before meeting Kelsier, but she does not know what she is. Recommendation: start withtrait_allomantic_potentialand trigger a special snapping event within the first few days of gameplay.