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
    bookmarks/bookmarks/        # Bookmark definitions (CK3 nested convention)
    culture/                    # Cultures: noble_scadrian, skaa, terris
    decisions/                  # Player decisions (balls, snapping, breeding)
    dynasties/                  # 10 Great Houses
    dynasty_houses/
    landed_titles/              # Dominances and holdings
    men_at_arms_types/          # Hazekillers, Koloss, Mistborn Agents, etc.
    modifiers/                  # Character and province modifiers
    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
      religion_families/        # Religion family definitions (rf_scadrial)
    scripted_effects/           # Reusable effect blocks
    scripted_triggers/          # Reusable condition checks
    traits/                     # Allomancy, Feruchemy, Hemalurgy 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/
  lore/                         # Mistborn universe reference material
  bookmarks/                    # Story arc planning (characters, scenarios)
  ck3-modding/                  # CK3 modding reference

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

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 issues:

• Missing event files for several decisions (kandra, hemalurgy, atium, skaa)
• Missing modifier definitions (lord_ruler_attention tiers, ruin_influence, etc.)
• Missing traits for higher/Era 2 metals (chromium, aluminum, cadmium, bendalloy)
• Missing custom name lists for cultures

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.