lords-of-ash/CLAUDE.md

Lords of Ash — Mistborn: The Final Empire CK3 Mod

A Crusader Kings III total conversion mod set in Brandon Sanderson's Mistborn universe during the Final Empire era. CK3 version 1.18.*.

Project Structure

lords_of_ash/          # The mod itself (CK3 mod directory)
  common/                       # Game data definitions
    artifacts/                  # Artifact types, slots, visuals (9 Mistborn artifacts)
    bookmark_portraits/         # Portrait overrides for bookmark characters
    bookmarks/bookmarks/        # Bookmark definitions (CK3 nested convention)
    buildings/                  # Special buildings (Kredik Shaw, Pits, Conventical)
    character_interactions/      # Inquisitor interactions (investigate, interrogate)
    culture/                    # Cultures: noble_scadrian, skaa, terris
      name_lists/               # Custom name lists per culture
    deathreasons/               # Custom Mistborn death causes
    decisions/                  # Player decisions (balls, snapping, breeding, crafting)
    dynasty_legacies/           # Universal + house-specific legacy trees
    dynasties/                  # 10 Great Houses + Rashek + Terris Stewards
    dynasty_houses/
    education/                  # Custom education focuses (5 Mistborn tracks)
    game_rules/                 # Narrative/Sandbox mode toggle
    holy_orders/                # Steel Inquisitor order, Keeper Network
    landed_titles/              # Dominances and holdings
    men_at_arms_types/          # Hazekillers, Koloss, Mistborn Agents, Inquisitor Squad
    modifier_icons/             # Modifier icon path definitions (DDS indirection)
    modifiers/                  # Character and province modifiers
    nicknames/                  # Custom Mistborn nicknames
    on_action/                  # Game hooks (birthday, yearly pulse, game start)
    opinion_modifiers/          # Opinion modifiers (e.g., disapproves_skaa_mercy)
    religion/                   # Steel Ministry, Terris, Survivorism, Cult of Ruin
      doctrines/                # Custom Scadrial doctrines and tenets
      holy_sites/               # 10 faith-differentiated holy sites
      religion_families/        # Religion family definitions (rf_scadrial)
    scripted_effects/           # Reusable effect blocks
    scripted_triggers/          # Reusable condition checks
    traits/                     # Allomancy, Feruchemy, Hemalurgy, Kandra, Education traits
  events/                       # Event chains (snapping, balls, Lord Ruler, etc.)
  history/                      # Starting characters and title holders
  localization/english/         # All display strings (l_english.yml)
lords-of-ash.mod       # Outer mod descriptor (has path field)
docs/
  bookmarks/                    # Story arc planning (characters, scenarios)
  ck3-modding/                  # CK3 modding reference
  lore/                         # Mistborn universe reference material
  milestones/                   # M1–M8 milestone specs and acceptance criteria
  events-registry.md            # Catalog of ~112 proposed flavor events
  IDEAS.md                      # Lightweight ideas tracker
  REQUIRED_ASSETS.md            # Visual asset inventory and specs (~230+ assets)
  TESTING.md                    # Testing protocol, debug decisions, validation scripts

CK3 Modding Conventions

File Naming

• Prefix data files with 00_ for load order: 00_allomancy_traits.txt
• Event files use descriptive names: snapping_events.txt, ball_events.txt
• Localization files: mistborn_<category>_l_english.yml

Trait Naming

Traits use the trait_ prefix consistently:

• Misting traits: trait_misting_<name> (e.g., trait_misting_coinshot, trait_misting_lurcher)
• Mistborn: trait_mistborn
• Potential: trait_allomantic_potential
• Feruchemy: trait_feruchemist, trait_feruchemical_potential
• Hemalurgy: trait_hemalurgist, trait_hemalurgic_spike_<type>
• Strength: trait_allomantic_strength_weak, _strong, _savant

Scripted Triggers/Effects Naming

• Triggers end with _trigger: is_allomancer_trigger, is_mistborn_trigger
• Effects end with _effect: activate_allomancy_effect

Event Namespaces

• mistborn_snapping — Allomantic awakening events
• mistborn_ball — Noble ball social events
• mistborn_lord_ruler — Lord Ruler attention/interaction
• mistborn_misc — General events (kandra, misc)
• mistborn_hemalurgy — Hemalurgy events
• mistborn_atium — Atium economy events
• mistborn_skaa — Skaa population events
• mistborn_skaa_allomancer — Skaa Allomancer discovery/recruitment
• mistborn_inquisitor — Steel Inquisitor interactions and events
• mistborn_keeper — Keeper Network events
• mistborn_education — Custom education track events

Localization

• All keys must be in l_english files with BOM encoding
• Key format: <namespace>_<identifier>:<digit> "Display text"
• Every trait, event, decision, title, and modifier needs a localization entry

Core Mod Systems

Allomancy

Genetic trait system. Characters carry trait_allomantic_potential (dormant) until "snapped" through trauma, which activates a specific Misting type or (rarely) full Mistborn. Inheritance chances are coded in trait definitions.

Lord Ruler Attention

Variable-based tracking system (0–100). Actions that defy the Lord Ruler increase attention; consequences escalate through tiers.

Compounding

When a character has both an Allomantic and Feruchemical trait for the same metal, compounding checks fire on the yearly pulse.

Known Issues

See lords_of_ash/REVIEW_NOTES.txt for the full review. Key open issues:

• No custom map data — mod reuses vanilla Swiss provinces (NOTE-02, planned for M8)
• Vanilla dependencies remain for ethoses, traits, and GFX (WARNING-02/03/04)

Committing

Always use the /commit skill when committing changes. Never commit without invoking it — it enforces conventional commit format, logical grouping, and changelog maintenance.

Skills

Always create skills in project scope (.claude/skills/) for this project, not in user scope (~/.claude/skills/).

Lore Reference

docs/lore/mistborn-universe.md — High-level setting, metallic arts, cosmic forces, organizations, and themes. Consult this for lore accuracy when writing events or designing new mechanics.